Skip to content

[WSLC] Port mappings for the built-in proxy - #1799

Merged
Elliot (theelliotm) merged 4 commits into
mainfrom
user/emichlin/wslc-proxy-port-mappings
Nov 18, 2026
Merged

Elliot (theelliotm) merged 4 commits into
mainfrom
user/emichlin/wslc-proxy-port-mappings

Conversation

@theelliotm

@theelliotm Elliot (theelliotm) commented Nov 18, 2026 •

Copy link
Copy Markdown
Contributor

📖 Description

Adds wslc.portMappings support to create-and-run requests behind the WSLC built-in proxy.

  • With egress filtering, port mappings now go through the built-in proxy; they're no longer rejected. A run with all traffic denied plus port mappings also uses the proxy.
  • The SDK port mappings are set on the proxy container, which relays each distinct containerPort to the workload at its fixed internal address (10.231.1.2).
  • Mapped ports listen only on Windows 127.0.0.1, never on the LAN IP. So network.ingress.default: allow still has no effect.
  • The workload sees the proxy container as the connection source.
  • UDP mappings are still rejected

🔗 References

Refs #1462

Spec: docs/development/architecture/designs/1462-wslc-builtin-proxy/README.md (#1625)

🔍 Validation

  • cargo test -p mxc-sdk --features wslc --lib -- wslc: passed (465)
  • cargo fmt --all -- --check and cargo clippy --workspace --all-targets -- -D warnings: passed
  • tests/scripts/run_wslc_all_tests.ps1 built-in proxy section (WSL 3.0.5, ARM64): passed
    • New mapping matrix: all denied, allow rules, egress allow, ingress allow, bridged.
    • Checked: reachability on 127.0.0.1, LAN IP refused, egress/DNS still filtered, workload can't reach the relay listener.
    • New rejections: UDP, duplicate port, hostLoopback, networkProxy.
    • Existing proxy tests: allow/deny rules, port ranges, CIDR except, reserved, timeout, allow everything, real client, raw frame.
  • Node: npm test: 459 passed, 24 skipped. WSLC integration (wslc-e2e, wslc-state-aware) with MXC_ENABLE_WSLC_TESTS=1: 19/19 passed
  • .NET: dotnet test --project Microsoft.Mxc.Sdk.Tests --framework <fw> -p:MxcWithWslc=true filtered to MxcContainerWslcE2ETests and MxcLifecycleWslcE2ETests: 32/32 passed on net10.0 and on net8.0

✅ Checklist

  • Signed the Contributor License Agreement
  • Linked to an issue
  • For features or changes requiring a spec: linked the issue with maintainer-applied feature-accepted
  • For implementation: linked the required approved and merged design/API spec, or explained why no spec is required
  • Feature issue remains open unless this PR completes all agreed implementation, validation, and documentation
  • Updated documentation (if applicable)
  • Updated Copilot instructions (if build, architecture, or conventions changed)
  • If this PR changes Cargo.lock, the dependency-feed-check check passes (see pull request builds)

📋 Issue Type

  • Bug fix
  • Feature
  • Task
Microsoft Reviewers: Open in CodeFlow

Copilot AI balanced review requested due to automatic review settings November 18, 2026 00:40
@azure-pipelines

Copy link
Copy Markdown
Azure Pipelines:
There may be pipelines that require an authorized user to comment /azp run to run.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟡 Changes recommended

The isolation tests can miss regressions because the relay probe targets the wrong network address and the LAN-refusal check may run after the mapped service has exited.

2 open issues
What changed in this PR

Adds TCP port mappings to WSLC create-and-run execution behind the built-in proxy, advancing #1462 while leaving lifecycle mappings unchanged.

Changes:

  • Places mappings on the proxy and relays connections to the workload’s fixed internal address.
  • Supports mappings alongside filtered or denied egress, with Windows loopback-only access.
  • Adds functional test scenarios, removes obsolete rejection expectations, and updates backend guidance.
File Description
tests/​scripts/​run_wslc_all_tests.ps1 Adds mapping reachability, isolation, and rejection checks.
tests/​configs/​wslc_port_mapping_bridged_reached.json Adds bridged mapping coverage.
tests/​configs/​wslc_network_egress_port_mappings_rejected.json Removes the obsolete mapping-rejection fixture.
tests/​configs/​wslc_network_egress_port_mapping.json Tests mappings with all other traffic denied.
tests/​configs/​wslc_network_egress_port_mapping_udp_rejected.json Tests UDP rejection.
tests/​configs/​wslc_network_egress_port_mapping_network_proxy_rejected.json Tests external-proxy rejection without bridged networking.
tests/​configs/​wslc_network_egress_port_mapping_ingress_allow.json Tests shared container ports and the ingress warning.
tests/​configs/​wslc_network_egress_port_mapping_host_loopback_rejected.json Tests incompatible host-loopback access.
tests/​configs/​wslc_network_egress_port_mapping_duplicate_rejected.json Tests duplicate Windows-port rejection.
tests/​configs/​wslc_network_egress_port_mapping_allow_rules.json Tests mappings alongside egress allow rules.
tests/​configs/​wslc_network_egress_port_mapping_allow_default.json Tests multiple mappings and relay isolation.
src/​mxc-sdk/​src/​backends/​wslc/​common/​wsl_container_runner.rs Transfers proxied mappings from workload to gateway.
src/​mxc-sdk/​src/​backends/​wslc/​common/​policy.rs Routes non-bridged mappings through the proxy.
src/​mxc-sdk/​src/​backends/​wslc/​common/​egress_gateway.rs Configures mappings, relay destinations, and a fixed workload address.
src/​mxc-sdk/​src/​backends/​wslc/​common/​container_steps.rs Shares SDK port-mapping conversion logic.
sdk/​node/​tests/​integration/​wslc-e2e.test.ts Removes the obsolete mapping-rejection expectation.
sdk/​dotnet/​Microsoft.Mxc.Sdk.Tests/​V1/​MxcContainerWslcE2ETests.cs Removes the obsolete mapping-rejection case.
docs/​backends/​wslc/​wsl-container-getting-started.md Documents proxy mappings and loopback-only access.

Review effort: Balanced

Comment thread tests/scripts/run_wslc_all_tests.ps1 Resolved
@theelliotm Elliot (theelliotm) changed the title [WSLC] Port mappings for the built-in proxy [WSLC] Port mappings for the built-in proxy (create-and-run only) Nov 18, 2026
@theelliotm Elliot (theelliotm) changed the title [WSLC] Port mappings for the built-in proxy (create-and-run only) [WSLC] Port mappings for the built-in proxy Nov 18, 2026
@theelliotm Elliot (theelliotm) self-assigned this Nov 18, 2026
Copilot AI balanced review requested due to automatic review settings November 18, 2026 01:05

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues remain for the WSLC TCP port-mapping changes.

No open issues 🎉

2 resolved since last review

Review effort: Balanced

@theelliotm
Elliot (theelliotm) marked this pull request as ready for review November 18, 2026 01:10
@theelliotm
Elliot (theelliotm) requested a review from a team as a code owner November 18, 2026 01:10
Co-authored-by: Copilot <[email protected]>
Copilot-Session: c3f64c2c-9005-43eb-a803-a91fb7265c5b
@theelliotm
Elliot (theelliotm) requested review from a team and a balanced review from Copilot November 18, 2026 01:14

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues are recorded for the WSLC TCP port-mapping changes.

No open issues 🎉

Review effort: Balanced

@microsoft-github-policy-service microsoft-github-policy-service Bot added the Needs-Author-Feedback Waiting for additional information or action from the issue or pull-request author. label Nov 18, 2026
Copilot AI balanced review requested due to automatic review settings November 18, 2026 22:25
@microsoft-github-policy-service microsoft-github-policy-service Bot added Needs-Attention Requires attention or a decision from the MXC maintainers. and removed Needs-Author-Feedback Waiting for additional information or action from the issue or pull-request author. labels Nov 18, 2026

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🟢 Approval recommended

No active review issues were identified for the TCP port-mapping changes.

No open issues 🎉

Review effort: Balanced

@theelliotm
Elliot (theelliotm) merged commit e6960f7 into main Nov 18, 2026
38 checks passed
@theelliotm
Elliot (theelliotm) deleted the user/emichlin/wslc-proxy-port-mappings branch November 18, 2026 23:54
@microsoft-github-policy-service microsoft-github-policy-service Bot removed the Needs-Attention Requires attention or a decision from the MXC maintainers. label Nov 18, 2026

@MGudgin Gudge (MGudgin) left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Post-merge follow-up

Two Medium follow-up findings, verified against final PR head a0fd1a95 and merged commit e6960f74. This is a non-blocking post-merge review, not a request to hold or undo the merge.

The gateway implementation and all five positive mapping fixtures are byte-identical between the originally reviewed revision and the merged result. The subsequent runner changes concern SDK error reporting, not gateway supervision; the mapping matrix still uses fixed Windows ports. The final explicit loopback-binding and relay-idle-timeout changes do not resolve these two concerns.

Both findings below are based on source inspection, not fault-injected runtime reproductions. No new runtime tests were run for this verification.

Verified pre-existing context - not attributed as a new defect

  • Ongoing gateway supervision was already absent for egress-only runs. Finding 1 is classified newly_exposed_by_change specifically because the newly accepted inbound mapping path now depends on that gateway remaining alive. It does not claim that this PR introduced the underlying supervision limitation.

}
// Published ports reach only a container with a non-internal network,
// so the gateway takes the workload's mappings and relays them.
let mappings = container_steps::sdk_port_mappings(port_mappings);

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Medium (reliability) - Report unexpected gateway exit during mapped runs.

Attribution: newly_exposed_by_change - filtered/all-deny requests with mappings were previously rejected; this change makes their inbound forwarding depend on the gateway's continued execution.

After startup readiness, WSLContainerRunner::wait_for_process waits for the workload's exit/timeout or stdin-forwarding abort, not the gateway's exit. If the gateway exits unexpectedly while the workload continues, the mapped ports stop relaying, but a workload that later exits zero can still produce a successful response. Gateway::teardown drains gateway output and reports resource-removal status rather than detecting premature gateway death.

Fix: Observe gateway completion alongside the workload and surface an actionable backend failure if it exits before the workload completes, preserving diagnostics and cleanup. Add a regression scenario that terminates the gateway after readiness and checks the public result. This is separate from changing the existing behavior for ordinary teardown errors.


# Port mappings are relayed by the proxy under every proxied posture, and stay
# on the workload under bridged networking.
Invoke-WslcMappedRun "wslc_network_egress_port_mapping.json" ([ordered]@{ 18080 = 8080 }) `

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Medium (testability) - Allocate mapping-test host ports dynamically.

Attribution: introduced_by_change - the new matrix and its fixtures hard-code Windows ports 18080-18086 without dynamic substitution or collision retry.

If another local service or concurrent validation run owns one of these ports, WSLC can fail to start and the matrix reports a feature regression caused by the environment. Start-WslcBackgroundRun launches the fixture directly, so nothing replaces those ports. The existing New-PortMappedSandbox helper in tests/scripts/run_wslc_state_aware_tests.ps1:675-705 already allocates an ephemeral port and retries the address-in-use result 0x80072740.

Fix: Reuse that allocation/retry pattern: substitute available Windows ports into temporary fixtures and retry if a port is claimed before WSLC binds it.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants