siltrun 0.1.0

package/src/room-info.test.ts

@@ -0,0 +1,80 @@
+import { test, expect, describe, afterEach } from "bun:test";
+import { startRoomInfoServer, WELL_KNOWN_PATH, type RoomInfoServer } from "./room-info.ts";
+
+let s: RoomInfoServer | null = null;
+afterEach(() => {
+  s?.stop();
+  s = null;
+});
+
+describe("room-info endpoint (SEAM §4)", () => {
+  test("GET /.well-known/silt returns the pinned shape", async () => {
+    s = startRoomInfoServer({
+      port: 0,
+      getInfo: () => ({
+        wtEndpoint: "https://127.0.0.1:4433/room/hello-room",
+        certHash: "abc123",
+        mode: "compute",
+      }),
+    });
+    const res = await fetch(`${s.url}${WELL_KNOWN_PATH}`);
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toContain("application/json");
+    const body = await res.json() as any;
+    // exact key set — the client (owner C) destructures these three
+    expect(Object.keys(body).sort()).toEqual(["certHash", "mode", "wtEndpoint"]);
+    expect(body.wtEndpoint).toBe("https://127.0.0.1:4433/room/hello-room");
+    expect(body.certHash).toBe("abc123");
+    expect(body.mode).toBe("compute");
+  });
+
+  test("certHash may be null (deployed rooms omit the hash)", async () => {
+    s = startRoomInfoServer({
+      port: 0,
+      getInfo: () => ({ wtEndpoint: "https://x/room/y", certHash: null, mode: "compute" }),
+    });
+    const body = await (await fetch(`${s.url}${WELL_KNOWN_PATH}`)).json() as any;
+    expect(body.certHash).toBeNull();
+  });
+
+  test("info is read per-request (cert refresh across restarts is visible)", async () => {
+    let hash = "first";
+    s = startRoomInfoServer({
+      port: 0,
+      getInfo: () => ({ wtEndpoint: "https://x/room/y", certHash: hash, mode: "compute" }),
+    });
+    let body = await (await fetch(`${s.url}${WELL_KNOWN_PATH}`)).json() as any;
+    expect(body.certHash).toBe("first");
+    hash = "second";
+    body = await (await fetch(`${s.url}${WELL_KNOWN_PATH}`)).json() as any;
+    expect(body.certHash).toBe("second");
+  });
+
+  test("permissive CORS so a Vite app on another port can fetch it", async () => {
+    s = startRoomInfoServer({
+      port: 0,
+      getInfo: () => ({ wtEndpoint: "https://x/room/y", certHash: "h", mode: "compute" }),
+    });
+    const res = await fetch(`${s.url}${WELL_KNOWN_PATH}`);
+    expect(res.headers.get("access-control-allow-origin")).toBe("*");
+  });
+
+  test("OPTIONS preflight is answered with CORS", async () => {
+    s = startRoomInfoServer({
+      port: 0,
+      getInfo: () => ({ wtEndpoint: "https://x/room/y", certHash: "h", mode: "compute" }),
+    });
+    const res = await fetch(`${s.url}${WELL_KNOWN_PATH}`, { method: "OPTIONS" });
+    expect(res.status).toBe(204);
+    expect(res.headers.get("access-control-allow-methods")).toContain("GET");
+  });
+
+  test("unknown paths 404", async () => {
+    s = startRoomInfoServer({
+      port: 0,
+      getInfo: () => ({ wtEndpoint: "https://x/room/y", certHash: "h", mode: "compute" }),
+    });
+    const res = await fetch(`${s.url}/nope`);
+    expect(res.status).toBe(404);
+  });
+});

package/src/room-info.ts

@@ -0,0 +1,70 @@
+// The room-info discovery endpoint (SEAM §4, owner E; consumed by @siltrun/client, owner C).
+//
+//   GET <url>/.well-known/silt
+//     -> { wtEndpoint, certHash, mode }
+//
+// `useRoom("http://localhost:4000")` fetches this to discover the WebTransport endpoint
+// and the dev cert hash, then dials WT with the hash pinned — so the dev never touches
+// serverCertificateHashes. Permissive CORS because a Vite app on another port fetches it.
+
+export interface RoomInfo {
+  wtEndpoint: string;
+  certHash: string | null;
+  mode: "compute" | "relay";
+}
+
+const CORS = {
+  "Access-Control-Allow-Origin": "*",
+  "Access-Control-Allow-Methods": "GET, OPTIONS",
+  "Access-Control-Allow-Headers": "*",
+  "Access-Control-Max-Age": "86400",
+};
+
+export const WELL_KNOWN_PATH = "/.well-known/silt";
+
+export interface RoomInfoServer {
+  server: ReturnType<typeof Bun.serve>;
+  port: number;
+  url: string;
+  stop: () => void;
+}
+
+/**
+ * Serve room-info on `port`. `getInfo` is called per request so the served cert hash
+ * tracks the live room-server across restarts (the cert changes each boot).
+ */
+export function startRoomInfoServer(opts: {
+  port: number;
+  hostname?: string;
+  getInfo: () => RoomInfo;
+}): RoomInfoServer {
+  const hostname = opts.hostname ?? "127.0.0.1";
+  const server = Bun.serve({
+    port: opts.port,
+    hostname,
+    fetch(req) {
+      const { pathname } = new URL(req.url);
+
+      if (req.method === "OPTIONS") {
+        return new Response(null, { status: 204, headers: CORS });
+      }
+
+      if (pathname === WELL_KNOWN_PATH) {
+        if (req.method !== "GET") {
+          return new Response("method not allowed", { status: 405, headers: CORS });
+        }
+        return Response.json(opts.getInfo(), { headers: CORS });
+      }
+
+      return new Response("not found", { status: 404, headers: CORS });
+    },
+  });
+
+  const port = server.port ?? opts.port;
+  return {
+    server,
+    port,
+    url: `http://${hostname === "0.0.0.0" ? "localhost" : hostname}:${port}`,
+    stop: () => server.stop(true),
+  };
+}

package/src/server-build.ts

@@ -0,0 +1,78 @@
+// Locates or builds the Go room-server binary and reports where it landed.
+//
+// Installed (npm) path: a prebuilt binary ships in the platform package
+// (@siltrun/room-server-<os>-<arch>) — paths.ts resolves it, no Go toolchain needed.
+// In-repo path: build from source (same approach as demo/run.sh: `go build -o <bin> .`
+// in the room-server dir) so local .go edits are always honored.
+
+import { join } from "node:path";
+import { existsSync, statSync } from "node:fs";
+import { readdir } from "node:fs/promises";
+import { paths, platformKey } from "./paths.ts";
+import { log } from "./log.ts";
+
+export class ServerBuildError extends Error {
+  constructor(
+    message: string,
+    readonly detail = "",
+  ) {
+    super(message);
+    this.name = "ServerBuildError";
+  }
+}
+
+/** Newest mtime among the room-server's .go sources, for a staleness check. */
+async function newestGoMtime(dir: string): Promise<number> {
+  const entries = await readdir(dir);
+  let newest = 0;
+  for (const name of entries) {
+    if (!name.endsWith(".go")) continue;
+    const m = statSync(join(dir, name)).mtimeMs;
+    if (m > newest) newest = m;
+  }
+  return newest;
+}
+
+/**
+ * Ensure a room-server binary exists; return its absolute path.
+ *
+ * Resolution: prebuilt binary (env override or installed platform package, via
+ * paths.ts) → in-repo `go build` (rebuilds when the binary is missing or older than
+ * any .go source). Throws ServerBuildError when neither is available or the build
+ * fails.
+ */
+export async function ensureRoomServer(): Promise<string> {
+  // Prebuilt path (installed from npm, or SILT_ROOM_SERVER_BIN): trust it as-is.
+  if (paths.roomServerBin) {
+    if (!existsSync(paths.roomServerBin)) {
+      throw new ServerBuildError(`room-server binary not found at ${paths.roomServerBin}`);
+    }
+    return paths.roomServerBin;
+  }
+
+  const dir = paths.roomServerDir;
+  if (!existsSync(dir)) {
+    throw new ServerBuildError(
+      `no room-server available: no prebuilt binary for ${platformKey} ` +
+        `(@siltrun/room-server-${platformKey}) and no source checkout at ${dir}`,
+    );
+  }
+
+  const binPath = join(dir, "silt-room-server");
+  const upToDate =
+    existsSync(binPath) && statSync(binPath).mtimeMs >= (await newestGoMtime(dir));
+
+  if (upToDate) return binPath;
+
+  log.info("building room-server (go build)…");
+  const proc = Bun.spawn(["go", "build", "-o", binPath, "."], {
+    cwd: dir,
+    stdout: "pipe",
+    stderr: "pipe",
+  });
+  const [code, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+  if (code !== 0) {
+    throw new ServerBuildError("go build failed", stderr.trim());
+  }
+  return binPath;
+}

package/src/silt-shim.test.ts

@@ -0,0 +1,54 @@
+// Regression test for the `siltrun` shim signal-propagation bug (review finding #5).
+//
+// bin/silt.mjs re-execs the real CLI under Bun and is meant to be transparent: if
+// the child dies from a signal, the shim's own exit should reflect that signal.
+// It re-raised the signal to itself — but its SIGINT/SIGTERM handlers were still
+// installed, so the re-raise hit the JS handler (which only forwards to the
+// already-dead child) and the shim fell through to exit 0, swallowing the signal.
+// The fix removes its own handlers before re-raising so the default disposition
+// terminates it.
+//
+// We drive the REAL shim with a stand-in "bun" that just sleeps (so there's a live
+// child to signal), SIGINT the shim, and assert it exits BY signal / non-zero.
+
+import { expect, test } from "bun:test";
+import { spawn } from "node:child_process";
+import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const SHIM = join(import.meta.dir, "..", "bin", "silt.mjs");
+
+test("SIGINT to the shim exits by signal (not swallowed to 0)", async () => {
+  const dir = mkdtempSync(join(tmpdir(), "silt-shim-"));
+  // A stand-in for the bun binary: ignore the args the shim passes (the cli entry)
+  // and just sleep, so the shim has a live child to forward the signal to.
+  const fakeBun = join(dir, "fake-bun.sh");
+  writeFileSync(fakeBun, "#!/bin/sh\nexec sleep 30\n");
+  chmodSync(fakeBun, 0o755);
+
+  try {
+    const shim = spawn(process.execPath, [SHIM], {
+      env: { ...process.env, SILT_BUN: fakeBun },
+      stdio: "ignore",
+    });
+
+    const exit = new Promise<{ code: number | null; signal: string | null }>((resolve) => {
+      shim.on("exit", (code, signal) => resolve({ code, signal }));
+    });
+
+    // Give the shim time to spawn its child and install its signal handlers.
+    await new Promise((r) => setTimeout(r, 400));
+    shim.kill("SIGINT");
+
+    const { code, signal } = await exit;
+    // Killed-by-signal → signal="SIGINT", code=null. Some platforms surface it as
+    // exit code 130 (128+SIGINT) instead. Either is correct; a swallowed signal
+    // (the bug) is code=0, signal=null.
+    const diedBySignal = signal === "SIGINT" || code === 130;
+    expect(diedBySignal).toBe(true);
+    expect(code === 0 && signal === null).toBe(false);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}, 15_000);

package/src/supervisor.test.ts

@@ -0,0 +1,23 @@
+import { test, expect, describe } from "bun:test";
+import { parseCertHash } from "./supervisor.ts";
+
+describe("parseCertHash", () => {
+  test("extracts the hash from the room-server's boot line", () => {
+    // exact format from packages/room-server/main.go
+    expect(parseCertHash("CERT-SHA256-HEX: a1b2c3d4e5f6")).toBe("a1b2c3d4e5f6");
+  });
+
+  test("lowercases", () => {
+    expect(parseCertHash("CERT-SHA256-HEX: ABCDEF01")).toBe("abcdef01");
+  });
+
+  test("tolerates extra whitespace", () => {
+    expect(parseCertHash("CERT-SHA256-HEX:    deadbeef")).toBe("deadbeef");
+  });
+
+  test("ignores unrelated lines", () => {
+    expect(parseCertHash("silt room server listening on 127.0.0.1:4433")).toBeNull();
+    expect(parseCertHash("session upgraded (handshake OK)")).toBeNull();
+    expect(parseCertHash("")).toBeNull();
+  });
+});

package/src/supervisor.ts

@@ -0,0 +1,218 @@
+// Process supervision for the Go room-server child.
+//
+// Responsibilities:
+//   - spawn the room-server binary and stream its logs (demoted, prefixed) to our output
+//   - scrape the per-boot cert hash it prints ("CERT-SHA256-HEX: <hex>", per main.go)
+//   - restart on crash with exponential backoff, clearly logged
+//   - support an INTENTIONAL restart (hot-reload) that is not counted as a crash
+//   - tear everything down on stop()
+//
+// One request in flight, one child at a time. The cert changes on every boot, so each
+// (re)spawn resolves a fresh cert; callers update room-info from onCert.
+
+import { log } from "./log.ts";
+
+// The room-server prints this line once at boot (packages/room-server/main.go).
+const CERT_LINE = /CERT-SHA256-HEX:\s*([0-9a-fA-F]{4,})/;
+
+/** Pure, testable: extract the cert hash from a log line, or null. */
+export function parseCertHash(line: string): string | null {
+  const m = CERT_LINE.exec(line);
+  return m ? m[1]!.toLowerCase() : null;
+}
+
+interface Deferred<T> {
+  promise: Promise<T>;
+  resolve: (v: T) => void;
+  reject: (e: unknown) => void;
+}
+function deferred<T>(): Deferred<T> {
+  let resolve!: (v: T) => void;
+  let reject!: (e: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+export interface SupervisorOptions {
+  binPath: string;
+  args: string[];
+  cwd?: string;
+  env?: Record<string, string>;
+  /** Called every time a fresh cert hash is observed (initial boot + each restart). */
+  onCert: (hash: string) => void;
+  /** How long to wait for the cert line before declaring a boot failure. */
+  certTimeoutMs?: number;
+  backoff?: { baseMs?: number; maxMs?: number; stableMs?: number };
+}
+
+export class ServerSupervisor {
+  private proc: Bun.Subprocess | null = null;
+  private stopping = false;
+  private restarting = false;
+  private crashCount = 0;
+  private certPending: Deferred<string> | null = null;
+  private recentErr: string[] = [];
+
+  private readonly baseMs: number;
+  private readonly maxMs: number;
+  private readonly stableMs: number;
+
+  constructor(private readonly opts: SupervisorOptions) {
+    this.baseMs = opts.backoff?.baseMs ?? 250;
+    this.maxMs = opts.backoff?.maxMs ?? 5000;
+    this.stableMs = opts.backoff?.stableMs ?? 4000;
+  }
+
+  /** Boot the server and resolve once the cert hash appears. Rejects on early exit. */
+  async start(): Promise<string> {
+    return this.spawnAndAwaitCert();
+  }
+
+  /** Intentional restart (e.g. contract reload). Resolves with the new cert hash. */
+  async restart(): Promise<string> {
+    this.restarting = true;
+    await this.killCurrent();
+    this.restarting = false;
+    return this.spawnAndAwaitCert();
+  }
+
+  async stop(): Promise<void> {
+    this.stopping = true;
+    await this.killCurrent();
+  }
+
+  private async killCurrent(): Promise<void> {
+    const proc = this.proc;
+    if (!proc) return;
+    this.proc = null;
+    try {
+      proc.kill("SIGTERM");
+    } catch {
+      /* already gone */
+    }
+    // Give it a beat to exit cleanly; escalate if it lingers.
+    const exited = proc.exited;
+    const timer = setTimeout(() => {
+      try {
+        proc.kill("SIGKILL");
+      } catch {
+        /* ignore */
+      }
+    }, 2000);
+    await exited;
+    clearTimeout(timer);
+  }
+
+  private spawnAndAwaitCert(): Promise<string> {
+    const pending = deferred<string>();
+    this.certPending = pending;
+    this.recentErr = [];
+
+    const startedAt = Date.now();
+    const proc = Bun.spawn([this.opts.binPath, ...this.opts.args], {
+      cwd: this.opts.cwd,
+      env: { ...process.env, ...this.opts.env },
+      stdout: "pipe",
+      stderr: "pipe",
+    });
+    this.proc = proc;
+
+    void this.pumpLines(proc.stdout, (line) => {
+      const hash = parseCertHash(line);
+      if (hash) {
+        this.opts.onCert(hash);
+        pending.resolve(hash);
+      }
+      log.child("server", line);
+    });
+    void this.pumpLines(proc.stderr, (line) => {
+      this.recentErr.push(line);
+      if (this.recentErr.length > 20) this.recentErr.shift();
+      log.child("server", line);
+    });
+
+    void proc.exited.then((code) => this.handleExit(proc, code, startedAt));
+
+    // Boot-timeout guard so start() never hangs forever on a wedged server.
+    const timeout = this.opts.certTimeoutMs ?? 15000;
+    const timer = setTimeout(() => {
+      pending.reject(
+        new Error(
+          `room-server did not print a cert hash within ${timeout}ms` +
+            this.errTail(),
+        ),
+      );
+    }, timeout);
+    void pending.promise.finally(() => clearTimeout(timer));
+
+    return pending.promise;
+  }
+
+  private handleExit(proc: Bun.Subprocess, code: number | null, startedAt: number) {
+    if (proc !== this.proc && this.proc !== null) return; // superseded by a newer spawn
+    if (this.stopping || this.restarting) return; // expected teardown/restart
+
+    // Unexpected exit = crash.
+    const uptime = Date.now() - startedAt;
+    if (uptime > this.stableMs) this.crashCount = 0; // it had been healthy; reset backoff
+    this.crashCount += 1;
+
+    // If start()/restart() is still waiting on the cert, surface the crash to it.
+    if (this.certPending) {
+      this.certPending.reject(
+        new Error(`room-server exited (code ${code}) before booting${this.errTail()}`),
+      );
+      this.certPending = null;
+    }
+
+    const delay = Math.min(this.maxMs, this.baseMs * 2 ** (this.crashCount - 1));
+    log.error(
+      `room-server exited (code ${code}); restarting in ${delay}ms (attempt ${this.crashCount})`,
+    );
+    setTimeout(() => {
+      if (this.stopping) return;
+      log.warn(`restarting room-server (backoff attempt ${this.crashCount})`);
+      // Non-fatal on early exit: a crash-loop keeps retrying rather than killing dev.
+      void this.spawnAndAwaitCert().catch((e) => {
+        log.error(`respawn failed: ${e instanceof Error ? e.message : String(e)}`);
+      });
+    }, delay);
+
+    void code; // referenced above; keep for clarity
+    void proc;
+  }
+
+  private errTail(): string {
+    return this.recentErr.length ? `\n  last server output:\n    ${this.recentErr.join("\n    ")}` : "";
+  }
+
+  private async pumpLines(
+    stream: ReadableStream<Uint8Array>,
+    onLine: (line: string) => void,
+  ): Promise<void> {
+    const reader = stream.getReader();
+    const decoder = new TextDecoder();
+    let buf = "";
+    try {
+      for (;;) {
+        const { done, value } = await reader.read();
+        if (done) break;
+        buf += decoder.decode(value, { stream: true });
+        let idx: number;
+        while ((idx = buf.indexOf("\n")) >= 0) {
+          const line = buf.slice(0, idx).replace(/\r$/, "");
+          if (line.length) onLine(line);
+          buf = buf.slice(idx + 1);
+        }
+      }
+      if (buf.trim().length) onLine(buf.trim());
+    } catch {
+      /* stream closed on process exit — normal */
+    } finally {
+      reader.releaseLock();
+    }
+  }
+}