slidemind 0.3.19 → 0.4.0

package/src/workspace/server.mjs

@@ -0,0 +1,159 @@
+// The workspace's loopback HTTP server — skeleton. Binds 127.0.0.1 only, serves
+// GET /health (protocol version + draining, nothing else) and two bearer-protected
+// process routes the lifecycle needs (`/api/v1/status`, `/api/v1/stop`).
+// Everything else is the API lane's: pass `handle(req, res, ctx)` and it is
+// asked first for any other path; return false to fall through to 404.
+//
+// No process.exit anywhere: `close()` resolves once the listener and every
+// open socket are gone, and the process ends when nothing else holds it.
+
+import { timingSafeEqual } from "node:crypto";
+import http from "node:http";
+
+export const PROTOCOL_VERSION = 1;
+export const PREFERRED_PORT = 57103;
+export const LOOPBACK = "127.0.0.1";
+
+/**
+ * The port a workspace calls home when it has none remembered: 57103, or
+ * `SLIDEMIND_WORKSPACE_PORT`. The test preload gives every test file its own,
+ * so no test server ever takes the developer's real workspace port — one that
+ * did, while the real workspace restarted into new code, pushed it off its
+ * port and every link an agent had handed out with it (2026-10-11).
+ */
+export function homePort() {
+  const n = Number(process.env.SLIDEMIND_WORKSPACE_PORT);
+  return Number.isInteger(n) && n > 0 && n < 65536 ? n : PREFERRED_PORT;
+}
+
+export function sendJson(res, status, body) {
+  const data = JSON.stringify(body);
+  res.writeHead(status, {
+    "Content-Type": "application/json; charset=utf-8",
+    "Cache-Control": "no-store",
+    "Content-Length": Buffer.byteLength(data),
+  });
+  res.end(data);
+}
+
+export function sendError(res, status, code, message, { retryable = false } = {}) {
+  sendJson(res, status, { ok: false, error: { code, message, retryable } });
+}
+
+/** Constant-time bearer check against the descriptor's `cliBearer`. */
+export function authorizeBearer(req, bearer) {
+  const header = String(req.headers.authorization ?? "");
+  if (!bearer || !header.startsWith("Bearer ")) return false;
+  const got = Buffer.from(header.slice(7));
+  const want = Buffer.from(bearer);
+  return got.length === want.length && timingSafeEqual(got, want);
+}
+
+/**
+ * `createServer({ bearer, nonce, pendingJobs, pages, onStop, handle, ports })`
+ *   bearer/nonce  from the descriptor the daemon writes
+ *   pendingJobs() → number, reported by status/stop
+ *   pages()       → number of connected browser pages, reported by status
+ *   onStop()      → Promise, the daemon's drain; the response is sent after it
+ *   handle        optional `(req, res, ctx) => boolean|Promise<boolean>` for the API lane
+ *   ports         the ports to try in order (default homePort())
+ * Returns `{ server, listen(), close(), url }`; `listen()` tries each of `ports`
+ * and falls back to an ephemeral port when they are all taken (never touching
+ * whoever holds them).
+ */
+export function createServer({ bearer, nonce, pid = process.pid, pendingJobs = () => 0, pages = () => 0, onStop = async () => {}, handle = null, ports = [homePort()] } = {}) {
+  const state = { draining: false, url: null };
+  const sockets = new Set();
+
+  const server = http.createServer(async (req, res) => {
+    const url = new URL(req.url, `http://${LOOPBACK}`);
+    // Only the workspace's own pages may frame it (the plan and preview iframes):
+    // another site cannot lay it under its own page and steer a click onto Approve.
+    res.setHeader("Content-Security-Policy", "frame-ancestors 'self'");
+    res.setHeader("X-Frame-Options", "SAMEORIGIN");
+    // The Host must be exactly the bound loopback authority: a page on another
+    // origin rebinding a DNS name to 127.0.0.1 gets nothing.
+    if (state.url && req.headers.host !== new URL(state.url).host) {
+      return sendError(res, 421, "bad_host", "unexpected Host header");
+    }
+    if (req.method === "GET" && url.pathname === "/health") {
+      // a draining workspace is on its way out: nobody may reuse it
+      return sendJson(res, 200, { protocolVersion: PROTOCOL_VERSION, draining: state.draining });
+    }
+    if (state.draining && url.pathname !== "/api/v1/status") {
+      return sendError(res, 503, "workspace_stopping", "workspace is shutting down", { retryable: true });
+    }
+    if (url.pathname === "/api/v1/status" || url.pathname === "/api/v1/stop") {
+      if (!authorizeBearer(req, bearer)) return sendError(res, 401, "unauthorized", "missing or invalid bearer");
+      if (url.pathname === "/api/v1/status" && req.method === "GET") {
+        return sendJson(res, 200, {
+          ok: true,
+          protocolVersion: PROTOCOL_VERSION,
+          nonce,
+          pid,
+          draining: state.draining,
+          pendingJobs: pendingJobs(),
+          pages: pages(),
+        });
+      }
+      if (url.pathname === "/api/v1/stop" && req.method === "POST") {
+        if (!state.draining) {
+          state.draining = true;
+          state.stopping = Promise.resolve().then(onStop);
+        }
+        await state.stopping;
+        sendJson(res, 200, { ok: true, stopped: true, pendingJobs: pendingJobs() });
+        // Let the response reach the wire, then drop every socket so the listener closes.
+        res.on("finish", () => setTimeout(() => api.close(), 50));
+        return;
+      }
+      return sendError(res, 405, "method_not_allowed", "method not allowed");
+    }
+    try {
+      if (handle && (await handle(req, res, { url, state, bearer }))) return;
+    } catch (err) {
+      if (!res.headersSent) return sendError(res, 500, "internal", err?.message ?? "internal error");
+      return;
+    }
+    sendError(res, 404, "not_found", "no such route");
+  });
+  server.on("connection", (s) => {
+    sockets.add(s);
+    s.on("close", () => sockets.delete(s));
+  });
+
+  const api = {
+    server,
+    state,
+    get url() {
+      return state.url;
+    },
+    listen() {
+      // the same port across restarts keeps the page's origin, and with it its cookie
+      const order = [...new Set(ports.filter((p) => Number.isInteger(p) && p > 0 && p < 65536)), 0];
+      return new Promise((resolve, reject) => {
+        const tryPort = (i) => {
+          const port = order[i];
+          server.once("error", (err) => {
+            if ((err.code === "EADDRINUSE" || err.code === "EACCES") && port !== 0) return tryPort(i + 1);
+            reject(err);
+          });
+          server.listen(port, LOOPBACK, () => {
+            server.removeAllListeners("error");
+            state.url = `http://${LOOPBACK}:${server.address().port}`;
+            resolve(state.url);
+          });
+        };
+        tryPort(0);
+      });
+    },
+    close() {
+      return new Promise((resolve) => {
+        if (!server.listening) return resolve();
+        server.close(() => resolve());
+        for (const s of sockets) s.destroy();
+      });
+    },
+  };
+  return api;
+}