wslc: idle-terminate per-user session VMs when inactive

src/windows/common/WSLCUserSettings.cpp

@@ -57,6 +57,9 @@ static constexpr std::string_view s_DefaultSettingsTemplate =
     "  # used without an explicit address (default: 127.0.0.1)\n"
     "  # defaultBindingAddress: default\n"
     "\n"
+    "  # Seconds an idle session VM stays running before it is torn down (default: 30)\n"
+    "  # idleTimeout: default\n"
+    "\n"
     "# Credential storage backend: \"wincred\" or \"file\" (default: wincred)\n"
     "# credentialStore: wincred\n";
 
@@ -163,6 +166,11 @@ namespace details {
         return value;
     }
 
+    WSLC_VALIDATE_SETTING(SessionIdleTimeout)
+    {
+        return value > 0 ? std::optional{value} : std::nullopt;
+    }
+
     WSLC_VALIDATE_SETTING(CredentialStore)
     {
         if (value == "wincred")

src/windows/common/WSLCUserSettings.h

@@ -45,6 +45,7 @@ enum class Setting : size_t
     SessionPortRelay,
     SessionDefaultBindingAddress,
     SessionStoragePath,
+    SessionIdleTimeout,
 
     Max
 };
@@ -101,6 +102,7 @@ namespace details {
     DEFINE_SETTING_MAPPING(SessionPortRelay,         std::string, PortRelayType,       PortRelayType::VirtioNet,      "experimental.portRelay")
     DEFINE_SETTING_MAPPING(SessionDefaultBindingAddress, std::string, std::string,     std::string{},                 "session.defaultBindingAddress")
     DEFINE_SETTING_MAPPING(SessionStoragePath,       std::string, std::string,         std::string{},                 "session.storagePath")
+    DEFINE_SETTING_MAPPING(SessionIdleTimeout,       uint32_t,    uint32_t,            30,                            "session.idleTimeout")
 
 #undef DEFINE_SETTING_MAPPING
     // clang-format on

src/windows/inc/WslPluginApi.h

@@ -141,6 +141,18 @@ typedef HRESULT (*WSLPluginAPI_ImageCreated)(const struct WSLCSessionInformation
 // Called when an image is deleted. 'ImageId' is the deleted image identifier. Errors are ignored.
 typedef HRESULT (*WSLPluginAPI_ImageDeleted)(const struct WSLCSessionInformation* Session, LPCSTR ImageId);
 
+// Called when the VM backing a WSLC session has started. Unlike OnSessionCreated (which fires once
+// per session), this fires every time a VM is created for the session: on the first operation that
+// needs a VM, and again each time the VM is recreated after being idle-terminated. Errors are logged
+// but ignored (they do not abort VM startup or the triggering operation).
+typedef HRESULT (*WSLPluginAPI_OnWslcVmStarted)(const struct WSLCSessionInformation* Session);
+
+// Called when the VM backing a WSLC session is about to stop (idle teardown, explicit termination,
+// or unexpected exit). Fires every time a VM is torn down, paired with a prior OnWslcVmStarted.
+// Errors are logged but ignored. The VM is going away, so this hook must not call back into the
+// session (e.g. via WSLCCreateProcess).
+typedef HRESULT (*WSLPluginAPI_OnWslcVmStopping)(const struct WSLCSessionInformation* Session);
+
 //
 // WSLC plugin API calls.
 //
@@ -220,6 +232,8 @@ struct WSLPluginHooksV1
     WSLPluginAPI_ContainerStopping ContainerStopping;
     WSLPluginAPI_ImageCreated ImageCreated;
     WSLPluginAPI_ImageDeleted ImageDeleted;
+    WSLPluginAPI_OnWslcVmStarted WslcVmStarted;
+    WSLPluginAPI_OnWslcVmStopping WslcVmStopping;
 };
 
 struct WSLPluginAPIV1

src/windows/service/exe/HcsVirtualMachine.cpp

@@ -350,7 +350,9 @@ HcsVirtualMachine::HcsVirtualMachine(_In_ const WSLCSessionSettings* Settings)
 
 HcsVirtualMachine::~HcsVirtualMachine()
 {
-    std::lock_guard lock(m_lock);
+    // Do not hold m_lock: waiting on m_vmExitEvent and closing the compute system below both block
+    // on in-flight HCS exit/crash callbacks, which may themselves need m_lock. OnExit() is lock-free,
+    // and closing the compute system drains all callbacks, so the rest of teardown needs no lock.
 
     // Wait up to 5 seconds for the VM to terminate gracefully.
     bool forceTerminate = false;

src/windows/service/exe/PluginManager.cpp

@@ -691,3 +691,41 @@ void PluginManager::OnWslcImageDeleted(const WSLCSessionInformation* Session, LP
         }
     }
 }
+
+void PluginManager::OnWslcVmStarted(const WSLCSessionInformation* Session) const
+{
+    ExecutionContext context(Context::Plugin);
+
+    for (const auto& e : m_plugins)
+    {
+        if (e.hooks.WslcVmStarted != nullptr)
+        {
+            const auto result = e.hooks.WslcVmStarted(Session);
+            WSL_LOG(
+                "PluginOnWslcVmStartedCall",
+                TraceLoggingValue(e.name.c_str(), "Plugin"),
+                TraceLoggingValue(Session->SessionId, "SessionId"),
+                TraceLoggingValue(result, "Result"));
+            LOG_IF_FAILED_MSG(result, "Error thrown from plugin: '%ls'", e.name.c_str());
+        }
+    }
+}
+
+void PluginManager::OnWslcVmStopping(const WSLCSessionInformation* Session) const
+{
+    ExecutionContext context(Context::Plugin);
+
+    for (const auto& e : m_plugins)
+    {
+        if (e.hooks.WslcVmStopping != nullptr)
+        {
+            const auto result = e.hooks.WslcVmStopping(Session);
+            WSL_LOG(
+                "PluginOnWslcVmStoppingCall",
+                TraceLoggingValue(e.name.c_str(), "Plugin"),
+                TraceLoggingValue(Session->SessionId, "SessionId"),
+                TraceLoggingValue(result, "Result"));
+            LOG_IF_FAILED_MSG(result, "Error thrown from plugin: '%ls'", e.name.c_str());
+        }
+    }
+}

src/windows/service/exe/PluginManager.h

@@ -52,6 +52,8 @@ class PluginManager
     void OnWslcContainerStopping(const WSLCSessionInformation* Session, LPCSTR ContainerId) const;
     void OnWslcImageCreated(const WSLCSessionInformation* Session, LPCSTR InspectJson) const;
     void OnWslcImageDeleted(const WSLCSessionInformation* Session, LPCSTR ImageId) const;
+    void OnWslcVmStarted(const WSLCSessionInformation* Session) const;
+    void OnWslcVmStopping(const WSLCSessionInformation* Session) const;
 
     void ThrowIfFatalPluginError() const;
 

src/windows/service/exe/WSLCPluginNotifier.cpp

@@ -64,3 +64,23 @@ try
     return S_OK;
 }
 CATCH_RETURN();
+
+HRESULT WSLCPluginNotifier::OnVmStarted()
+try
+{
+    COMServiceExecutionContext context;
+
+    m_plugins.OnWslcVmStarted(&m_sessionInfo);
+    return S_OK;
+}
+CATCH_RETURN();
+
+HRESULT WSLCPluginNotifier::OnVmStopping()
+try
+{
+    COMServiceExecutionContext context;
+
+    m_plugins.OnWslcVmStopping(&m_sessionInfo);
+    return S_OK;
+}
+CATCH_RETURN();

src/windows/service/exe/WSLCPluginNotifier.h

@@ -34,6 +34,8 @@ class DECLSPEC_UUID("E29B0F1A-4E18-4F09-83A2-2D6B1B9F8C4D") WSLCPluginNotifier
     IFACEMETHOD(OnContainerStopping)(_In_ LPCSTR ContainerId) override;
     IFACEMETHOD(OnImageCreated)(_In_ LPCSTR InspectJson) override;
     IFACEMETHOD(OnImageDeleted)(_In_ LPCSTR ImageId) override;
+    IFACEMETHOD(OnVmStarted)() override;
+    IFACEMETHOD(OnVmStopping)() override;
 
 private:
     wsl::windows::service::PluginManager& m_plugins;

src/windows/service/exe/WSLCSessionManager.cpp

@@ -121,6 +121,7 @@ struct SessionSettings
         Settings.MemoryMb = memoryMb > 0 ? memoryMb : SessionSettings::DefaultMemoryMb();
         Settings.MaximumStorageSizeMb = userSettings.Get<settings::Setting::SessionStorageSizeMb>();
         Settings.BootTimeoutMs = wsl::windows::wslc::DefaultBootTimeoutMs;
+        Settings.IdleTimeoutSec = userSettings.Get<settings::Setting::SessionIdleTimeout>();
         Settings.NetworkingMode = userSettings.Get<settings::Setting::SessionNetworkingMode>();
 
         // TODO: Add a config setting to opt-out of GPU support.
@@ -285,8 +286,7 @@ void WSLCSessionManagerImpl::CreateSession(
             g_pluginManager, sessionId, creatorPid, std::wstring(resolvedDisplayName), wil::shared_handle(sharedToken), std::vector<BYTE>(storedSid));
 
         // Create the VM factory in the SYSTEM service (privileged). The per-user session
-        // uses it to create the VM. Funneling VM creation through a factory lets the session
-        // own when VMs are created, rather than having one handed to it up front.
+        // uses it to create VMs on demand and recreate them after idle-termination.
         auto vmFactory = Microsoft::WRL::Make<WSLCVirtualMachineFactory>(Settings);
 
         // Launch per-user COM server factory and add it to a fresh per-session job object for crash cleanup.
@@ -473,6 +473,7 @@ WSLCSessionInitSettings WSLCSessionManagerImpl::CreateSessionSettings(
     sessionSettings.RootVhdTypeOverride = Settings->RootVhdTypeOverride;
     sessionSettings.StorageFlags = Settings->StorageFlags;
     sessionSettings.SwapSizeMb = Settings->MemoryMb;
+    sessionSettings.IdleTimeoutSec = Settings->IdleTimeoutSec;
     return sessionSettings;
 }
 

src/windows/service/inc/wslc.idl

@@ -125,6 +125,13 @@ interface IWSLCPluginNotifier : IUnknown
 
     // Called when an image is deleted. 'ImageId' is the image identifier. Errors are logged but ignored.
     HRESULT OnImageDeleted([in] LPCSTR ImageId);
+
+    // Called when the VM backing the session has started (first start or recreation after idle
+    // teardown). Errors are logged but ignored.
+    HRESULT OnVmStarted();
+
+    // Called when the VM backing the session is about to stop. Errors are logged but ignored.
+    HRESULT OnVmStopping();
 };
 
 typedef struct _WSLCImageInformation
@@ -461,6 +468,7 @@ typedef struct _WSLCSessionSettings {
     WSLCFeatureFlags FeatureFlags;
     WSLCHandle DmesgOutput;
     WSLCSessionStorageFlags StorageFlags;
+    ULONG IdleTimeoutSec;
 
     // Below options are used for debugging purposes only.
     [unique] LPCWSTR RootVhdOverride;
@@ -595,6 +603,7 @@ typedef struct _WSLCSessionInitSettings
     WSLCNetworkingMode NetworkingMode;
     WSLCFeatureFlags FeatureFlags;
     [unique] LPCSTR RootVhdTypeOverride;
+    ULONG IdleTimeoutSec;
 } WSLCSessionInitSettings;
 
 [
@@ -633,6 +642,14 @@ interface IWSLCSession : IUnknown
     // Container management.
     HRESULT CreateContainer([in] const WSLCContainerOptions* Options, [in, unique] IWarningCallback* WarningCallback, [out] IWSLCContainer** Container);
     HRESULT OpenContainer([in, ref] LPCSTR Id, [out] IWSLCContainer** Container);
+
+    // Keeps the VM alive for the duration of a client-side container operation. The CLI performs
+    // each mutation as two round-trips (OpenContainer followed by the operation) and may stream
+    // output afterwards. With on-demand VM idle-termination the VM could otherwise tear down
+    // between those calls, disconnecting the container wrapper and failing the second call with
+    // RPC_E_DISCONNECTED. The client holds the returned token for the whole operation; releasing
+    // it (or the client exiting) lets the VM idle-terminate again.
+    HRESULT BeginContainerOperation([out] IUnknown** Operation);
     HRESULT ListContainers([in, unique] const WSLCListContainersOptions* Options,[out, size_is(, *Count)] WSLCContainerEntry** Containers,[out] ULONG* Count, [out, size_is(, *PortsCount)] WSLCContainerPortMapping** Ports, [out] ULONG* PortsCount);
     HRESULT PruneContainers([in, unique, size_is(FiltersCount)] const WSLCFilter* Filters, [in] ULONG FiltersCount, [out] WSLCPruneContainersResults* Result);
 
@@ -682,6 +699,11 @@ interface IWSLCSession : IUnknown
     HRESULT PruneNetworks([in, unique, size_is(FiltersCount)] const WSLCFilter* Filters, [in] ULONG FiltersCount, [out, size_is(, *NetworksCount)] WSLCNetworkName** Networks, [out] ULONG* NetworksCount);
 
     HRESULT RegisterCrashDumpCallback([in] ICrashDumpCallback* Callback, [out] IUnknown** Subscription);
+
+    // Used only for testing. Synchronously runs the idle-termination teardown path, ignoring the
+    // activity-count and idle-timeout-enabled guards so a test can force the VM down even while a
+    // container holds an activity reference. WasAlreadyIdle is TRUE when the VM was not running.
+    HRESULT TriggerIdleTermination([out] BOOL* WasAlreadyIdle);
 }
 
 //

src/windows/wslc/services/ContainerService.cpp

@@ -296,6 +296,7 @@ std::wstring ContainerService::FormatRelativeTime(ULONGLONG timestamp)
 
 int ContainerService::Attach(Session& session, const std::string& id)
 {
+    auto operation = session.BeginContainerOperation();
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
 
@@ -457,6 +458,7 @@ CreateContainerResult ContainerService::Create(Session& session, const std::stri
 
 int ContainerService::Start(Session& session, const std::string& id, bool attach)
 {
+    auto operation = session.BeginContainerOperation();
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
     WSLCContainerStartFlags flags = attach ? WSLCContainerStartFlagsAttach : WSLCContainerStartFlagsNone;
@@ -487,20 +489,23 @@ int ContainerService::Start(Session& session, const std::string& id, bool attach
 
 void ContainerService::Stop(Session& session, const std::string& id, StopContainerOptions options)
 {
+    auto operation = session.BeginContainerOperation();
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
     THROW_IF_FAILED_EXCEPT(container->Stop(options.Signal, options.Timeout), WSLC_E_CONTAINER_NOT_RUNNING);
 }
 
 void ContainerService::Kill(Session& session, const std::string& id, WSLCSignal signal)
 {
+    auto operation = session.BeginContainerOperation();
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
     THROW_IF_FAILED(container->Kill(signal));
 }
 
 void ContainerService::Delete(Session& session, const std::string& id, bool force)
 {
+    auto operation = session.BeginContainerOperation();
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
     THROW_IF_FAILED(container->Delete(force ? WSLCDeleteFlagsForce : WSLCDeleteFlagsNone));
@@ -555,6 +560,7 @@ std::vector<ContainerInformation> ContainerService::List(
 
 int ContainerService::Exec(Session& session, const std::string& id, ContainerOptions options)
 {
+    auto operation = session.BeginContainerOperation();
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
 
@@ -586,6 +592,7 @@ int ContainerService::Exec(Session& session, const std::string& id, ContainerOpt
 
 InspectContainer ContainerService::Inspect(Session& session, const std::string& id)
 {
+    auto operation = session.BeginContainerOperation();
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
     wil::unique_cotaskmem_ansistring output;
@@ -604,6 +611,8 @@ void ContainerService::Export(Session& session, const std::string& id, const std
 
 void ContainerService::Export(Session& session, const std::string& id, HANDLE outputHandle)
 {
+    auto operation = session.BeginContainerOperation();
+
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
 
@@ -615,6 +624,7 @@ void ContainerService::Export(Session& session, const std::string& id, HANDLE ou
 
 void ContainerService::Logs(Session& session, const std::string& id, bool follow, bool timestamps, ULONGLONG since, ULONGLONG until, ULONGLONG tail)
 {
+    auto operation = session.BeginContainerOperation();
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
 
@@ -642,6 +652,7 @@ void ContainerService::Logs(Session& session, const std::string& id, bool follow
 
 wsl::windows::common::docker_schema::ContainerStats ContainerService::Stats(Session& session, const std::string& id)
 {
+    auto operation = session.BeginContainerOperation();
     wil::com_ptr<IWSLCContainer> container;
     THROW_IF_FAILED(session.Get()->OpenContainer(id.c_str(), &container));
     wil::unique_cotaskmem_ansistring output;

src/windows/wslc/services/SessionModel.h

@@ -31,6 +31,16 @@ struct Session
         return m_session.get();
     }
 
+    // Acquires an activity token that keeps the VM alive for the duration of a client-side
+    // container operation (resolve + operate, plus any streamed output). Hold the returned
+    // pointer for the whole operation; releasing it lets the VM idle-terminate again.
+    [[nodiscard]] wil::com_ptr<IUnknown> BeginContainerOperation() const
+    {
+        wil::com_ptr<IUnknown> operation;
+        THROW_IF_FAILED(m_session->BeginContainerOperation(&operation));
+        return operation;
+    }
+
 private:
     wil::com_ptr<IWSLCSession> m_session;
 };

src/windows/wslc/services/SessionService.cpp

@@ -56,11 +56,13 @@ Session SessionService::OpenOrCreateDefaultSession()
 {
     auto manager = CreateSessionManager();
 
-    // Null Settings = default session with server-determined name and settings.
+    // Null Settings = default session with server-determined name and settings. The warning callback
+    // is consumed during CreateSession (session initialization); it is not retained afterwards.
     wil::com_ptr<IWSLCSession> session;
     auto warningCallback = Microsoft::WRL::Make<WarningCallback>();
     THROW_IF_FAILED(manager->CreateSession(nullptr, WSLCSessionFlagsNone, warningCallback.Get(), &session));
     wsl::windows::common::security::ConfigureForCOMImpersonation(session.get());
+
     return Session(std::move(session));
 }
 

src/windows/wslcsession/CMakeLists.txt

@@ -9,6 +9,7 @@ set(SOURCES
 
     # Session and container implementation
     WSLCSession.cpp
+    WSLCSessionRuntime.cpp
     WSLCContainer.cpp
     WSLCVirtualMachine.cpp
 
@@ -44,6 +45,8 @@ set(HEADERS
     WSLCProcessControl.h
     WSLCProcessIO.h
     WSLCSession.h
+    WSLCSessionRuntime.h
+    WSLCIdleState.h
     WSLCSessionFactory.h
     WSLCSessionReference.h
     WSLCVirtualMachine.h

src/windows/wslcsession/IORelay.cpp

@@ -68,11 +68,20 @@ void IORelay::Stop()
     }
 }
 
+bool IORelay::IsRelayThread() const noexcept
+{
+    return m_thread.get_id() == std::this_thread::get_id();
+}
+
 void IORelay::Run()
 try
 {
     common::wslutil::SetThreadDescription(L"IORelay");
 
+    // Handle callbacks dispatched from this thread (e.g. unexpected VM exit) can tear the VM down,
+    // releasing cross-process COM proxies, so join the process MTA to avoid RPC_E_WRONG_THREAD.
+    const auto coInit = wil::CoInitializeEx(COINIT_MULTITHREADED);
+
     windows::common::io::MultiHandleWait io;
 
     // N.B. All the IO must happen on the thread.