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()));
+}

plugins/docker/backend/index.mjs

@@ -118,10 +118,11 @@ export async function activate(ctx) {
     });
   }
 
-  // Importing console.js binds its WebSocket server on port 30009 as a
-  // module-scope side effect -- unchanged from before the move, see that
-  // file's own header.
+  // Importing console.js no longer binds anything: the server is started
+  // here so disabling the plugin frees port 30009 and re-enabling can take
+  // it again, even though the module stays in the ESM cache.
   consoleModule = await loadRelative("console");
+  await consoleModule.startConsoleServer();
 
   ctx.log.info(`Docker plugin listening on ${port} (console on 30009)`);
 }

plugins/docker/manifest.json

@@ -3,19 +3,25 @@
   "name": "Docker",
   "version": "1.0.0",
   "description": "Container management over SSH: list, inspect, start, stop and view logs for Docker or Podman containers, plus an interactive container console.",
-  "author": { "name": "Termix" },
+  "author": {
+    "name": "Termix"
+  },
   "license": "MIT",
   "repository": "https://github.com/Termix-SSH/Termix",
   "category": "Infrastructure",
   "icon": "Box",
-  "engine": { "termix": ">=2.9.0", "api": "1" },
-  "capabilities": {
-    "backend": true,
-    "frontend": true,
-    "electron": true,
-    "platforms": ["linux", "win32", "darwin"]
+  "engine": {
+    "termix": ">=2.9.0",
+    "api": "1"
   },
-  "permissions": ["process:transport-owner"],
+  "capabilities": [
+    "hosts:read",
+    "credentials:use",
+    "ssh:connect",
+    "network:serve",
+    "audit:read",
+    "ui:surface"
+  ],
   "contributes": {
     "tabs": [
       {
@@ -31,5 +37,8 @@
       "editorTab": "docker"
     }
   },
-  "sidecars": []
+  "backend": "backend/index.mjs",
+  "frontend": "frontend/index.mjs",
+  "locales": "locales",
+  "platforms": ["linux", "win32", "darwin"]
 }