Add API flags for creating & opening persistent sessions #14047

OneBlue · 2026-01-09T20:27:22Z

Summary of the Pull Request

This will be needed for the CLI to open & maintain its session across invocations

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

OneBlue · 2026-01-09T20:56:36Z

src/windows/wslaservice/inc/wslaservice.idl


    // Session managment.
-    HRESULT CreateSession([in] const struct WSLA_SESSION_SETTINGS* Settings, [out]IWSLASession** Session);
+    HRESULT CreateSession([in] const struct WSLA_SESSION_SETTINGS* Settings, WSLASessionFlags Flags, [out]IWSLASession** Session);


@kevpar: This is one of the API changes that I mentioned. This will allow a caller to specify that a session should outlive its last COM client reference.

The WSLASessionFlagsOpenExisting flag will make it easy for the CLI to have a "create-or-open" logic when setting up its COM session

benhillis · 2026-01-09T21:32:38Z

For persistent sessions what are you thinking for lifetime of the VM? We likely want to clean it up after some period of inactivity.

OneBlue · 2026-01-09T21:58:23Z

For persistent sessions what are you thinking for lifetime of the VM? We likely want to clean it up after some period of inactivity.

This is something that we still need to design. Most likely we're going to need some form of configuration file for the container CLI, and in it we can have an inactivity timeout, similar to what we do in WSL

Copilot

Pull request overview

This PR adds API flags for creating and opening persistent WSL sessions that can outlive their COM reference lifetime. The main purpose is to support the CLI's ability to maintain sessions across invocations by introducing WSLASessionFlagsPersistent and WSLASessionFlagsOpenExisting flags.

Changes:

Added session flag enums (WSLASessionFlagsPersistent, WSLASessionFlagsOpenExisting) to control session lifecycle behavior
Removed the deprecated IWSLAVirtualMachine interface and migrated its functionality to IWSLASession
Replaced Shutdown() with Terminate() and changed WSLAVirtualMachine from a COM object to an internal std::optional member
Added comprehensive test coverage for persistent session behavior including creation, reopening, and termination

Reviewed changes

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

Show a summary per file

File	Description
src/windows/wslaservice/inc/wslaservice.idl	Added WSLASessionFlags enum, updated CreateSession signature, removed IWSLAVirtualMachine interface, renamed Shutdown to Terminate, added testing methods to IWSLASession
src/windows/wslaservice/exe/WSLAUserSession.h	Added m_persistentSessions vector to store strong references, updated CreateSession signature, added logic to remove terminated persistent sessions
src/windows/wslaservice/exe/WSLAUserSession.cpp	Implemented session lookup by name with OpenExisting flag support, added persistent session reference management
src/windows/wslaservice/exe/WSLASession.h	Changed m_virtualMachine from ComPtr to std::optional, renamed Shutdown to Terminate, added Terminated() method, moved VM methods from IWSLAVirtualMachine
src/windows/wslaservice/exe/WSLASession.cpp	Refactored Terminate() to be callable explicitly, moved VM operation wrappers from deleted interface, changed VM initialization to use emplace
src/windows/wslaservice/exe/WSLAVirtualMachine.h	Removed COM interface inheritance, changed methods from HRESULT-returning to void/exception-throwing
src/windows/wslaservice/exe/WSLAVirtualMachine.cpp	Removed WaitPid, Shutdown methods, changed MapPort/Unmount/Signal to throw exceptions instead of returning HRESULT
src/windows/wslaservice/exe/WSLAContainer.cpp	Updated MapPort calls to use try/catch instead of LOG_IF_FAILED since it now throws
src/windows/wslaservice/exe/WSLAProcessControl.cpp	Updated Signal call to handle void return type
src/windows/common/WslClient.cpp	Updated CreateSession call to pass WSLASessionFlagsNone, removed IWSLAVirtualMachine usage
test/windows/WSLATests.cpp	Updated all tests to use new API, replaced Shutdown with session.reset() or Terminate(), added PersistentSession test with comprehensive coverage, removed test for process creation after VM termination
src/shared/inc/lxinitshared.h	Removed WSLA_WAITPID, WSLA_WAITPID_RESULT, and WSLA_SHUTDOWN message structures
src/linux/init/WSLAInit.cpp	Removed HandleMessageImpl for WSLA_WAITPID, removed WSLA_WAITPID from HandleMessage template list
msipackage/package.wix.in	Removed registry entries for WSLAVirtualMachine and IWSLAVirtualMachine COM classes

Copilot · 2026-01-10T19:05:43Z

test/windows/WSLATests.cpp

+            expectSessions({});
+        }
+
+        // Validate that persistent sessions are only dropped when explicitely terminated.


Spelling error: "explicitely" should be "explicitly".

Suggested change

// Validate that persistent sessions are only dropped when explicitely terminated.

// Validate that persistent sessions are only dropped when explicitly terminated.

Copilot · 2026-01-10T19:05:44Z

src/shared/inc/lxinitshared.h


    PRETTY_PRINT(FIELD(Header), FIELD(Pid), FIELD(Signal));
 };



The Linux side still references LxMessageWSLAShutdown in line 832 of WSLAInit.cpp but the WSLA_SHUTDOWN message structure has been removed from lxinitshared.h. While this won't cause immediate issues since the message is never sent, this is now dead code. The check for LxMessageWSLAShutdown should be removed from the Linux-side message processing loop to maintain consistency with the removal of the WSLA_SHUTDOWN message type.

Suggested change

struct WSLA_SHUTDOWN

{

static inline auto Type = LxMessageWSLAShutdown;

using TResponse = RESULT_MESSAGE<int32_t>;

DECLARE_MESSAGE_CTOR(WSLA_SHUTDOWN);

MESSAGE_HEADER Header;

PRETTY_PRINT(FIELD(Header));

};

Copilot · 2026-01-10T19:05:44Z

test/windows/WSLATests.cpp

            // Validate that the process object correctly handle requests after the VM has terminated.
-            VERIFY_SUCCEEDED(session->Shutdown(30 * 1000));
+            session.reset();
            VERIFY_ARE_EQUAL(process.Get().Signal(WSLASignalSIGKILL), HRESULT_FROM_WIN32(ERROR_INVALID_STATE));
        }


The deleted test case validated that processes cannot be created after the VM is terminated. This is important functionality that ensures the API returns the correct error when attempting to create processes in an invalid state. Removing this test case reduces test coverage for the error handling path in CreateRootNamespaceProcess. Consider keeping this test or adding an equivalent test for the Terminate() functionality.

Copilot · 2026-01-10T19:05:44Z

src/windows/wslaservice/exe/WSLAUserSession.cpp

+        // TODO: ACL check.
+        if (session.DisplayName() == Settings->DisplayName)


The TODO comment "ACL check" indicates that security checks are missing. When opening an existing persistent session by name, the code should verify that the caller has permission to access that session. Without ACL checks, any user could potentially open and control sessions created by other users in the same user session context, which could be a security concern depending on the deployment model.

Copilot · 2026-01-10T19:05:44Z

test/windows/WSLATests.cpp

+            auto session1Copy =
+                create(L"session-1", static_cast<WSLASessionFlags>(WSLASessionFlagsPersistent | WSLASessionFlagsOpenExisting));


The test creates a session with both WSLASessionFlagsPersistent and WSLASessionFlagsOpenExisting flags combined, but there's no explicit test coverage for the error case where WSLASessionFlagsOpenExisting is specified without an existing session. The code should return an appropriate error (likely ERROR_NOT_FOUND) in this case, and this behavior should be tested to ensure the API contract is clear.

OneBlue added 3 commits January 9, 2026 12:24

Add API flags for creating & opening persistent sessions

fdfc5ec

Properly handle session name conflicts

5780ad9

Format

1ef6391

OneBlue commented Jan 9, 2026

View reviewed changes

OneBlue added 2 commits January 9, 2026 14:00

Format

c232800

Fix broken port mapping logic

d9cff57

OneBlue marked this pull request as ready for review January 10, 2026 19:01

OneBlue requested a review from a team as a code owner January 10, 2026 19:01

Copilot AI review requested due to automatic review settings January 10, 2026 19:01

Copilot started reviewing on behalf of OneBlue January 10, 2026 19:01 View session

Copilot AI reviewed Jan 10, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

Add API flags for creating & opening persistent sessions #14047

Add API flags for creating & opening persistent sessions #14047

OneBlue commented Jan 9, 2026

Uh oh!

OneBlue Jan 9, 2026

Uh oh!

benhillis commented Jan 9, 2026

Uh oh!

OneBlue commented Jan 9, 2026 •

edited

Loading

Uh oh!

Copilot AI left a comment

Uh oh!

Copilot AI Jan 10, 2026

Uh oh!

Copilot AI Jan 10, 2026

Uh oh!

Copilot AI Jan 10, 2026

Uh oh!

Copilot AI Jan 10, 2026

Uh oh!

Copilot AI Jan 10, 2026

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

	// Validate that persistent sessions are only dropped when explicitely terminated.
	// Validate that persistent sessions are only dropped when explicitly terminated.

+struct WSLA_SHUTDOWN
+{
+    static inline auto Type = LxMessageWSLAShutdown;
+    using TResponse = RESULT_MESSAGE<int32_t>;
+    DECLARE_MESSAGE_CTOR(WSLA_SHUTDOWN);
+    MESSAGE_HEADER Header;
+    PRETTY_PRINT(FIELD(Header));
+};

		// TODO: ACL check.
		if (session.DisplayName() == Settings->DisplayName)

		auto session1Copy =
		create(L"session-1", static_cast<WSLASessionFlags>(WSLASessionFlagsPersistent \| WSLASessionFlagsOpenExisting));

Add API flags for creating & opening persistent sessions #14047

Are you sure you want to change the base?

Add API flags for creating & opening persistent sessions #14047

Conversation

OneBlue commented Jan 9, 2026

Summary of the Pull Request

PR Checklist

Detailed Description of the Pull Request / Additional comments

Validation Steps Performed

Uh oh!

OneBlue Jan 9, 2026

Choose a reason for hiding this comment

Uh oh!

benhillis commented Jan 9, 2026

Uh oh!

OneBlue commented Jan 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Copilot AI Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Jan 10, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

OneBlue commented Jan 9, 2026 •

edited

Loading