Add WSLC network lifecycle events

[beena352]

Summary of the Pull Request

Add network lifecycle events to WSLC, including create, connect, disconnect, destroy, and prune events. The implementation supports Docker-compatible network event filters by ID and name, forwards events directly from Docker's event stream preserving Docker's event order and behavior, handles network events across VM restarts, and safely cleans up when network creation fails.

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

• WSLC now records and publishes network events from the Docker event stream
• Network event filters support full and prefix matches for network IDs and names. Events are also kept across VM restart when the event store remains available
• Network operations (create/delete/prune) return as soon as Docker's HTTP response is processed and do not wait for the corresponding event to be recorded. Rollback events (e.g. from a failed create) are forwarded like any other Docker event, matching Docker's own behavior

Validation Steps Performed

[Copilot]

🟡 Changes recommended

Unresolved localization, rollback cleanup, and prune-timeout test issues remain.

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

Pull request overview

Adds Docker-compatible WSLC network lifecycle events for create, connect, disconnect, destroy, and prune operations.

Changes:

• Adds network event tracking, filtering, ordering, and restart persistence.
• Synchronizes network mutations with event publication.
• Adds rollback handling and integration tests.

File summaries

File	Changes	Review findings
test/windows/WSLCTests.cpp	Adds network event integration tests.	—
src/windows/wslcsession/WSLCSession.h	Declares network operation state.	—
src/windows/wslcsession/WSLCSession.cpp	Implements event handling and network operation coordination.	Moderate, 3 votes: Localize the PruneNetworks failure message. Moderate, 1 vote: Add deterministic rollback failure-path coverage. Critical, 1 vote: Handle post-commit create failures to prevent orphaned networks. Moderate, 1 vote: Test prune timeout/abandon behavior and recovery.
src/windows/wslcsession/EventStore.cpp	Adds network ID/name filtering.	—
src/windows/wslcsession/DockerEventTracker.h	Defines network event callbacks.	—
src/windows/wslcsession/DockerEventTracker.cpp	Parses and dispatches Docker network events.	—

Review details

Suppressed comments (2)

src/windows/wslcsession/WSLCSession.cpp:3262

• The rollback-specific behavior introduced here is not covered by the new integration tests, which only exercise successful creates/deletes/prunes. A failure after Docker has created the network is exactly where this suppression queue must hide the create/destroy pair and remove the network; add a deterministic failure-path test that verifies neither stale event nor network remains.

    // Suppress create and destroy before rollback; removal may commit despite a failed response.
    auto removeNetworkCleanup = wil::scope_exit_log(WI_DIAGNOSTICS_INFO, [this, &name, &createResult]() {
        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Create);
        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Destroy);
        m_runtime.Docker().RemoveNetwork(name);

src/windows/wslcsession/WSLCSession.cpp:2589

• This timeout/abandon path is the only protection against a late aggregate prune event completing a later operation, but the new tests cover only successful prune and VM restart. Add a test that forces the wait to time out, verifies a subsequent prune is rejected while the abandoned event is pending, and verifies that the delayed event or a restart clears the block.

    // Clear the slot if the wait fails; an abandoned prune remains blocked until its unkeyed event arrives.
    auto abandonOnFailure = wil::scope_exit([&]() {
        std::lock_guard networksLock{m_networksLock};
        if (m_pendingNetworkOperation != Operation)

• Files reviewed: 6/6 changed files
• Comments generated: 2
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.

[Copilot]

🟡 Changes recommended

Prune-event correlation and rollback suppression-state issues remain unresolved.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (3)

src/windows/wslcsession/WSLCSession.cpp:3267

• These suppression entries are never retired if RemoveNetwork fails or the Docker event stream never delivers one of the matching events. Each failed create can therefore leave two entries in the session forever (and a later event for that ID can be incorrectly hidden), so repeated rollback failures cause unbounded state growth. Please remove/expire the entries when rollback cannot complete, or otherwise bound this suppression state.

        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Create);
        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Destroy);

test/windows/WSLCTests.cpp:7312

• Because Docker event timestamps are whole seconds and the event store includes the since bound, this can equal the cleanup DeleteNetwork event above. If a stale network is present from a prior run, that cleanup destroy is included and this test sees an extra lifecycle event; establish since at the next second before creating the network, as NetworkPruneEventStream does.

        const LONGLONG since = now();

test/windows/WSLCTests.cpp:7496

• This has the same inclusive whole-second boundary issue as the other network event test: a destroy emitted by the pre-test cleanup can have the same timestamp as since and be returned by the filter after a rerun with stale state. Wait for the next second before capturing since so cleanup events are excluded.

        const LONGLONG since = now();

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Unresolved rollback-suppression issues remain, and deterministic tests are needed for rollback and abandoned-prune recovery.

Review details

Suppressed comments (4)

Previously missed (1) — in code that hasn't changed since the last review.

src/windows/wslcsession/WSLCSession.cpp:468

• Clearing this queue before the relay is stopped races with an in-flight Docker callback. OnNetworkEvent can already be blocked on m_networksLock while rollback is issuing RemoveNetwork; during teardown this hook clears the suppression entries, then WSLCSessionRuntime calls m_ioRelay->Stop() afterward and joins the callback, so the late create/destroy event is recorded instead of suppressed. Preserve the entries until the old relay has drained, or otherwise synchronize teardown with network callbacks.

src/windows/wslcsession/WSLCSession.cpp:3282

• This rollback path is new but none of the added tests forces a failure after Docker has created the network (for example, an inspect failure). Without exercising this sequence, regressions can leave the network behind or publish the rollback create/destroy events; add a deterministic failure-injection test that verifies both cleanup and event suppression.

    auto removeNetworkCleanup = wil::scope_exit_log(WI_DIAGNOSTICS_INFO, [this, &name, &createResult]() {
        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Create);
        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Destroy);
        m_runtime.Docker().RemoveNetwork(name);
    });

src/windows/wslcsession/WSLCSession.cpp:2618

• The abandoned-prune recovery path is also untested: the new tests cover successful ordering and VM restart, but never force the aggregate event past the timeout and then verify that a later prune is rejected until the delayed sequence drains. Add a deterministic event-stream failure/delay test for this state transition.

        if (Operation->Type == PendingNetworkOperationType::Prune)
        {
            m_abandonedPrune.emplace(AbandonedPrune{std::move(Operation->ExpectedDestroyIds)});
        }

src/windows/wslcsession/WSLCSession.cpp:3282

• Both suppression entries are queued before RemoveNetwork, but this is a logging scope-exit cleanup, so a removal failure leaves the entries behind. In that case the Docker network can remain alive while a later legitimate destroy for the same ID is silently discarded by OnNetworkEvent (and the stale entries persist until VM teardown). Handle cleanup failure separately so the destroy event is not suppressed unless removal actually succeeded.

    auto removeNetworkCleanup = wil::scope_exit_log(WI_DIAGNOSTICS_INFO, [this, &name, &createResult]() {
        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Create);
        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Destroy);
        m_runtime.Docker().RemoveNetwork(name);
    });

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Unresolved issues remain in rollback event suppression and lifecycle test timestamp handling; final human review is needed.

Review details

Suppressed comments (3)

src/windows/wslcsession/WSLCSession.cpp:3306

• The rollback tombstones only suppress one create and one destroy. If an endpoint is attached and detached while the inspect is failing (for example, by another Docker client), the corresponding connect/disconnect events are still recorded even though cleanup removes the network, leaving orphaned lifecycle events. Suppress all event kinds for a rolled-back network ID until its cleanup events have drained.

    // Suppress create and destroy before rollback; removal may commit despite a failed response.
    auto removeNetworkCleanup = wil::scope_exit_log(WI_DIAGNOSTICS_INFO, [this, &name, &createResult]() {
        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Create);
        m_suppressedNetworkEvents.emplace_back(createResult.Id, NetworkEvent::Destroy);

test/windows/WSLCTests.cpp:7312

• since is captured only after the best-effort cleanup at line 7308, but event windows are inclusive at second resolution. If a previous run left this network behind, that cleanup's destroy event can have the same timestamp as since, so the first query and the lifecycle assertions see a stale extra event. Start the window on the next whole second, as the prune tests below do.

        const LONGLONG since = now();

test/windows/WSLCTests.cpp:7695

• The pre-test DeleteNetwork can record a destroy event in the same second as this since value, and the event window includes since. After an interrupted prior run leaves the network behind, the final network filter can therefore include that cleanup event and fail the expected two-event assertion. Move since to the next whole-second boundary.

        const LONGLONG since = now();

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

Rollback can be released before pending-operation setup completes, leaving network state committed if allocation fails.

Review details

Suppressed comments (1)

src/windows/wslcsession/WSLCSession.cpp:3378

• The rollback guard is released before StartPendingNetworkOperation allocates and publishes the completion slot. If that allocation throws, CreateNetwork returns failure while the Docker network and its m_networks entry remain committed. Keep rollback active until the pending operation is established and make that failure path undo both pieces of state.

    removeNetworkCleanup.release();

    auto pendingOperation = StartPendingNetworkOperation(PendingNetworkOperationType::Create, createResult.Id);

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The changes span lifecycle synchronization, persistence, rollback, and recovery across multiple components, warranting final human review.

Review details

• Files reviewed: 8/8 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟢 Approval recommended

The reviewed changes and tests cover the stated network event functionality without unresolved blocking issues.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

The broad lifecycle, persistence, and recovery changes warrant final human review.

Review details

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[Copilot]

🟡 Changes recommended

One or more issues must be addressed before approval.

Get a fresh assessment by requesting another Copilot review.

Review details

Suppressed comments (1)

test/windows/WSLCTests.cpp:7199

• IWSLCEventStream::GetNext requires the optional cancellation handle argument; this new call has only one argument and will fail to compile. Use the existing two-argument form with nullptr for an uncancelled read.

            VERIFY_SUCCEEDED(Stream->GetNext(&eventJson));

• Files reviewed: 7/7 changed files
• Comments generated: 1
• Review effort level: Lite

[Copilot]

🔵 Needs a closer look

CLI event-filter validation must accept the network key so the advertised filters are usable.

Review details

Suppressed comments (1)

Previously missed (1) — in code that hasn't changed since the last review.

src/windows/wslcsession/EventStore.cpp:124

• This adds network filtering to the COM event store, but the public wslc events path still rejects that key: ArgumentValidation.cpp's event-filter allowlist remains {type, event, container, image} (and the existing CLI tests assert network=test is invalid). As a result, users cannot access the advertised network ID/name filters through the CLI; add the key to CLI validation and update its coverage as part of this feature.

• Files reviewed: 7/7 changed files
• Comments generated: 0 new
• Review effort level: Lite

[David Bennett (dkbennett)]

src\windows\wslc\arguments\ArgumentValidation.cpp:52 still allows only type, event, container, and image. Existing tests explicitly expect --filter network=test to fail. Therefore, the COM tests pass while users cannot exercise the feature through wslc events. The correct solution here IMO is to remove the argument validation in the CLI on the value of the keys and let the service be authoritative in that (I know I recommended adding this validation earlier - I was wrong). I believe hte correct place to validate filter keys is in WSLCSession::GetEvents or EventStore::CreateStream.

Recommend removing the enum and passing the original action directly:

using NetworkEventCallback = std::function<void(
    const std::string& networkId,
    const std::string& action,
    const std::map<std::string, std::string>& attributes,
    std::int64_t time)>;

OnNetworkEvent can then record the action directly and it would automatically support all docker actions and future docker actions without requiring another wslc change.

Also would like an E2E test for the network events using the wslc events command line to verify that network lifecycle events work E2E.

[David Bennett (dkbennett)]

Probably more of a question for Blue (@OneBlue) - do we want methods that exist solely for testing to be in the IDL?

[Blue (OneBlue)]

Yes that's OK. We do this in other places, like TriggerIdleTermination()

[beena352]

src\windows\wslc\arguments\ArgumentValidation.cpp:52 still allows only type, event, container, and image. Existing tests explicitly expect --filter network=test to fail. Therefore, the COM tests pass while users cannot exercise the feature through wslc events. The correct solution here IMO is to remove the argument validation in the CLI on the value of the keys and let the service be authoritative in that (I know I recommended adding this validation earlier - I was wrong). I believe hte correct place to validate filter keys is in WSLCSession::GetEvents or EventStore::CreateStream.

Recommend removing the enum and passing the original action directly:

using NetworkEventCallback = std::function<void(
    const std::string& networkId,
    const std::string& action,
    const std::map<std::string, std::string>& attributes,
    std::int64_t time)>;

OnNetworkEvent can then record the action directly and it would automatically support all docker actions and future docker actions without requiring another wslc change.

Also would like an E2E test for the network events using the wslc events command line to verify that network lifecycle events work E2E.

That makes sense. I was originally planning to cover the network-events CLI path in a follow-up, but now wslc events command added, I’ll add that E2E coverage here. I’ll also switch the events command to the shared filter argument and move supported-key validation into the service so  --filter network=...  works through the CLI.

[Copilot]

🔵 Needs a closer look

Unsupported filter validation should remain in the CLI path before resolving or creating a session.

Review details

Suppressed comments (1)

src/windows/wslcsession/EventStore.cpp:153

• This moves unsupported-filter validation behind ResolveSession: the CLI now accepts any --filter key, opens or creates the session, and only then returns E_INVALIDARG from GetEvents. The removed WSLCE2E_Events_RejectsUnsupportedFilterBeforeResolvingSession case intentionally covered the opposite behavior, so events --session <missing> --filter label=... now reports a session error (and may start a VM) instead of the invalid-filter error. Keep event-specific key validation in the CLI path while retaining this server-side validation for COM callers.

    for (const auto& [key, values] : Filters)
    {
        THROW_HR_WITH_USER_ERROR_IF(
            E_INVALIDARG,
            Localization::MessageWslcInvalidFilter(wsl::shared::string::MultiByteToWide(key)),
            key != "type" && key != "event" && key != "container" && key != "image" && key != "network");
    }

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

[Blue (OneBlue)]

LGTM, minor comments. Feel free to fix in a followup

[Blue (OneBlue)]

I don't think this is needed anmore

[Blue (OneBlue)]

nit: Instead of doing this I would recommend replacing events.SendCtrlBreak(); by stopReader.reset()