Initial support for port mapping in CLI

[AmelBawa-msft]

Summary of the Pull Request

🦞 Port mapping parser

Parser support examples:

✅ Valid (parsing)

 --- IP not specified ---
-p 8080:80
-p 443:443
-p 80
-p 80/tcp
-p 53/udp

# --- IPv4 specified ---
-p 127.0.0.1:8080:80
-p 0.0.0.0:8080:80
-p 192.168.1.50:8080:80
-p 127.0.0.1:5353:5353/udp
-p 127.0.0.1::80
-p 127.0.0.1::53/udp

# --- IPv6 specified ---
-p '[::1]:8080:80'
-p '[::]:8080:80'
-p '[2001:db8::10]:8080:80'
-p '[::1]:5353:5353/udp'
-p '[::1]::80'
-p '[::]::53/udp'

# --- Protocol not specified (defaults to tcp) ---
-p 9090:90
-p 127.0.0.1:9090:90
-p '[::1]:9090:90'

# --- Both tcp and udp (separate publishes) ---
-p 53:53/tcp
-p 53:53/udp
-p 5000:5000/tcp
-p 5000:5000/udp

# --- Port ranges ---
-p 8000-8005:8000-8005
-p 127.0.0.1:9000-9003:9000-9003
-p '[::1]:7000-7002:7000-7002'
-p 10000-10010:10000-10010/tcp
-p 20000-20002:20000-20002/udp

❌ Invalid (parsing)

# Malformed IP/container combinations
-p 127.0.0.1:80
-p '[::1]:8080'

# Port range mismatches
-p 8000-8005:8000-8006
-p 8000-8005:8000
-p 8000:8000-8005

# Bad protocol
-p 8080:80/icmp
-p 8080:80/udpp

# IPv6 without brackets
-p ::1:8080:80

🦐 Full example

# Example 1: HOST_PORT:CONTAINER_PORT
# (host port) 8080 => (container port) 80
wslc container run -p 8080:80 -it --name demo nginx:alpine

PR Checklist

• Closes: Link to issue #xxx
• Communication: I've discussed this with core contributors already. If work hasn't been agreed, this work might be rejected
• Tests: Added/updated if needed and all pass
• Localization: All end user facing strings can be localized
• Dev docs: Added/updated if needed
• Documentation updated: If checked, please file a pull request on our docs repo and link it here: #xxx

Detailed Description of the Pull Request / Additional comments

Validation Steps Performed

[dkbennett]

I have a meta comment before we go too far down the argument validation path. We have two types of arguments in the CLI:

1. Arguments directly consumed by the CLI to change its behavior (progress settings, output, logging, settings specific to the CLI, etc)
2. Arguments that are generally passed on to the service or another component, such as the operating system.

@OneBlue recommended that our general approach for argument validation for arguments to the service is that we should pass the argument along to the service with as little modification as possible, and if it's bad input the service will return error messages that we can surface to the user. I completely agree with this approach and believe it should apply to everything not just the service.

I would prefer not to have rigid validation of arguments in the CLI unless it's a type 1 argument specific to the CLI or some minimum parsing needs to be done in order to put the data into a form the service can consume (converting a string to two integers, for example).

The port validation is something I would expect the service to handle and I am generally concerned about the CLI parsing the port data argument differently from the service. I am strongly in favor of only validating the bare minimum needed to make it valid input to the service and let the service tell us if its inputs were invalid.

So the general guidance for argument validation should be: "Is something else already validating or going to validate this?" If the answer is yes, then the CLI should only validate it enough to get it to that validator and then rely on that validator to do its job correctly.

[AmelBawa-msft]

@dkbennett great observation and feedback, thank you! I have a couple of questions before marking this PR as ready, one of which you touched on, and another related to what we currently support.

This PR contains the necessary pieces to light up the feature, but I’ve held off on marking it ready to avoid duplicating service logic and to clarify how certain parts of the syntax should be handled. Some aspects may require follow-up work with the runtime team. I will sync up today with the team for suggestions on the next step.

Excited to see this feature finally available 🚀🙌

[Copilot]

Pull request overview

This PR adds initial support for port mapping in the WSLC CLI, implementing the -p/--publish flag for the wslc container run and wslc container create commands. The implementation includes a comprehensive port mapping parser that supports various formats including IPv4/IPv6 addresses, port ranges, and protocol specifications (TCP/UDP).

Changes:

• Adds PublishPort parser with support for formats like [host-ip:][host-port:]container-port[/protocol], including IPv6 addresses in brackets and port ranges
• Integrates port mapping into CLI commands with -p/--publish argument
• Implements ephemeral port allocation using socket binding when host port is not specified

Reviewed changes

Copilot reviewed 5 out of 5 changed files in this pull request and generated 11 comments.

Show a summary per file

File	Description
src/windows/wslc/ContainerModel.h	Adds PublishPort class with nested PortRange and IPAddress structs for parsing port mapping specifications
src/windows/wslc/ContainerModel.cpp	Implements parsing logic for port mappings, IP addresses, and port ranges with validation
src/windows/wslc/ContainerService.cpp	Adds ResolveOrAllocatePort function for ephemeral port allocation and integrates port mapping into container creation
src/windows/wslc/ContainerCommand.h	Adds -p/--publish flag to container run and create commands with help text
src/windows/wslc/CMakeLists.txt	Adds ContainerModel.cpp to build configuration

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 10 comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 6 comments.

[Copilot]

Pull request overview

Copilot reviewed 9 out of 9 changed files in this pull request and generated 3 comments.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 2 comments.

[OneBlue]

The CLI doesn't need to parse this since this will be done in the service (same for IPV4)

[AmelBawa-msft]

We use this information to determine if the IP is v4 or v6. But if the service will handle this, we can possibly reduce this to checking for just [ and ]?

[OneBlue]

Yeah I think just relying on the bracket syntax is the right move for now

[AmelBawa-msft]

One interesting use case I came across is:

::1:8080:80

After the refactor PR is merged, the CLI will pass:

AddPort(8080, 80, AF_INET, "::1")

Notice that AF_INET is used instead of AF_INET6 because square brackets were not provided. I’m wondering whether this scenario will be handled correctly on the service side.

[Copilot]

Pull request overview

Copilot reviewed 13 out of 13 changed files in this pull request and generated 7 comments.