feat: collapse plugin runtime to one tier behind a plugin SDK

plugins/docker/backend/console.ts

@@ -45,17 +45,57 @@ interface SSHSession {
 
 const activeSessions = new Map<string, SSHSession>();
 
-const wss = new WebSocketServer({
-  host: "127.0.0.1",
-  port: 30009,
-  maxPayload: MAX_WS_MESSAGE_BYTES,
-});
+const CONSOLE_PORT = 30009;
 
-wss.on("error", (error) => {
-  sshLogger.error("Docker console WebSocket server error", error, {
-    operation: "wss_error",
+/**
+ * Created by startConsoleServer(), not at module load.
+ *
+ * Importing this file used to bind the port as a side effect, which meant the
+ * plugin could not be disabled and re-enabled: the module stays in the ESM
+ * cache, so the second activate() got a server that had already been closed.
+ */
+let wss: WebSocketServer | null = null;
+
+function handleConnection(ws: WebSocket, req: import("http").IncomingMessage) {
+  void onConsoleConnection(ws, req);
+}
+
+/** Starts the console WebSocket server. Call from the plugin's activate(). */
+export function startConsoleServer(): Promise<void> {
+  if (wss) return Promise.resolve();
+
+  return new Promise((resolve, reject) => {
+    const server = new WebSocketServer({
+      host: "127.0.0.1",
+      port: CONSOLE_PORT,
+      maxPayload: MAX_WS_MESSAGE_BYTES,
+    });
+
+    const onStartupError = (error: Error) => {
+      server.off("listening", onListening);
+      wss = null;
+      reject(error);
+    };
+
+    const onListening = () => {
+      server.off("error", onStartupError);
+      // Past startup an error is logged rather than fatal: one bad socket
+      // must not take the server down.
+      server.on("error", (error) => {
+        sshLogger.error("Docker console WebSocket server error", error, {
+          operation: "wss_error",
+        });
+      });
+      resolve();
+    };
+
+    server.once("error", onStartupError);
+    server.once("listening", onListening);
+    server.on("connection", handleConnection);
+
+    wss = server;
   });
-});
+}
 
 async function detectShell(
   session: SSHSession,
@@ -296,7 +336,10 @@ async function createJumpHostChain(
   return currentClient;
 }
 
-wss.on("connection", async (ws: WebSocket, req) => {
+async function onConsoleConnection(
+  ws: WebSocket,
+  req: import("http").IncomingMessage,
+) {
   const token = extractWebSocketToken(req);
 
   if (!token) {
@@ -824,12 +867,17 @@ wss.on("connection", async (ws: WebSocket, req) => {
 
     cleanup();
   });
-});
+}
 
 /**
- * Closes every live console session and the WebSocket server. Called by the
- * plugin's deactivate() as well as SIGTERM, since disabling the docker
- * plugin has to free port 30009 the same way process shutdown does.
+ * Closes every live console session and the WebSocket server, freeing port
+ * 30009. Called from the plugin's deactivate().
+ *
+ * There is deliberately no process signal handler here. Core owns shutdown:
+ * gracefulShutdown in src/backend/starter.ts calls shutdownPlugins(), which
+ * runs every plugin's deactivate. A plugin calling process.exit() itself
+ * skipped the rest of that sequence, including other plugins and the
+ * database flush.
  */
 export function closeConsoleServer(): Promise<void> {
   activeSessions.forEach((session) => {
@@ -841,9 +889,10 @@ export function closeConsoleServer(): Promise<void> {
 
   activeSessions.clear();
 
-  return new Promise((resolve) => wss.close(() => resolve()));
-}
+  const server = wss;
+  wss = null;
+  if (!server) return Promise.resolve();
 
-process.on("SIGTERM", () => {
-  void closeConsoleServer().then(() => process.exit(0));
-});
+  server.off("connection", handleConnection);
+  return new Promise((resolve) => server.close(() => resolve()));
+}