Implement the WSLC plugin API by OneBlue · Pull Request #40521 · microsoft/WSL

OneBlue · 2026-05-13T06:44:15Z

Summary of the Pull Request

This change implements the WSLC plugin API.

Notable design changes:

All plugins are only loaded once, by wslservice.exe
Plugins remain loaded regardless of the WSL policies registry keys
User errors originated from plugins clearly say which plugin the error comes from

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

…-api-wslc

Copilot

Pull request overview

This PR implements the WSLC plugin API by extending the WSL plugin surface and wiring WSLC session/container/image notifications (plus a small WSLC control API) through wslservice.exe to loaded plugins, with corresponding end-to-end test coverage updates.

Changes:

Adds a WSLC-facing notifier COM interface and threads it through WSLC session creation and container/image lifecycle to notify plugins.
Extends WslPluginApi.h and PluginManager with WSLC plugin hooks and WSLC API calls (mount/unmount, create process, process IO helpers).
Refactors/extends Windows tests and the test plugin to validate WSLC callbacks and API calls.

Reviewed changes

Copilot reviewed 24 out of 25 changed files in this pull request and generated 15 comments.

Show a summary per file

File	Description
test/windows/WSLCTests.cpp	Switches to shared WSLC E2E helpers and updates session-list struct usage.
test/windows/wslc/e2e/WSLCE2EHelpers.cpp	Updates local registry helper to ensure the registry image exists in the target session.
test/windows/testplugin/Plugin.cpp	Adds WSLC hook implementations and exercises WSLC plugin API calls.
test/windows/PluginTests.h	Extends test-mode enum with WSLC test scenarios.
test/windows/PluginTests.cpp	Adds new WSLC plugin API tests (success, pull notification, rejection paths).
test/windows/Common.h / Common.cpp	Centralizes `LoadTestImage` and COM error validation helpers for reuse.
src/windows/wslcsession/WSLCSessionFactory.h / .cpp	Threads `IWSLCPluginNotifier` into session initialization.
src/windows/wslcsession/WSLCSession.h / .cpp	Stores notifier and emits image-created/image-deleted notifications; passes notifier to containers.
src/windows/wslcsession/WSLCContainer.h / .cpp	Emits container-start/container-stopping notifications via the notifier.
src/windows/wslc/services/SessionService.cpp	Updates to renamed session-list struct.
src/windows/service/inc/wslc.idl	Introduces `IWSLCPluginNotifier`, changes WSLC session factory/init signatures, renames session list entry struct.
src/windows/service/exe/WSLCSessionManager.h / .cpp	Creates and owns plugin notifier per session; triggers plugin session create/stop notifications; adds session lookup for plugin API calls.
src/windows/service/exe/ServiceMain.cpp	Loads plugins once at service startup (policy-independent); leaves an unload placeholder comment.
src/windows/service/exe/PluginManager.h / .cpp	Extends plugin API vtable with WSLC calls and adds WSLC hook dispatch.
src/windows/service/exe/LxssUserSessionFactory.cpp	Switches to global `g_pluginManager` loaded by service rather than per-policy instantiation.
src/windows/service/exe/CMakeLists.txt	Adds WSLC plugin notifier implementation sources/headers to the service build.
src/windows/inc/WslPluginApi.h	Defines WSLC plugin hooks + WSLC API call function pointers and related types.
msipackage/package.wix.in	Registers the `IWSLCPluginNotifier` interface for COM proxy/stub.

    // Creates a new session and returns both the session interface and a service reference.
    HRESULT CreateSession(
        [in] const WSLCSessionInitSettings* Settings,
        [in] IWSLCVirtualMachine* Vm,
+        [in, unique] IWSLCPluginNotifier* PluginNotifier,
        [out] IWSLCSession** Session,
        [out] IWSLCSessionReference** ServiceRef);


+    const auto pluginResult = m_pluginNotifier->OnContainerStarted(inspectJson.c_str());
+    if (FAILED(pluginResult))
+    {
+        // Forward the COM error message, if available.
+        auto comError = wsl::windows::common::wslutil::GetCOMErrorInfo();
+
+        LOG_HR_MSG(pluginResult, "Plugin rejected start of container '%hs' (0x%x)", m_id.c_str(), pluginResult);
+        try
+        {
+            m_dockerClient.StopContainer(m_id.c_str(), {}, {});
+        }
+        CATCH_LOG();
+
+        if (comError.has_value() && comError->Message)
+        {
+            THROW_HR_WITH_USER_ERROR(pluginResult, comError->Message.get());
+        }
+        else
+        {
+            THROW_HR(pluginResult);
+        }


benhillis

🤖 AI-generated review (GitHub Copilot CLI, Claude Opus 4.7, run by @benhillis).

This is automated feedback — please use your judgment on every item. I focused on correctness / lifetime / API contract issues and skipped style. Three items from a prior pass were already addressed in 581b849e / af4affd8 (dead UnloadPlugins, nullable notifier contract, path-traversal in WSLCMountFolder) — thanks for those. Remaining items are inline.

Separately: I noted in another context that this design is compatible with #40120 (out-of-process plugin host); the lock-held-across-callbacks point below is the one place where the two PRs would interact and would benefit from a fix in-tree regardless of #40120.

Copilot

Pull request overview

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

Copilot

Pull request overview

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

Copilot

Pull request overview

Copilot reviewed 26 out of 27 changed files in this pull request and generated 1 comment.

OneBlue added 15 commits May 11, 2026 15:11

Save state

6b33cfa

Merge remote-tracking branch 'origin/master' into user/oneblue/plugin…

7d8c361

…-api-wslc

Save state

d7fdcb5

Save state

5d5a22a

Save state

0724763

Save state

277c46e

Merge remote-tracking branch 'origin/master' into user/oneblue/plugin…

e91f5a2

…-api-wslc

Format

51bf4a0

Save state

816906f

Save state

4fe36c9

Format

992ad04

Save state

df5cb29

Save state

e2d2c83

Reorganize tests

d8125f4

Cleanup before review

02f11ac

Copilot AI review requested due to automatic review settings May 13, 2026 06:44

Copilot started reviewing on behalf of OneBlue May 13, 2026 06:45 View session

Copilot AI reviewed May 13, 2026

View reviewed changes

Add missing file

b1d2c6e

benhillis reviewed May 13, 2026

View reviewed changes

Comment thread src/windows/service/inc/wslc.idl Outdated

OneBlue added 3 commits May 13, 2026 16:03

Apply PR feedback

581b849

Apply PR feedback

af4affd

Format

72ecee9

benhillis reviewed May 14, 2026

View reviewed changes

OneBlue and others added 2 commits May 14, 2026 11:43

Apply PR feedback

9a8870a

Merge branch 'master' into user/oneblue/plugin-api-wslc

c23162c

OneBlue marked this pull request as ready for review May 14, 2026 22:27

OneBlue requested a review from a team as a code owner May 14, 2026 22:27

merge

e7d05a1

benhillis requested a review from Copilot May 15, 2026 19:25

Copilot started reviewing on behalf of benhillis May 15, 2026 19:30 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

Comment thread test/windows/testplugin/Plugin.cpp Outdated

Comment thread test/windows/wslc/e2e/WSLCE2EHelpers.cpp Outdated

Comment thread src/windows/inc/WslPluginApi.h Outdated

benhillis previously approved these changes May 15, 2026

View reviewed changes

Apply PR feedback

6d3b122

OneBlue dismissed benhillis’s stale review via 6d3b122 May 15, 2026 21:17

Format

5ef718a

Copilot AI review requested due to automatic review settings May 15, 2026 21:24

Copilot AI reviewed May 15, 2026

View reviewed changes

Comment thread src/windows/service/exe/PluginManager.cpp

Comment thread src/windows/inc/WslPluginApi.h

Comment thread test/windows/testplugin/Plugin.cpp

Comment thread src/windows/service/exe/PluginManager.cpp Outdated

Comment thread src/windows/service/inc/wslc.idl Outdated

Copilot started reviewing on behalf of OneBlue May 15, 2026 21:36 View session

OneBlue added 2 commits May 15, 2026 14:36

Apply PR feedback

6dcc846

Use iswalnum()

54685cf

Copilot AI review requested due to automatic review settings May 15, 2026 22:23

Copilot started reviewing on behalf of OneBlue May 15, 2026 22:26 View session

Copilot AI reviewed May 15, 2026

View reviewed changes

Comment thread src/windows/service/exe/PluginManager.cpp

OneBlue enabled auto-merge (squash) May 15, 2026 22:57

benhillis approved these changes May 15, 2026

View reviewed changes

OneBlue merged commit c9e4671 into master May 16, 2026
15 checks passed

OneBlue deleted the user/oneblue/plugin-api-wslc branch May 16, 2026 00:08

Conversation

OneBlue commented May 13, 2026

Summary of the Pull Request

PR Checklist

Detailed Description of the Pull Request / Additional comments

Validation Steps Performed

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

benhillis left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants