Make WSLC an available backend on the Rust SDK

[Carlos Alexandro Becker (caarlos0)]

📖 Description

Makes the WSL Container (WSLC) backend available through the public Rust SDK
(mxc-sdk), for both run-to-completion (run) and streaming (spawn_sandbox).
Previously WSLC was reachable only by driving the wxc-exec binary; selecting it
from the library returned ErrorCode::UnsupportedContainment.

The API mirrors how the TypeScript SDK selects the backend
(createConfigFromPolicy(policy, 'wslc') + { experimental: true }, then tweak
config.experimental.wslc):

let wslc = WslcSection { image: "python:3.12".into(), ..Default::default() };
let mut request = build_request_with_containment(&policy, &Containment::Wslc(wslc), None)?;
request.set_script("python3 -c 'print(42)'").set_experimental(true);

let output = run(request)?;            // captured stdout/stderr
// or: let mut sandbox = spawn_sandbox(request)?;   // live stdio + kill

How it works

WSLContainerRunner now implements both ScriptRunner and SandboxBackend
over one shared start_container lifecycle — the same shape as the Seatbelt,
Bubblewrap, and ProcessContainer backends. The two execution models differ only
in where the WSLC SDK's output callbacks send their bytes, selected by an
IoSink (an in-memory buffer for capture, or a non-blocking stream for the
caller — with host stdio being that same stream drained by a pump thread, so the
SDK's callback thread never performs the host's blocking I/O). The
run-to-completion path used by wxc-exec is unchanged.

Because the WSLC SDK delivers output through callbacks on its own threads rather
than exposing the container's pipe ends, streaming needs somewhere to park bytes
until the caller reads them. The stream_buffer module provides that: an
in-memory queue whose writer never blocks. Backpressure is deliberately absent
and documented — stalling a callback thread would also stall the exit callback
that teardown waits on, deadlocking shutdown. The queue is abandoned (and
released) as soon as its reader is cancelled or dropped, so an unread stream
cannot grow without bound.

Backend selection is explicit: build_request still resolves the host's
native backend, and build_request_with_containment takes a Containment.
Auto-selecting WSLC would silently boot a VM and resolve a container image. WSLC
additionally requires set_experimental(true) — the library-side equivalent of
--experimental, kept fail-closed. platform_support() reports "wslc" only
when the host can actually run it.

Limitations

Two limits follow directly from the WSLC SDK's surface, documented in the crate
docs and the getting-started guide:

• No stdin — the SDK exposes no process-input API, so take_stdin() returns
  None.
• No host pid — the process runs inside the WSL VM, so id() is 0;
  kill() stops the whole container (the process-tree kill the trait requires).

Separately, allowedHosts/blockedHosts cannot be enforced on WSLC today: the
backend applies them with in-container iptables and the container is not
granted CAP_NET_ADMIN, so such a policy fails the run at spawn. That is
pre-existing behaviour, now documented on WslcSection and in the guide rather
than left as a surprise.

WSLC remains Windows-only and experimental, behind the crate's wslc feature.

🔗 References

• Docs updated: docs/wsl/wsl-container-getting-started.md (new Rust SDK
  section), src/core/mxc-sdk/README.md, and the mxc-sdk crate docs.
• No linked issue.

🔍 Validation

Automated, all green:

• cargo fmt --all -- --check
• cargo clippy --target x86_64-pc-windows-msvc clean both with and without
  the wslc feature (the feature-off configuration is what the WXC-Exec Hyperlight / MicroVM jobs build).
• cargo test -p mxc_engine -p mxc-sdk -p wxc_common — 471 tests pass, including
  7 new mxc_engine tests (WSLC config mapping, defaults matching the TypeScript
  SDK, the fail-closed experimental gate, parser rejection of invalid port
  mappings, and the off-Windows / no-experimental dispatch rejections) and 7
  stream_buffer tests (EOF-on-close, partial reads, parked reads, cancellation
  releasing buffered bytes, reader-drop abandoning the stream, and a large write
  to a never-drained stream completing without blocking).
• 13 further wslc_common tests added for the teardown hardening below: the
  Settled state machine that keeps wait and try_wait from disagreeing about
  a timeout, both timeout error kinds, the confirmed vs. unconfirmed timeout
  wording, the host-stdio pump loop, the per-mode I/O wiring, and the regression
  the pump exists for — callback-path writes not blocking on a stalled host sink.

Teardown hardening (review follow-ups)

Review of the streaming lifecycle surfaced several related ways the backend
could report more than it had proven, all fixed here:

• try_wait ignored the sticky timeout. A timeout kills the container, so
  has_exited() is true afterwards and try_wait returned the kill's exit code
  — contradicting the Err(TimedOut) the same handle's wait had just returned.
  Both now read one Settled outcome.
• A timeout claimed a termination it never confirmed. WslcStopContainer's
  HRESULT says the call was accepted, not that the process died. wait_for_process
  now escalates SIGTERM → SIGKILL and reports a three-state WaitOutcome, so
  an unconfirmed timeout says the container may still be running instead of
  asserting it was killed.
• StartedContainer had no Drop. A panic unwinding past a started
  container freed the callback context while the SDK could still be calling
  through it; it now quiesces unless teardown already ran.
• SDK handle releases ran apartment-less. The RAII guards' Drop impls did
  not join the MTA, which the Send impl's soundness argument assumed (reported
  as [WSLC] RAII guard Drop impls call SDK teardown outside a COM apartment #721).
• An unconfirmed kill still reached callers as a successful timeout.
  mxc_sdk::Sandbox::wait maps every ErrorKind::TimedOut onto
  WaitOutcome::TimedOut — a success value documented as "the process tree was
  killed" — discarding the message with it. The unconfirmed case now uses
  io::Error::other, so it surfaces as Err and the public WaitOutcome keeps
  meaning exactly what it documents.
• Only WAIT_TIMEOUT was special-cased. WAIT_FAILED, WAIT_ABANDONED and
  a null exit event all fell through as a normal exit, reporting STILL_ACTIVE
  for a container that was still running. Every wait result is now handled
  explicitly, and reporting an exit requires positive evidence of one — the exit
  event signalling, or the SDK's exit callback.

main has been merged in, including the bindgen-generated WSLC FFI bindings
(#669). That refactor and this branch both rewrote wslc_bindings.rs and
wsl_container_runner.rs, so the resolution keeps upstream's generated-bindings
facade and re-applies this branch's additions on top, porting every SDK call site
to the generated API shape. One consequence is worth calling out: bindgen's
WslcSdk owns its Library, so the "never unload the module" property now lives
in WslcSdk::shared() — a process-wide OnceLock instance handed out as
&'static. The DLL is loaded and symbol-checked once, never unloaded, and
StartedContainer borrows it rather than owning it, which removes the SDK from
that struct's drop-order reasoning entirely.

⚠️ The WSLC path itself has not been executed. It requires Windows + WSL2 +
the WSLC runtime, and this was developed on macOS, where only cross-target
cargo check/clippy is possible. It needs a run on a WSLC-capable host
before merge. The existing tests/configs/wslc_*.json corpus exercises the
run-to-completion path this change refactors, so that corpus is the natural
regression check.

That caveat is not theoretical. Because the Windows-only code could not be run,
it went through several rounds of independent review, which found ten defects —
all fixed here, and all but one in the streaming/teardown state machine:

1. Use-after-free on a routine path. After WslcStartContainer succeeds, the
   two error returns dropped locals in reverse declaration order, freeing the
   SDK's callback context before the session was terminated and the DLL unloaded.
   Reached by any host-rules policy, since apply_iptables_rules always fails
   without CAP_NET_ADMIN. Failures now quiesce the container and wait for the
   exit callback first — as does the run-to-completion wait-failure path, which
   had the same hole.
2. Use-after-free when the exit-callback wait timed out. Every teardown path
   waited for the callback but proceeded regardless, freeing the context and
   unloading the DLL even though the "SDK has stopped calling back" guarantee had
   not held. The module is now never unloaded, and a timed-out wait leaks one
   Arc reference, so a late callback can touch neither freed memory nor
   unmapped code.
3. Deadlock. The streaming sink originally held a mutex across a blocking
   WriteFile, so a full pipe with an undrained reader hung every teardown path.
   Replaced with the non-blocking in-memory stream.
4. Drop racing live callbacks into FreeLibrary, without the
   exit-callback handshake.
5. A spurious-wakeup bug in that handshake (single wait_timeout, result
   discarded) that silently reintroduced 2 and 3.
6. try_wait short-circuited teardown by caching the exit code wait treats
   as proof it already ran, and masked a prior timeout.
7. Abandoned readers grew the unbounded queue forever, since wait only
   drains streams the caller did not take.
8. validate_common was skipped on the streaming path — which also bypassed
   the central --allow-testing-features gate on
   network.proxy.builtinTestServer.
9. Probe and spawn disagreed on RPC_E_CHANGED_MODE, so an STA caller was
   told WSLC was available and then refused at spawn.
10. A racy test (a write legitimately woke the parked reader, making the
    assertion a mutex coin flip) that failed on windows / arm64.

Known follow-up (pre-existing)

COM initialization is deliberately not balanced: init_and_load_sdk enters the
MTA and intentionally leaks that initialization, because the SDK and its callback
threads outlive the call, so releasing the apartment on return could tear the MTA
down under a running container. Correctly balancing it — and covering the
handles' own Drop, which releases them outside an apartment — means tying the
apartment to StartedContainer's cross-thread lifetime via ManuallyDrop or an
owning worker thread. The same exposure exists on main today (the previous
run_internal initialized COM and never uninitialized), so this is left as a
focused follow-up rather than widening this change.

Note this is now a refcount/apartment concern only: the memory-safety half — a
late callback reaching a freed context or an unloaded module — is closed above,
by never unloading wslcsdk.dll and by leaking the callback context whenever the
exit callback cannot be positively observed.

✅ Checklist

• Signed the Contributor License Agreement
• Linked to an issue
• 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 docs/pull-requests.md) — n/a, no dependency changes

📋 Issue Type

• Bug fix
• Feature
• Task

[Copilot]

Pull request overview

Exposes experimental WSLC through the Rust SDK for explicit run-to-completion and streaming execution.

Changes:

• Adds explicit containment selection and WSLC configuration APIs.
• Implements callback-backed streaming, lifecycle handling, and capability discovery.
• Adds tests and documentation for WSLC SDK usage.

Show a summary per file

File	Description
.github/copilot-instructions.md	Documents the expanded architecture.
docs/wsl/wsl-container-getting-started.md	Adds Rust SDK guidance.
src/backends/wslc/common/src/lib.rs	Exports streaming and availability APIs.
src/backends/wslc/common/src/sandbox.rs	Implements streaming WSLC processes.
src/backends/wslc/common/src/stream_buffer.rs	Adds callback-to-reader buffering.
src/backends/wslc/common/src/wsl_container_runner.rs	Shares WSLC lifecycle across execution modes.
src/backends/wslc/common/src/wslc_bindings.rs	Adds runtime capability probing.
src/core/mxc-sdk/Cargo.toml	Adds the optional WSLC feature.
src/core/mxc-sdk/README.md	Documents WSLC support and limitations.
src/core/mxc-sdk/src/lib.rs	Re-exports WSLC APIs.
src/core/mxc_engine/src/dispatch.rs	Dispatches streaming WSLC requests.
src/core/mxc_engine/src/lib.rs	Exports containment configuration types.
src/core/mxc_engine/src/platform.rs	Reports available WSLC runtimes.
src/core/mxc_engine/src/policy.rs	Builds and validates WSLC requests.

Review details

Comments suppressed due to low confidence (1)

src/backends/wslc/common/src/sandbox.rs:164

• After try_wait() caches an exit code, this fast path returns without calling started.destroy() or setting torn_down. Consequently a completed WSLC container/session remains allocated until the Sandbox is dropped, even though wait() has reported completion. Only use the cached fast path after teardown; otherwise continue through the normal wait/cleanup path.

        if let Some(code) = self.exit {
            return Ok(code);
        }

• Files reviewed: 14/14 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 14/14 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

Comments suppressed due to low confidence (2)

src/backends/wslc/common/src/wslc_bindings.rs:552

• This probe can advertise WSLC on an STA thread because ComApartment::enter accepts RPC_E_CHANGED_MODE, but the actual startup path still calls init_and_load_sdk, which treats that same result as fatal. Consequently platform_support() can report "wslc" and a subsequent run/spawn_sandbox on the same thread immediately fails COM initialization. Make startup use the same apartment handling (with a guard spanning all startup SDK calls), or make the probe match the runner's real preflight.

    let Ok(_com) = ComApartment::enter() else {
        return false;
    };
    probe_components()

src/backends/wslc/common/src/sandbox.rs:215

• A successful terminal wait does not actually release the WSLC session: destroy() only stops/deletes the container, while WslcSessionGuard, the process/container handles, and the loaded DLL remain inside self.started until the caller drops the Sandbox. Applications that retain completed handles therefore retain the heavyweight WSL session indefinitely despite wait() reporting completion. Consume/release StartedContainer on the first terminal wait and keep only the cached outcome needed for repeated waits.

        self.started.destroy(&mut self.logger);
        self.torn_down = true;

• Files reviewed: 15/15 changed files
• Comments generated: 1
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

• Files reviewed: 15/15 changed files
• Comments generated: 2
• Review effort level: Medium

[Copilot]

Review details

Comments suppressed due to low confidence (1)

src/backends/wslc/common/src/wsl_container_runner.rs:1492

• If wait_for_exit fails (for example, WslcGetProcessExitEvent returns an error), this returns while the container and its callbacks may still be live. StartedContainer has no Drop handshake, so its fields are released without waiting for the exit callback—the condition this file identifies as necessary before reclaiming IoContext and unloading the DLL. Quiesce the started container on this error path before returning, as the post-start failures above already do.

        let (exit_code, timed_out) = match started.wait_for_exit(logger) {
            Ok(r) => r,
            Err(e) => return e,
        };

• Files reviewed: 15/15 changed files
• Comments generated: 0 new
• Review effort level: Medium

[Copilot]

🟡 Not ready to approve

Callback waiting can leak captured output, and failed waits may be misreported as normal exits.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (2)

src/backends/wslc/common/src/wsl_container_runner.rs:1098

• This interim wait already leaks an Arc when the first 30-second callback wait expires, but the code then retries after SIGKILL. If the callback arrives during that second wait, teardown is confirmed yet the first leaked reference permanently retains the IoContext and any captured stdout/stderr. Use the non-leaking predicate wait for this first probe and reserve await_callbacks_quiesced for the final failed attempt.

        let mut confirmed = await_callbacks_quiesced(io_ctx);

src/core/mxc-sdk/src/lib.rs:57

• The public WSLC limitations should also disclose that stdout/stderr are backed by unbounded in-memory queues. A caller that takes a reader but keeps it alive without draining or dropping it can grow the host process until OOM; this behavior is currently documented only in the private stream_buffer module, so SDK consumers cannot discover the requirement.

//! WSLC is **experimental**: build with the crate's `wslc` feature, and call
//! [`SandboxRequest::set_experimental(true)`](SandboxRequest::set_experimental)
//! on the request. Its container has no stdin (the WSLC SDK exposes no
//! process-input API), so [`Sandbox::take_stdin`] returns `None` for it.

• Files reviewed: 15/15 changed files
• Comments generated: 1
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Not ready to approve

Callback retry paths can permanently retain complete output buffers through premature repeated Arc leaks.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (1)

src/backends/wslc/common/src/wsl_container_runner.rs:270

• This helper leaks an Arc as soon as any 30-second wait misses the callback, but wait_for_process deliberately calls it once before SIGKILL and again afterward. If the callback arrives only after escalation, the first leaked reference remains forever; in capture mode it retains the complete stdout/stderr buffers, and repeated failed waits leak additional references. Separate the non-leaking predicate wait from the final “about to release the callback context” fallback, and only forget one reference after the last confirmation attempt fails.

fn await_callbacks_quiesced(io_ctx: &Arc<IoContext>) -> bool {
    if io_ctx.wait_for_exit_callback() {
        return true;
    }
    std::mem::forget(Arc::clone(io_ctx));

• Files reviewed: 15/15 changed files
• Comments generated: 0 new
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Human review recommended

The Windows-only FFI lifecycle remains untested on a WSLC host and contains an unresolved pump-thread leak on setup failures.

Review details

Suppressed comments (1)

src/backends/wslc/common/src/stream_buffer.rs:57

• StreamWriter does not close the shared state when its producer is dropped. In OutputMode::Stream(StdioMode::Inherit), IoContext::new starts two pump threads before several fallible SDK setup calls; any pre-start error drops these writers and detaches the JoinHandles, but each pump remains parked on the condvar forever because no one sets closed or notifies it. Close the stream from StreamWriter::drop so producer teardown always wakes its reader.

pub(crate) struct StreamWriter(Arc<Shared>);

• Files reviewed: 15/15 changed files
• Comments generated: 0 new
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Human review recommended

The unexecuted Windows lifecycle still has unresolved COM-drop and callback-lifetime concerns.

Review details

Suppressed comments (4)

src/backends/wslc/common/src/wslc_bindings.rs:408

• This also proceeds with WslcReleaseContainer when ComApartment::enter() failed, so cross-thread drop can still invoke the SDK outside any COM apartment. Fail closed here (or centralize releases on an initialized worker) rather than violating the teardown precondition.

            let _com = ComApartment::enter();

src/backends/wslc/common/src/wslc_bindings.rs:444

• As with the other guards, ignoring an Err here means WslcReleaseProcess still runs apartment-less, contradicting the invariant used to justify moving this handle across threads. Skip the release when COM cannot be entered, or perform it on a guaranteed initialized teardown thread.

            let _com = ComApartment::enter();

src/backends/wslc/common/src/wsl_container_runner.rs:270

• This first failed callback wait leaks an Arc immediately, but wait_for_process then waits again (and may observe the callback on that retry). In that successful-retry case the leaked reference is never recoverable, so every delayed callback permanently retains the IoContext and its potentially large capture/stream-buffer capacity. Separate “wait” from “make immortal”: only leak once the final confirmation attempt has failed and teardown is actually about to release the callback owner.

    std::mem::forget(Arc::clone(io_ctx));

src/backends/wslc/common/src/wsl_container_runner.rs:1888

• This safety documentation is stale: WslcSdk::shared() deliberately keeps the DLL loaded for the process lifetime, so teardown no longer unloads it. Reword this to focus on preventing callbacks from reaching a freed IoContext; otherwise the documented ownership argument contradicts the implementation.

    /// The exit callback is the SDK's guarantee that no further callback will
    /// arrive, which must hold before this container's fields drop: they free
    /// the `IoContext` those callbacks write through and then unload the DLL.

• Files reviewed: 15/15 changed files
• Comments generated: 1
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Copilot]

🟡 Not ready to approve

Intermediate callback-state and pre-start pump lifecycle paths can leak memory and threads.

Once you've addressed the issues Copilot identified, you can request another Copilot review.

This review doesn't count toward merge requirements. Sign up for the private preview to control whether Copilot approvals count.

Review details

Suppressed comments (2)

src/backends/wslc/common/src/wsl_container_runner.rs:271

• This leaks the callback Arc on an intermediate timeout, before teardown has actually given up. On the timeout path, the first 30-second wait can expire, SIGKILL can then make the second wait succeed, but the first forgotten reference still keeps the entire IoContext (including captured stdout/stderr) alive for the rest of the process. Split “wait for callback” from “leak on final failure,” and only forget a reference after the last confirmation attempt has failed.

fn await_callbacks_quiesced(io_ctx: &Arc<IoContext>) -> bool {
    if io_ctx.wait_for_exit_callback() {
        return true;
    }
    std::mem::forget(Arc::clone(io_ctx));
    false

src/backends/wslc/common/src/stream_buffer.rs:57

• Dropping the producer does not close the stream. IoContext::new(Stream(Inherit)) starts pump threads before the many fallible setup calls in start_container; if one of those calls fails before the container starts, the context and writer are dropped but each pump remains blocked in read() forever because neither closed nor cancelled is set. Make writer drop signal EOF so pre-start failures cannot leak two threads.

pub(crate) struct StreamWriter(Arc<Shared>);

• Files reviewed: 15/15 changed files
• Comments generated: 0 new
• Review effort level: Balanced

We're testing this review assessment. Please use 👍 or 👎 to tell us if it's correct.

[Soham Das (SohamDas2021)]

Ran all the existing wslc config jsons to ensure that there is no regression.