@cfbender/cesium 0.3.5

package/src/server/api.ts

@@ -0,0 +1,166 @@
+// API route handler for interactive artifact submissions and state queries.
+//
+// Routes:
+//   POST /api/sessions/:projectSlug/:filename/answers/:questionId
+//   GET  /api/sessions/:projectSlug/:filename/state
+//
+// Wire into startServer via handle.addHandler() before the static file fallback.
+
+import { join, resolve, relative } from "node:path";
+import { submitAnswer, getState } from "../storage/mutate.ts";
+import type { AnswerValue } from "../render/validate.ts";
+
+export interface ApiHandlerOptions {
+  stateDir: string;
+}
+
+// Artifact filename regex: <iso-utc>__<slug>__<6char>.html
+// Permissive form: no path separators + ends with .html
+const FILENAME_RE = /^[^/\\]+\.html$/;
+const DANGEROUS_RE = /[/\\]|\.\./;
+
+function jsonResponse(body: unknown, status: number): Response {
+  return new Response(JSON.stringify(body), {
+    status,
+    headers: {
+      "Content-Type": "application/json; charset=utf-8",
+      "Cache-Control": "no-store",
+    },
+  });
+}
+
+export function createApiHandler(
+  options: ApiHandlerOptions,
+): (req: Request) => Promise<Response | undefined> {
+  const { stateDir } = options;
+
+  return async (req: Request): Promise<Response | undefined> => {
+    const url = new URL(req.url);
+    const { pathname } = url;
+
+    // Only handle /api/ routes
+    if (!pathname.startsWith("/api/")) {
+      return undefined;
+    }
+
+    // ─── Route matching ────────────────────────────────────────────────────
+    // POST /api/sessions/:projectSlug/:filename/answers/:questionId
+    const answerMatch = /^\/api\/sessions\/([^/]+)\/([^/]+)\/answers\/([^/]+)$/.exec(pathname);
+    // GET  /api/sessions/:projectSlug/:filename/state
+    const stateMatch = /^\/api\/sessions\/([^/]+)\/([^/]+)\/state$/.exec(pathname);
+
+    if (answerMatch === null && stateMatch === null) {
+      // Unrecognized /api/ path
+      return jsonResponse({ ok: false, error: "not found" }, 404);
+    }
+
+    const match = (answerMatch ?? stateMatch)!;
+    const projectSlug = match[1]!;
+    const filename = match[2]!;
+
+    // ─── Input validation ──────────────────────────────────────────────────
+    if (DANGEROUS_RE.test(projectSlug) || DANGEROUS_RE.test(filename)) {
+      return jsonResponse({ ok: false, error: "invalid path component" }, 400);
+    }
+
+    if (!FILENAME_RE.test(filename)) {
+      return jsonResponse({ ok: false, error: "filename must end with .html" }, 400);
+    }
+
+    // ─── Path traversal defense ────────────────────────────────────────────
+    const artifactsDir = join(stateDir, "projects", projectSlug, "artifacts");
+    const artifactPath = join(artifactsDir, filename);
+
+    const resolvedArtifactsDir = resolve(artifactsDir);
+    const resolvedArtifact = resolve(artifactPath);
+    const rel = relative(resolvedArtifactsDir, resolvedArtifact);
+    if (rel.startsWith("..") || rel.includes("/")) {
+      return jsonResponse({ ok: false, error: "invalid path" }, 400);
+    }
+
+    // ─── Route dispatch ────────────────────────────────────────────────────
+
+    if (answerMatch !== null) {
+      // POST /api/sessions/:projectSlug/:filename/answers/:questionId
+      if (req.method !== "POST") {
+        return jsonResponse({ ok: false, error: "method not allowed" }, 404);
+      }
+
+      const questionId = answerMatch[3]!;
+
+      // Parse body
+      let body: unknown;
+      try {
+        body = await req.json();
+      } catch {
+        return jsonResponse({ ok: false, error: "invalid JSON body" }, 400);
+      }
+
+      if (
+        body === null ||
+        typeof body !== "object" ||
+        Array.isArray(body) ||
+        !("value" in (body as Record<string, unknown>))
+      ) {
+        return jsonResponse({ ok: false, error: 'body must contain a "value" field' }, 400);
+      }
+
+      const value = (body as Record<string, unknown>)["value"] as AnswerValue;
+
+      const outcome = await submitAnswer({ artifactPath: resolvedArtifact, questionId, value });
+
+      if (outcome.ok) {
+        return jsonResponse(
+          {
+            ok: true,
+            status: outcome.status,
+            remaining: outcome.remaining,
+            replacementHtml: outcome.replacementHtml,
+          },
+          200,
+        );
+      }
+
+      switch (outcome.reason) {
+        case "not-found":
+        case "not-interactive":
+        case "unknown-question":
+          return jsonResponse({ ok: false, reason: outcome.reason }, 404);
+        case "session-ended":
+          return jsonResponse({ ok: false, status: outcome.status }, 410);
+        case "expired":
+          return jsonResponse({ ok: false, status: "expired" }, 410);
+        case "invalid-value":
+          return jsonResponse({ ok: false, message: outcome.message }, 422);
+      }
+
+      // Fallback (should not reach)
+      return jsonResponse({ ok: false, error: "internal error" }, 500);
+    }
+
+    if (stateMatch !== null) {
+      // GET /api/sessions/:projectSlug/:filename/state
+      if (req.method !== "GET") {
+        return jsonResponse({ ok: false, error: "method not allowed" }, 404);
+      }
+
+      const outcome = await getState(resolvedArtifact);
+
+      if (!outcome.ok) {
+        return jsonResponse({ ok: false, reason: outcome.reason }, 404);
+      }
+
+      return jsonResponse(
+        {
+          status: outcome.status,
+          answers: outcome.answers,
+          remaining: outcome.remaining,
+        },
+        200,
+      );
+    }
+
+    // Should not reach here
+    return jsonResponse({ ok: false, error: "not found" }, 404);
+  };
+}

package/src/server/http.ts

@@ -0,0 +1,195 @@
+// Bun HTTP server bound to 127.0.0.1 (default), serving the cesium state directory.
+
+import { resolve, extname } from "node:path";
+import { readFile } from "node:fs/promises";
+
+export interface ServerHandle {
+  port: number;
+  url: string; // "http://127.0.0.1:<port>"
+  stop(): Promise<void>;
+  onRequest(handler: () => void): void; // for idle-tracking; lifecycle attaches a callback
+  /** Register a pre-static handler. Returns a Response to short-circuit, or undefined to fall through. */
+  addHandler(handler: (req: Request) => Promise<Response | undefined>): void;
+}
+
+export interface StartServerArgs {
+  stateDir: string; // absolute, served as the root
+  port: number; // exact port to bind; lifecycle handles conflict scanning
+  hostname?: string; // default "127.0.0.1"
+}
+
+const MIME_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".htm": "text/html; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".js": "application/javascript; charset=utf-8",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".txt": "text/plain; charset=utf-8",
+  ".md": "text/plain; charset=utf-8",
+};
+
+const NOT_FOUND_HTML = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>404</title>
+<style>
+  body{font-family:system-ui,sans-serif;background:#faf9f5;color:#141413;
+       display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0}
+  .box{text-align:center}h1{font-size:2rem;margin:0 0 .5rem}p{color:#87867f;margin:0}
+</style>
+</head>
+<body><div class="box"><h1>404</h1><p>not found</p></div></body>
+</html>`;
+
+const FORBIDDEN_HTML = `<!doctype html>
+<html lang="en">
+<head><meta charset="utf-8"><title>403</title>
+<style>
+  body{font-family:system-ui,sans-serif;background:#faf9f5;color:#141413;
+       display:flex;align-items:center;justify-content:center;min-height:100vh;margin:0}
+  .box{text-align:center}h1{font-size:2rem;margin:0 0 .5rem}p{color:#87867f;margin:0}
+</style>
+</head>
+<body><div class="box"><h1>403</h1><p>forbidden</p></div></body>
+</html>`;
+
+function mimeFor(filePath: string): string {
+  const ext = extname(filePath).toLowerCase();
+  return MIME_TYPES[ext] ?? "application/octet-stream";
+}
+
+export async function startServer(args: StartServerArgs): Promise<ServerHandle> {
+  const { stateDir, port, hostname = "127.0.0.1" } = args;
+  const stateDirResolved = resolve(stateDir);
+  const requestHandlers: Array<() => void> = [];
+  const preHandlers: Array<(req: Request) => Promise<Response | undefined>> = [];
+
+  const server = Bun.serve({
+    hostname,
+    port,
+    async fetch(req) {
+      // Notify idle tracker
+      for (const h of requestHandlers) {
+        h();
+      }
+
+      // Run pre-static handlers (e.g. API routes) before serving static files
+      for (const handler of preHandlers) {
+        const result = await handler(req);
+        if (result !== undefined) {
+          return result;
+        }
+      }
+
+      if (req.method !== "GET") {
+        return new Response("Method Not Allowed", { status: 405 });
+      }
+
+      const url = new URL(req.url);
+      // Decode and normalize the request path
+      let reqPath: string;
+      try {
+        reqPath = decodeURIComponent(url.pathname);
+      } catch {
+        return new Response(NOT_FOUND_HTML, {
+          status: 404,
+          headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
+      }
+
+      // Resolve the absolute path under stateDir
+      // Use resolve with stateDir as root to prevent traversal
+      const joined = resolve(stateDirResolved, "." + reqPath);
+
+      // Path traversal defense: resolved path must be rooted at stateDir
+      if (!joined.startsWith(stateDirResolved + "/") && joined !== stateDirResolved) {
+        return new Response(FORBIDDEN_HTML, {
+          status: 403,
+          headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
+      }
+
+      // Determine final file path: if directory, try index.html
+      let filePath = joined;
+      const trailingSlash = reqPath.endsWith("/");
+
+      // Check if it's a directory by trying index.html
+      const indexPath = filePath.endsWith("/") ? filePath + "index.html" : filePath + "/index.html";
+
+      // Try as-is first, then as directory index
+      let fileToServe = filePath;
+      let isDir = false;
+
+      // If path has no extension or trailing slash, it might be a directory
+      if (trailingSlash || extname(filePath) === "") {
+        isDir = true;
+        fileToServe = filePath.endsWith("/") ? filePath + "index.html" : filePath + "/index.html";
+      }
+
+      const bunFile = Bun.file(fileToServe);
+      let exists = await bunFile.exists();
+
+      if (!exists && !isDir) {
+        // Try as directory index (e.g. /sub → /sub/index.html)
+        fileToServe = indexPath;
+        const bunFileIdx = Bun.file(fileToServe);
+        exists = await bunFileIdx.exists();
+        if (!exists) {
+          return new Response(NOT_FOUND_HTML, {
+            status: 404,
+            headers: { "Content-Type": "text/html; charset=utf-8" },
+          });
+        }
+      } else if (!exists) {
+        return new Response(NOT_FOUND_HTML, {
+          status: 404,
+          headers: { "Content-Type": "text/html; charset=utf-8" },
+        });
+      }
+
+      const contentType = mimeFor(fileToServe);
+      const finalFile = Bun.file(fileToServe);
+      const size = finalFile.size;
+
+      // Large files (>= 1MB): stream; small files: read fully
+      const ONE_MB = 1024 * 1024;
+      if (size >= ONE_MB) {
+        return new Response(finalFile.stream(), {
+          status: 200,
+          headers: { "Content-Type": contentType },
+        });
+      }
+
+      const buf = await readFile(fileToServe);
+      return new Response(buf, {
+        status: 200,
+        headers: { "Content-Type": contentType },
+      });
+    },
+  });
+
+  const actualPort = server.port;
+  if (actualPort === undefined) {
+    await server.stop();
+    throw new Error("cesium: server.port is undefined after Bun.serve (unexpected)");
+  }
+  const serverUrl = `http://${hostname}:${actualPort}`;
+
+  return {
+    port: actualPort,
+    url: serverUrl,
+    stop: async () => {
+      await server.stop();
+    },
+    onRequest: (handler: () => void) => {
+      requestHandlers.push(handler);
+    },
+    addHandler: (handler: (req: Request) => Promise<Response | undefined>) => {
+      preHandlers.push(handler);
+    },
+  };
+}

package/src/server/lifecycle.ts

@@ -0,0 +1,331 @@
+// Lazy server start, idle shutdown, and PID file management.
+
+import { join } from "node:path";
+import { readFileSync, unlinkSync } from "node:fs";
+import { unlink, writeFile } from "node:fs/promises";
+import { startServer, type ServerHandle } from "./http.ts";
+import { acquireLock } from "../storage/lock.ts";
+import { createApiHandler } from "./api.ts";
+
+export interface LifecycleConfig {
+  stateDir: string;
+  port: number; // start port for scan
+  portMax: number; // upper bound (inclusive)
+  idleTimeoutMs: number;
+  hostname?: string; // default "127.0.0.1"
+}
+
+export interface RunningInfo {
+  port: number;
+  url: string;
+  pid: number;
+  startedAt: string; // ISO UTC
+}
+
+export interface PidFileContent {
+  pid: number;
+  port: number;
+  hostname: string;
+  startedAt: string;
+}
+
+// ─── Module-level singleton ───────────────────────────────────────────────────
+
+let currentHandle: ServerHandle | null = null;
+let currentInfo: RunningInfo | null = null;
+let idleInterval: ReturnType<typeof setInterval> | null = null;
+let lastRequestAt: number = Date.now();
+let exitHandler: (() => void) | null = null;
+let sigTermHandler: (() => void) | null = null;
+let sigIntHandler: (() => void) | null = null;
+let currentPidFilePath: string | null = null;
+
+// ─── PID file helpers ─────────────────────────────────────────────────────────
+
+export function readPidFile(path: string): PidFileContent | null {
+  try {
+    const raw = readFileSync(path, "utf8");
+    const parsed: unknown = JSON.parse(raw);
+    if (
+      parsed !== null &&
+      typeof parsed === "object" &&
+      !Array.isArray(parsed) &&
+      "pid" in parsed &&
+      "port" in parsed &&
+      "hostname" in parsed &&
+      "startedAt" in parsed &&
+      typeof (parsed as Record<string, unknown>)["pid"] === "number" &&
+      typeof (parsed as Record<string, unknown>)["port"] === "number" &&
+      typeof (parsed as Record<string, unknown>)["hostname"] === "string" &&
+      typeof (parsed as Record<string, unknown>)["startedAt"] === "string"
+    ) {
+      const p = parsed as Record<string, unknown>;
+      return {
+        pid: p["pid"] as number,
+        port: p["port"] as number,
+        hostname: p["hostname"] as string,
+        startedAt: p["startedAt"] as string,
+      };
+    }
+    return null;
+  } catch {
+    return null;
+  }
+}
+
+export async function writePidFile(path: string, content: PidFileContent): Promise<void> {
+  await writeFile(path, JSON.stringify(content, null, 2), "utf8");
+}
+
+export function isAlive(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (err) {
+    const e = err as NodeJS.ErrnoException;
+    if (e.code === "ESRCH") return false;
+    // EPERM → process exists but owned by different user
+    if (e.code === "EPERM") return true;
+    return false;
+  }
+}
+
+// ─── Idle timer management ────────────────────────────────────────────────────
+
+function clearIdleTimer(): void {
+  if (idleInterval !== null) {
+    clearInterval(idleInterval);
+    idleInterval = null;
+  }
+}
+
+function startIdleTimer(idleTimeoutMs: number): void {
+  clearIdleTimer();
+  // 0 (or negative) means "never time out" — used by `cesium serve` in the
+  // foreground, where the user expects the server to live until they Ctrl-C.
+  if (idleTimeoutMs <= 0) return;
+  // Check every 10% of the timeout (but at least every 5s, at most every 60s)
+  const checkMs = Math.max(5_000, Math.min(60_000, Math.floor(idleTimeoutMs / 10)));
+  const interval = setInterval(() => {
+    if (Date.now() - lastRequestAt > idleTimeoutMs) {
+      void stopRunning(currentPidFilePath ? currentPidFilePath.replace(/\/.server\.pid$/, "") : "");
+    }
+  }, checkMs);
+  // Unref so the interval doesn't keep the process alive
+  interval.unref();
+  idleInterval = interval;
+}
+
+// ─── Signal / exit handler management ────────────────────────────────────────
+
+function removeSignalHandlers(): void {
+  if (sigTermHandler !== null) {
+    process.removeListener("SIGTERM", sigTermHandler);
+    sigTermHandler = null;
+  }
+  if (sigIntHandler !== null) {
+    process.removeListener("SIGINT", sigIntHandler);
+    sigIntHandler = null;
+  }
+  if (exitHandler !== null) {
+    process.removeListener("exit", exitHandler);
+    exitHandler = null;
+  }
+}
+
+function installSignalHandlers(pidFilePath: string): void {
+  removeSignalHandlers();
+
+  sigTermHandler = () => {
+    void stopRunning(pidFilePath.replace(/\/.server\.pid$/, "")).finally(() => {
+      process.exit(0);
+    });
+  };
+
+  sigIntHandler = () => {
+    void stopRunning(pidFilePath.replace(/\/.server\.pid$/, "")).finally(() => {
+      process.exit(0);
+    });
+  };
+
+  // Synchronous exit handler — last resort PID file cleanup
+  exitHandler = () => {
+    try {
+      unlinkSync(pidFilePath);
+    } catch {
+      // ignore ENOENT and any other error
+    }
+  };
+
+  process.on("SIGTERM", sigTermHandler);
+  process.on("SIGINT", sigIntHandler);
+  process.on("exit", exitHandler);
+}
+
+// ─── Core lifecycle ───────────────────────────────────────────────────────────
+
+export async function stopRunning(stateDir: string): Promise<void> {
+  clearIdleTimer();
+  removeSignalHandlers();
+
+  const handle = currentHandle;
+  currentHandle = null;
+  currentInfo = null;
+  const pidPath = currentPidFilePath;
+  currentPidFilePath = null;
+  lastRequestAt = Date.now();
+
+  if (handle !== null) {
+    try {
+      await handle.stop();
+    } catch {
+      // best-effort
+    }
+  }
+
+  if (pidPath !== null) {
+    try {
+      await unlink(pidPath);
+    } catch {
+      // ENOENT is fine
+    }
+  } else if (stateDir) {
+    try {
+      await unlink(join(stateDir, ".server.pid"));
+    } catch {
+      // ENOENT is fine
+    }
+  }
+}
+
+export async function ensureRunning(cfg: LifecycleConfig): Promise<RunningInfo> {
+  const { stateDir, port, portMax, idleTimeoutMs, hostname = "127.0.0.1" } = cfg;
+  const pidFilePath = join(stateDir, ".server.pid");
+  const lockPath = join(stateDir, ".server-start.lock");
+
+  // Fast path: already running in this process
+  if (currentHandle !== null && currentInfo !== null) {
+    return currentInfo;
+  }
+
+  const lock = await acquireLock({ lockPath, timeoutMs: 10_000, staleMs: 30_000 });
+  try {
+    // Re-check after acquiring lock (another concurrent call may have started it)
+    if (currentHandle !== null && currentInfo !== null) {
+      return currentInfo;
+    }
+
+    // Read existing PID file
+    const existing = readPidFile(pidFilePath);
+    if (existing !== null) {
+      if (existing.pid === process.pid) {
+        // Our own PID but no in-process handle — stale from a previous test reset or crash
+        // Fall through to start new
+      } else if (isAlive(existing.pid)) {
+        // Another process owns this server
+        const info: RunningInfo = {
+          port: existing.port,
+          url: `http://${existing.hostname}:${existing.port}`,
+          pid: existing.pid,
+          startedAt: existing.startedAt,
+        };
+        return info;
+      }
+      // Stale — delete and start fresh
+      try {
+        await unlink(pidFilePath);
+      } catch {
+        // ENOENT is fine
+      }
+    }
+
+    // Scan for a free port using a recursive helper (avoids await-in-loop lint rule)
+    async function tryBindPort(p: number): Promise<ServerHandle> {
+      if (p > portMax) {
+        throw new Error(`cesium: no free port found in range ${port}–${portMax}`);
+      }
+      try {
+        return await startServer({ stateDir, port: p, hostname });
+      } catch (err) {
+        const e = err as NodeJS.ErrnoException;
+        if (e.code === "EADDRINUSE" || e.code === "EACCES") {
+          return tryBindPort(p + 1);
+        }
+        throw err;
+      }
+    }
+
+    const handle = await tryBindPort(port);
+    const boundPort = handle.port;
+
+    // Wire API handler before static file fallback
+    handle.addHandler(createApiHandler({ stateDir }));
+
+    const startedAt = new Date().toISOString();
+
+    // Write PID file
+    await writePidFile(pidFilePath, {
+      pid: process.pid,
+      port: boundPort,
+      hostname,
+      startedAt,
+    });
+
+    currentHandle = handle;
+    currentPidFilePath = pidFilePath;
+    lastRequestAt = Date.now();
+
+    const info: RunningInfo = {
+      port: boundPort,
+      url: `http://${hostname}:${boundPort}`,
+      pid: process.pid,
+      startedAt,
+    };
+    currentInfo = info;
+
+    // Attach idle tracking
+    handle.onRequest(() => {
+      lastRequestAt = Date.now();
+    });
+
+    // Install signal handlers
+    installSignalHandlers(pidFilePath);
+
+    // Start idle timer
+    startIdleTimer(idleTimeoutMs);
+
+    return info;
+  } finally {
+    await lock.release();
+  }
+}
+
+// ─── Test reset hook ──────────────────────────────────────────────────────────
+// This function is intended for test use only. It clears module-level singleton
+// state, stops any running server, and removes signal/exit listeners.
+
+export async function resetForTests(): Promise<void> {
+  clearIdleTimer();
+  removeSignalHandlers();
+
+  if (currentHandle !== null) {
+    try {
+      await currentHandle.stop();
+    } catch {
+      // best-effort
+    }
+    currentHandle = null;
+  }
+
+  if (currentPidFilePath !== null) {
+    try {
+      await unlink(currentPidFilePath);
+    } catch {
+      // ENOENT is fine
+    }
+    currentPidFilePath = null;
+  }
+
+  currentInfo = null;
+  lastRequestAt = Date.now();
+}