Skip to content

feat(ports): add ports command to list and check host port bindings#514

Open
jongio wants to merge 1 commit into
mainfrom
idea/ports
Open

feat(ports): add ports command to list and check host port bindings#514
jongio wants to merge 1 commit into
mainfrom
idea/ports

Conversation

@jongio

@jongio jongio commented Jul 13, 2026

Copy link
Copy Markdown
Owner

What

Adds azd app ports, a read-only command that lists the host port each service binds, resolved from azure.yaml.

For every service it prints each binding as host -> container/protocol. An explicit host port shows as its number; a port left for the runtime to assign shows as auto. When two bindings claim the same explicit host port, the command marks the conflict, prints a warning, and exits non-zero. That makes it a quick preflight check before azd app run and lets it gate a pipeline in CI.

Why

There is no fast way to see, across all services, which host ports are claimed and whether two services collide on the same one until run fails to bind. Listing the resolved ports up front, and failing on duplicate explicit bindings, catches the collision before startup.

Usage

# List host ports for every service
azd app ports

# JSON object keyed by service name
azd app ports --output json

Text output:

web
  port: 3000 -> 8080/tcp  (conflict)
worker
  port: 3000 -> 9090/tcp  (conflict)

Host port 3000 is bound by more than one service: web, worker

Details

  • Reuses the existing port model (GetPortMappings, ParsePortSpec) so protocol suffixes, ip:host:container forms, and Docker auto-assign all resolve the same way run sees them.
  • Only explicit host ports can conflict; auto-assigned ports never count, since the runtime picks a free port for each.
  • Conflicts are detected across services and within a single service, deduped by owner, and sorted by port for stable output.
  • JSON mode prints an object keyed by service name for programmatic use.

Tests

Table-driven unit tests cover the basic report, cross-service conflict, auto ports never conflicting, intra-service duplicate, UDP protocol, JSON shape, and the conflict summary and helper functions.

Verification

  • go build ./... clean
  • go vet ./src/cmd/app/commands/... clean
  • go test ./src/cmd/app/commands/ clean
  • golangci-lint run ./src/cmd/app/commands/... reports 0 issues

Closes #509

Add `azd app ports` to list the host port each service binds, resolved
from azure.yaml. Explicit host ports show as their number, auto-assigned
ports show as `auto`, and duplicate explicit bindings are flagged with a
warning and a non-zero exit so it works as a preflight check before run.

Reuses the existing port model (GetPortMappings/ParsePortSpec) so protocol
suffixes, ip:host:container forms, and Docker auto-assign resolve the same
way run sees them. Adds table-driven unit tests and docs.

Closes #509

Co-authored-by: Copilot App <[email protected]>
@jongio jongio added the idea Feature idea from the idea pipeline label Jul 13, 2026
@jongio jongio self-assigned this Jul 13, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

idea Feature idea from the idea pipeline

Projects

None yet

Development

Successfully merging this pull request may close these issues.

Add azd app ports command to list host ports and flag conflicts

1 participant