diff --git a/knip.json b/knip.json index 2a2465581..db5e8d6b7 100644 --- a/knip.json +++ b/knip.json @@ -16,6 +16,7 @@ ], "entry": [ "src/index.ts", + "src/bin.ts", "src/middleware.ts", "src/state.ts", "src/client/client.tsx", diff --git a/packages/serve-sim/README.md b/packages/serve-sim/README.md index f6c543660..d25d13183 100644 --- a/packages/serve-sim/README.md +++ b/packages/serve-sim/README.md @@ -135,6 +135,8 @@ serve-sim ax --refs [--all] [--text] Compact snapshot with element refs (@e1… serve-sim tap @e2 [--settle] [--timeout ] Tap an element ref; --settle prints the diff serve-sim settle [--timeout ] Wait for the screen to settle; print the diff +serve-sim control [status|start|stop] Persistent control process that keeps short + commands fast (automatic; see below) serve-sim camera [-d udid] [source-options] Inject a synthetic camera feed and (re)launch the app @@ -357,6 +359,52 @@ HTTP, under the same device helper routes and auth as `/recording` (`--auth-toke Limits: sampling at 4 fps can miss a state shown for less than a tick (record for frame-exact history). Frames are the raw framebuffer orientation, like the stream before rotation. When serve-sim is embedded as middleware, `SERVE_SIM_BUFFER` in the dev server's environment starts the buffer when a device's session opens (its first viewer or command), not at startup. +### Control process (faster repeated commands) + +Each `serve-sim` call is a new Node process, and most of a short command used to be Node compiling and running the ~1 MB CLI bundle. The `serve-sim` bin is now an 18 KB entry that hands short commands to a background control process. That process keeps two workers that have already loaded the CLI. Each worker runs one command in its own process, then exits and is replaced, so exit codes, `process.exit`, and signal handlers behave as in a normal run. + +- **Which commands**: `tap`, `gesture`, `settle`, `button`, `type`, `paste`, `rotate`, `fold`, `ca-debug`, `memory-warning`, `event-log`, `ax`, `buffer`, and bare `--help`/`--version`. Everything else runs in-process as before: the preview server, `--detach`, `record`, `camera`, `exec`, `doctor`, `permissions`, `ui`, and anything with `--stdin` (stdin is not forwarded). +- **What carries over**: argv, cwd, the full environment, the umask, stdout/stderr, the exit code or signal, and whether stdout/stderr are TTYs plus their column width. The worker writes stdout/stderr synchronously, so `process.exit` right after a large write loses nothing. That is better than a direct run: when stdout is a pipe on macOS, a direct run can cut that output short (to 64 KiB) because Node writes pipes asynchronously. When stdout and stderr are the same file (`2>&1`, one terminal), the worker sends both down one pipe so their order is kept; output from child processes that inherit stderr is the exception. A slow reader (a pager, a stalled pipe) holds the worker back as it would a direct run, instead of the output piling up in the control process. Ctrl+C, SIGTERM and SIGHUP are forwarded to the worker once the command has started. If the caller dies, its worker is stopped. What does not carry over: resource limits (`ulimit`), the nice level, and any OS sandbox around the caller; those come from whoever started the control process. stdin isn't forwarded either, so `--stdin` and `--file` paths that resolve into `/dev/` (relative or via a symlink) run in-process. +- **Lifecycle**: the first short command starts it in the background and runs in-process itself. It exits after 5 minutes without commands (`SERVE_SIM_CONTROL_IDLE_MS`). It also exits when the dist it came from is rebuilt; that call runs in-process. Callers whose `HOME`, `TMPDIR` or `DEBUG` differ from the daemon's, that use a different node binary or install, or that set `NODE_OPTIONS`, `NODE_EXTRA_CA_CERTS`, `NODE_USE_ENV_PROXY` or node flags, always run in-process. So do callers inside a known agent sandbox (`CODEX_SANDBOX`, `CODEX_SANDBOX_NETWORK_DISABLED`, or Claude Code's `SANDBOX_RUNTIME`), and they never start one (`serve-sim control start` refuses there too), so a daemon is never born inside a sandbox or used to step outside it. Other sandboxes aren't detected; set `SERVE_SIM_CONTROL=0` under them. Those settings are also removed from the daemon's and workers' environment, so one caller's preloads never reach another's command. +- **Fallback**: the daemon first reserves a warm worker and replies "accepted"; the command is only handed to the worker after the caller confirms. If the control process is missing, stale, or doesn't reserve a worker within 1 s (`SERVE_SIM_CONTROL_ACCEPT_MS`), nothing has run yet and the command runs in-process. Once the caller has confirmed, it never falls back: a lost connection fails that call (exit 1) instead of running the command twice. If the reserved worker dies before it is handed the command (for example `pkill node`), or the caller takes more than 10 s to confirm, the daemon frees it and the caller runs the command in-process. +- **Broken installs**: if workers can't load the CLI, the daemon records why in a `.failed` file next to its socket and exits. Commands keep running in-process, and for 10 minutes (or until the dist is rebuilt) they don't start a new daemon. `serve-sim control start` retries immediately, and only reports success once a worker has loaded; otherwise it prints the worker's error and exits 1. +- **Off switch**: `SERVE_SIM_CONTROL=0` never uses or starts it. Under `CI` it is only used if already running; `SERVE_SIM_CONTROL=1` auto-starts it there too. + +```sh +serve-sim control status [--json] # exit 1 when not running; shows a recent worker load failure +serve-sim control start # idempotent; waits until it answers +serve-sim control stop # idempotent; also clears stale socket/pid files + # (says "stopping" while running commands finish) + # (a daemon that doesn't acknowledge within 2 s gets + # SIGTERM, only if its pid file names that daemon) +``` + +It listens on a Unix socket at `$TMPDIR/serve-sim-control-/control-.sock` (or under `SERVE_SIM_CONTROL_DIR`), with a pid file next to it. `` is derived from the bin path, the node binary, and `HOME`. Callers send their whole environment over that socket, so both sides check ownership first: the directory must be a real directory (not a symlink) owned by you with no group/other access, and the socket must be a socket owned by you. Otherwise commands run in-process and the daemon refuses to start. The socket is created owner-only (mode 0600) with no window where it is more open. A daemon that finds a dead socket replaces it. When several start at once, the extra ones see their socket was taken over and exit. + +Measured on an Apple Silicon Mac with Node 24.13: each case was spawned with `spawnSync` from a node script, after 3 warm-up runs. Back-to-back means calls ran one after another. "Before" runs the full CLI bundle directly, which is what the bin was before this change. `tap` ran against a live preview on its own simulator. + +| case | p50 ms | p95 ms | +|---|---|---| +| `node -e 0` (floor) | 23.1 | 27.1 | +| `--help`, before | 66.2 | 82.7 | +| `--help`, warm control process | 31.9 | 32.8 | +| `--help`, first call with no daemon (starts it) | 76.0 | 81.7 | +| `--help`, the call right after that | 51.1 | 54.2 | +| `tap`, before | 113.3 | 119.4 | +| `tap`, warm control process | 84.8 | 86.6 | +| `tap`, first call with no daemon (starts it) | 114.0 | 121.2 | +| `tap`, the call right after that | 86.6 | 89.6 | + +With calls spaced 400 ms apart, a more agent-like pace, everything is slower, including bare Node (p50 38 ms). The saving stays about the same: `--help` drops from 72.5 to 44.5 ms and `tap` from 132.1 to 105.9 ms. + +Where the warm time goes: + +- About 23 ms is Node's own startup, which can't be avoided. +- About 9 ms is the bin, the socket round trip, the worker running the command, and the worker's exit. +- For `tap`, about 40 ms more is spent waiting on the preview server for the touch-config fetch, the WebSocket connect, and the HID ack. + +The first call with no daemon running costs about 10 ms extra. That is the daemon spawn, plus its workers competing with the command for CPU. + ### Accessibility refs for agents `serve-sim ax --refs` prints a compact snapshot of the visible screen: each interesting element gets a short ref (`@e1`, `@e2`, …, in tree order), its role, label, value (when set), `enabled: false` (only when disabled), and its frame and center in device points. `--all` includes offscreen elements; `--text` prints one line per element. diff --git a/packages/serve-sim/build.ts b/packages/serve-sim/build.ts index 7d84e5536..a918d1ec9 100644 --- a/packages/serve-sim/build.ts +++ b/packages/serve-sim/build.ts @@ -3,7 +3,9 @@ * Unified serve-sim build. * * Produces, all minified and with no runtime deps on workspace packages: - * dist/serve-sim.js ESM bin (node target) referenced by package.json#bin + * dist/serve-sim.js Tiny ESM bin (node target) referenced by package.json#bin; + * dispatches to the control process or loads: + * dist/serve-sim-cli.js The full CLI bundle (node target) * dist/serve-sim Compiled single-file executable (bun --compile) * dist/middleware.js Public subpath export "serve-sim/middleware" (ESM) * dist/middleware.cjs Thin CJS wrapper for the same @@ -150,27 +152,51 @@ writeFileSync( ); console.log("dist/middleware.cjs (wrapper)"); -// ─── 4. Bin JS bundle ──────────────────────────────────────────────────── +// ─── 4. Bin JS bundles ─────────────────────────────────────────────────── +// dist/serve-sim-cli.js is the whole CLI. dist/serve-sim.js is the bin: only +// node builtins, so a short command handed to the persistent control process +// skips compiling the ~1 MB CLI bundle (see src/bin.ts). -const binJsResult = await Bun.build({ +const NODE_EXTERNALS = ["fs", "path", "os", "child_process", "url", "net", "tls", "crypto", "stream", "events", "http", "https", "zlib", "buffer", "module", "ws"]; + +const cliJsResult = await Bun.build({ entrypoints: [resolve(root, "src/index.ts")], target: "node", format: "esm", minify: true, outdir: distDir, - naming: "serve-sim.js", - external: ["fs", "path", "os", "child_process", "url", "net", "tls", "crypto", "stream", "events", "http", "https", "zlib", "buffer", "module", "ws"], + naming: "serve-sim-cli.js", + external: NODE_EXTERNALS, define: PREVIEW_DEFINE, sourcemap: "linked", }); +if (!cliJsResult.success) { + console.error("CLI JS build failed:"); + for (const log of cliJsResult.logs) console.error(log); + process.exit(1); +} +console.log(`dist/serve-sim-cli.js ${kb((await cliJsResult.outputs[0]!.text()).length)}`); + +const binJsResult = await Bun.build({ + entrypoints: [resolve(root, "src/bin.ts")], + target: "node", + format: "esm", + minify: true, + outdir: distDir, + naming: "serve-sim.js", + external: NODE_EXTERNALS, +}); if (!binJsResult.success) { console.error("Bin JS build failed:"); for (const log of binJsResult.logs) console.error(log); process.exit(1); } - -const binJsSize = (await binJsResult.outputs[0]!.text()).length; -console.log(`dist/serve-sim.js ${kb(binJsSize)}`); +const binJs = await binJsResult.outputs[0]!.text(); +if (/\bws\b["']|from"ws"|commander/.test(binJs)) { + console.error("dist/serve-sim.js must only import node builtins"); + process.exit(1); +} +console.log(`dist/serve-sim.js ${kb(binJs.length)}`); // ─── 5. Compiled single-file executable ────────────────────────────────── // Bun.build doesn't expose --compile yet, so shell out. The define arg carries diff --git a/packages/serve-sim/package.json b/packages/serve-sim/package.json index 13eb618f2..e3e727168 100644 --- a/packages/serve-sim/package.json +++ b/packages/serve-sim/package.json @@ -25,6 +25,7 @@ }, "files": [ "dist/serve-sim.js", + "dist/serve-sim-cli.js", "dist/middleware.js", "dist/middleware.cjs", "dist/simcam/libSimCameraInjector.dylib", diff --git a/packages/serve-sim/src/__tests__/bundle-portability.test.ts b/packages/serve-sim/src/__tests__/bundle-portability.test.ts index 34a3ee1d9..204eb8523 100644 --- a/packages/serve-sim/src/__tests__/bundle-portability.test.ts +++ b/packages/serve-sim/src/__tests__/bundle-portability.test.ts @@ -15,7 +15,7 @@ import { join } from "path"; const PKG_DIR = join(import.meta.dir, "../.."); const SRC_DIR = join(PKG_DIR, "src"); -const BUNDLES = ["dist/serve-sim.js", "dist/middleware.js"] as const; +const BUNDLES = ["dist/serve-sim.js", "dist/serve-sim-cli.js", "dist/middleware.js"] as const; // CI builds dist before running this directory; locally, run // `bun run build.ts` first or the suite skips. diff --git a/packages/serve-sim/src/__tests__/control-process.test.ts b/packages/serve-sim/src/__tests__/control-process.test.ts new file mode 100644 index 000000000..dd5f00787 --- /dev/null +++ b/packages/serve-sim/src/__tests__/control-process.test.ts @@ -0,0 +1,1109 @@ +import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test"; +import { spawn, spawnSync, type ChildProcess } from "child_process"; +import { + chmodSync, + existsSync, + mkdirSync, + mkdtempSync, + readFileSync, + readdirSync, + realpathSync, + rmSync, + statSync, + symlinkSync, + utimesSync, + writeFileSync, +} from "fs"; +import { join } from "path"; +import { + CONTROL_DIR_ENV, + FRAME_JSON, + FRAME_STDOUT, + FrameDecoder, + controlFingerprint, + controlMode, + controlPaths, + encodeFrame, + encodeJson, + fingerprintMismatch, + isDispatchable, + isStaleBuild, + nodeRuntimeOverride, + parseAcceptMs, + parseIdleMs, + parseJsonFrame, + sandboxMarker, + unsafeControlDir, + unsafeControlSocket, + withoutNodeRuntimeEnv, + type ControlMessage, +} from "../control-protocol"; +import { adoptCaller } from "../control-worker"; + +// ─── Pure pieces ───────────────────────────────────────────────────────── + +describe("isDispatchable", () => { + test("short commands and root info flags dispatch", () => { + expect(isDispatchable(["tap", "0.5", "0.5"])).toBe(true); + expect(isDispatchable(["button", "home", "-d", "X"])).toBe(true); + expect(isDispatchable(["buffer", "status"])).toBe(true); + expect(isDispatchable(["--help"])).toBe(true); + expect(isDispatchable(["-v"])).toBe(true); + expect(isDispatchable(["help", "tap"])).toBe(true); + }); + + test("servers, long-running, stdin and unknown commands stay in-process", () => { + expect(isDispatchable([])).toBe(false); + expect(isDispatchable(["--port", "3412"])).toBe(false); + expect(isDispatchable(["--detach"])).toBe(false); + expect(isDispatchable(["record"])).toBe(false); + expect(isDispatchable(["camera", "status"])).toBe(false); + expect(isDispatchable(["exec", "ls"])).toBe(false); + expect(isDispatchable(["control", "status"])).toBe(false); + expect(isDispatchable(["type", "--stdin"])).toBe(false); + expect(isDispatchable(["paste", "--stdin", "-d", "X"])).toBe(false); + expect(isDispatchable(["iPhone 16"])).toBe(false); + expect(isDispatchable(["--help", "tap"])).toBe(false); + }); + + test("--file pointing at a /dev alias of stdin stays in-process", () => { + expect(isDispatchable(["type", "--file", "/dev/stdin"])).toBe(false); + expect(isDispatchable(["type", "--file=/dev/fd/0"])).toBe(false); + expect(isDispatchable(["paste", "-d", "X", "--file", "/dev/fd/3"])).toBe(false); + expect(isDispatchable(["type", "--file", "/tmp/notes.txt"])).toBe(true); + }); + + test("--file resolves against the caller's cwd and through symlinks before the /dev check", () => { + const dir = realpathSync(mkdtempSync("/tmp/ssctl-devfile-")); + try { + const up = "../".repeat(dir.split("/").length); + expect(isDispatchable(["type", "--file", `${up}dev/stdin`], dir)).toBe(false); + expect(isDispatchable(["type", `--file=./../${up}dev/fd/0`], dir)).toBe(false); + symlinkSync("/dev/stdin", join(dir, "in")); + expect(isDispatchable(["type", "--file", "in"], dir)).toBe(false); + symlinkSync("in", join(dir, "in2")); + expect(isDispatchable(["type", "--file", "in2"], dir)).toBe(false); + symlinkSync("/dev", join(dir, "devdir")); + expect(isDispatchable(["type", "--file", "devdir/fd/0"], dir)).toBe(false); + expect(isDispatchable(["type", "--file", join(dir, "in")])).toBe(false); + writeFileSync(join(dir, "notes.txt"), "hi"); + expect(isDispatchable(["type", "--file", "notes.txt"], dir)).toBe(true); + expect(isDispatchable(["type", "--file", "missing.txt"], dir)).toBe(true); + } finally { + rmSync(dir, { recursive: true, force: true }); + } + }); + + test("sandboxed callers are recognised by their env markers", () => { + expect(sandboxMarker({})).toBeNull(); + expect(sandboxMarker({ CODEX_SANDBOX: "seatbelt" })).toBe("CODEX_SANDBOX"); + expect(sandboxMarker({ CODEX_SANDBOX_NETWORK_DISABLED: "1" })).toBe("CODEX_SANDBOX_NETWORK_DISABLED"); + expect(sandboxMarker({ SANDBOX_RUNTIME: "1" })).toBe("SANDBOX_RUNTIME"); + expect(sandboxMarker({ SANDBOX_RUNTIME: "" })).toBeNull(); + }); +}); + +describe("controlMode", () => { + test("defaults to auto, off/on overrides, CI only reuses", () => { + expect(controlMode({})).toBe("auto"); + expect(controlMode({ SERVE_SIM_CONTROL: "0" })).toBe("off"); + expect(controlMode({ SERVE_SIM_CONTROL: "off" })).toBe("off"); + expect(controlMode({ CI: "true" })).toBe("use"); + expect(controlMode({ CI: "false" })).toBe("auto"); + expect(controlMode({ CI: "1", SERVE_SIM_CONTROL: "1" })).toBe("auto"); + }); + + test("parseIdleMs falls back on junk", () => { + expect(parseIdleMs(undefined)).toBe(300_000); + expect(parseIdleMs("2000")).toBe(2000); + expect(parseIdleMs("nope")).toBe(300_000); + expect(parseIdleMs("5")).toBe(300_000); + expect(parseAcceptMs(undefined)).toBe(1000); + expect(parseAcceptMs("30000")).toBe(30000); + expect(parseAcceptMs("-1")).toBe(1000); + }); + + test("node runtime settings are stripped from workers and force in-process", () => { + expect(withoutNodeRuntimeEnv({ NODE_OPTIONS: "--require x", NODE_EXTRA_CA_CERTS: "/ca", KEEP: "1" })).toEqual({ + KEEP: "1", + }); + expect(nodeRuntimeOverride({}, [])).toBeNull(); + expect(nodeRuntimeOverride({ NODE_OPTIONS: "" }, [])).toBeNull(); + expect(nodeRuntimeOverride({ NODE_USE_ENV_PROXY: "1" }, [])).toBe("NODE_USE_ENV_PROXY"); + expect(nodeRuntimeOverride({}, ["--inspect"])).toBe("execArgv"); + }); +}); + +describe("control dir and socket ownership", () => { + test("default dir is per uid", () => { + const p = controlPaths({ binFile: "/a", execPath: "/n", env: { HOME: "/h" } }); + expect(p.dir.endsWith(`serve-sim-control-${process.getuid!()}`)).toBe(true); + }); + + test("rejects missing, group/other-writable, symlinked and foreign-owned dirs", () => { + const base = realpathSync(mkdtempSync("/tmp/ssctl-own-")); + try { + const ok = join(base, "ok"); + mkdirSync(ok, { mode: 0o700 }); + expect(unsafeControlDir(ok)).toBeNull(); + expect(unsafeControlDir(join(base, "nope"))).toBe("missing"); + const open = join(base, "open"); + mkdirSync(open); + chmodSync(open, 0o777); + expect(unsafeControlDir(open)).toMatch(/group\/other/); + chmodSync(open, 0o750); + expect(unsafeControlDir(open)).toMatch(/group\/other/); + const link = join(base, "link"); + symlinkSync(ok, link); + expect(unsafeControlDir(link)).toBe("symlink"); + const file = join(base, "file"); + writeFileSync(file, ""); + expect(unsafeControlDir(file)).toBe("not a directory"); + // Root-owned: stands in for a directory another user pre-created. + if (process.getuid!() !== 0) expect(unsafeControlDir("/")).toBe("owned by uid 0"); + expect(unsafeControlSocket(join(ok, "x.sock"))).toBe("missing"); + expect(unsafeControlSocket(file)).toBe("not a socket"); + const sockLink = join(base, "s.sock"); + symlinkSync(file, sockLink); + expect(unsafeControlSocket(sockLink)).toBe("symlink"); + // A root-owned socket, where the OS has one. + const rootSock = "/var/run/mDNSResponder"; + if (process.getuid!() !== 0 && existsSync(rootSock) && statSync(rootSock).isSocket()) { + expect(unsafeControlSocket(rootSock)).toBe("owned by uid 0"); + } + } finally { + rmSync(base, { recursive: true, force: true }); + } + }); +}); + +describe("framing", () => { + test("decodes frames split across arbitrary chunks", () => { + const wire = Buffer.concat([ + encodeJson({ t: "accepted" }), + encodeFrame(FRAME_STDOUT, "hello\n"), + encodeJson({ t: "exit", code: 3, signal: null }), + ]); + const decoder = new FrameDecoder(); + const frames = []; + for (let i = 0; i < wire.length; i += 3) frames.push(...decoder.push(wire.subarray(i, i + 3))); + expect(frames.map((f) => f.type)).toEqual([FRAME_JSON, FRAME_STDOUT, FRAME_JSON]); + expect(frames[1]!.payload.toString()).toBe("hello\n"); + expect(parseJsonFrame(frames[2]!)).toEqual({ t: "exit", code: 3, signal: null }); + }); + + test("rejects oversized frames and ignores non-JSON", () => { + const header = Buffer.alloc(5); + header.writeUInt8(FRAME_JSON, 0); + header.writeUInt32BE(0xffffffff, 1); + expect(() => new FrameDecoder().push(header)).toThrow(/too large/); + expect(parseJsonFrame({ type: FRAME_JSON, payload: Buffer.from("{nope") })).toBeNull(); + }); +}); + +describe("fingerprint", () => { + const base = { + protocol: 1, + execPath: "/n", + home: "/h", + tmpdir: "/t", + debug: "", + binMtimeMs: 1, + mainMtimeMs: 2, + }; + test("reports the first differing field; rebuilds are stale", () => { + expect(fingerprintMismatch(base, { ...base })).toBeNull(); + expect(fingerprintMismatch(base, { ...base, debug: "serve-sim*" })).toBe("debug"); + expect(isStaleBuild(fingerprintMismatch(base, { ...base, mainMtimeMs: 3 }))).toBe(true); + expect(isStaleBuild("home")).toBe(false); + }); + + test("socket paths are per install and node binary", () => { + const env = { HOME: "/h", [CONTROL_DIR_ENV]: "/tmp/x" }; + const a = controlPaths({ binFile: "/a/serve-sim.js", execPath: "/n", env }); + const b = controlPaths({ binFile: "/b/serve-sim.js", execPath: "/n", env }); + const c = controlPaths({ binFile: "/a/serve-sim.js", execPath: "/n2", env }); + expect(a.socket.startsWith("/tmp/x/control-")).toBe(true); + expect(new Set([a.socket, b.socket, c.socket]).size).toBe(3); + expect(controlFingerprint({ binFile: "/missing", mainFile: "/missing", execPath: "/n", env }).mainMtimeMs).toBe(-1); + }); +}); + +describe("adoptCaller", () => { + test("takes over argv, env, cwd and TTY shape", () => { + const dir = mkdtempSync("/tmp/ssctl-adopt-"); + const chdirs: string[] = []; + const stdout = {} as NodeJS.WriteStream; + const proc = { + argv: ["/node", "/bin.js"], + env: { KEEP: "old", DROP: "x" } as NodeJS.ProcessEnv, + chdir: (d: string) => chdirs.push(d), + stdout, + stderr: {} as NodeJS.WriteStream, + } as unknown as NodeJS.Process; + adoptCaller( + { + t: "run", + fingerprint: {} as never, + argv: ["tap", "1", "2"], + cwd: dir, + env: { KEEP: "new", ADD: "y" }, + tty: { stdout: { isTTY: true, columns: 120 }, stderr: { isTTY: false } }, + }, + proc, + ); + expect(proc.argv).toEqual(["/node", "/bin.js", "tap", "1", "2"]); + expect(proc.env).toEqual({ KEEP: "new", ADD: "y" }); + expect(chdirs).toEqual([dir]); + expect(stdout.isTTY).toBe(true); + expect(stdout.columns).toBe(120); + expect(proc.stderr.isTTY).toBeUndefined(); + rmSync(dir, { recursive: true, force: true }); + }); + + test("adopts the caller's umask when sent", () => { + const umasks: number[] = []; + const proc = { + argv: [], + env: {}, + chdir: () => {}, + umask: (m: number) => umasks.push(m), + stdout: {} as NodeJS.WriteStream, + stderr: {} as NodeJS.WriteStream, + } as unknown as NodeJS.Process; + const msg = { + t: "run" as const, + fingerprint: {} as never, + argv: [], + cwd: "/", + env: {}, + tty: { stdout: { isTTY: false }, stderr: { isTTY: false } }, + }; + adoptCaller(msg, proc); + expect(umasks).toEqual([]); + adoptCaller({ ...msg, umask: 0o027 }, proc); + expect(umasks).toEqual([0o027]); + }); + + test("keeps a 0-column TTY width and merges stderr into stdout for 2>&1", () => { + const writes: string[] = []; + const stdout = { write: (c: string) => writes.push(`out:${c}`) } as unknown as NodeJS.WriteStream; + const stderr = { write: (c: string) => writes.push(`err:${c}`) } as unknown as NodeJS.WriteStream; + const proc = { argv: [], env: {}, chdir: () => {}, stdout, stderr } as unknown as NodeJS.Process; + adoptCaller( + { + t: "run", + fingerprint: {} as never, + argv: [], + cwd: "/", + env: {}, + tty: { stdout: { isTTY: true, columns: 0 }, stderr: { isTTY: true, columns: 0 } }, + sharedOutput: true, + }, + proc, + ); + expect(stdout.columns).toBe(0); + proc.stderr.write("a"); + proc.stdout.write("b"); + expect(writes).toEqual(["out:a", "out:b"]); + }); +}); + +// ─── Real processes ────────────────────────────────────────────────────── +// Build the real bin next to a fake CLI bundle and drive it with node, the +// runtime the published bin targets. + +const NODE = spawnSync("node", ["-e", "process.stdout.write(process.execPath)"], { encoding: "utf8" }); +const nodePath = NODE.status === 0 ? NODE.stdout : null; +const describeWithNode = nodePath ? describe : describe.skip; + +describeWithNode("control process", () => { + let root: string; + let dist: string; + let binFile: string; + let mainFile: string; + let driverFile: string; + let ctlDir: string; + let work: string; + const stray: ChildProcess[] = []; + + beforeAll(async () => { + // realpath: macOS /tmp is a symlink, and the bin keys its socket on its own real path. + root = realpathSync(mkdtempSync("/tmp/ssctl-")); + dist = join(root, "dist"); + for (const [entry, naming] of [ + [join(import.meta.dir, "../bin.ts"), "serve-sim.js"], + [join(import.meta.dir, "fixtures/control-fake-cli.ts"), "serve-sim-cli.js"], + [join(import.meta.dir, "fixtures/control-race-driver.ts"), "race-driver.js"], + ] as const) { + const result = await Bun.build({ entrypoints: [entry], target: "node", format: "esm", outdir: dist, naming }); + if (!result.success) throw new Error(result.logs.map(String).join("\n")); + } + binFile = join(dist, "serve-sim.js"); + mainFile = join(dist, "serve-sim-cli.js"); + driverFile = join(dist, "race-driver.js"); + }); + + beforeEach(() => { + ctlDir = mkdtempSync(join(root, "c")); + work = mkdtempSync(join(root, "w")); + }); + + afterEach(async () => { + await cli(["control", "stop"]); + for (const c of stray.splice(0)) c.kill("SIGKILL"); + }); + + afterAll(() => { + rmSync(root, { recursive: true, force: true }); + }); + + function env(extra: Record = {}): NodeJS.ProcessEnv { + const e: NodeJS.ProcessEnv = { + ...process.env, + [CONTROL_DIR_ENV]: ctlDir, + SERVE_SIM_CONTROL_IDLE_MS: "60000", + // Slow CI must not turn dispatches into in-process runs. + SERVE_SIM_CONTROL_ACCEPT_MS: "30000", + }; + delete e.CI; + for (const k of [ + "NODE_OPTIONS", + "NODE_EXTRA_CA_CERTS", + "NODE_USE_ENV_PROXY", + "MARKER", + "FAKE_WORKER_LOAD_FAIL", + "CODEX_SANDBOX", + "CODEX_SANDBOX_NETWORK_DISABLED", + "SANDBOX_RUNTIME", + ]) + delete e[k]; + delete e.SERVE_SIM_CONTROL; + delete e.EXIT_CODE; + for (const [k, v] of Object.entries(extra)) { + if (v === undefined) delete e[k]; + else e[k] = v; + } + return e; + } + + type Run = { code: number | null; signal: string | null; stdout: string; stderr: string }; + + function run(cmd: string, argv: string[], opts: { env?: Record; cwd?: string } = {}): Promise { + return new Promise((resolve) => { + const child = spawn(cmd, argv, { cwd: opts.cwd ?? work, env: env(opts.env) }); + let stdout = ""; + let stderr = ""; + child.stdout.on("data", (d) => (stdout += d)); + child.stderr.on("data", (d) => (stderr += d)); + child.on("close", (code, signal) => resolve({ code, signal, stdout, stderr })); + }); + } + + function cli( + args: string[], + opts: { env?: Record; cwd?: string; nodeArgs?: string[] } = {}, + ): Promise { + return run(nodePath!, [...(opts.nodeArgs ?? []), binFile, ...args], opts); + } + + const paths = () => controlPaths({ binFile, execPath: nodePath!, env: env() }); + const daemonPids = () => + spawnSync("pgrep", ["-f", `${binFile} __control-daemon`], { encoding: "utf8" }) + .stdout.split("\n") + .filter(Boolean); + + async function status(): Promise<{ running: boolean; pid?: number; served?: number; warm?: number; busy?: number; buffered?: number }> { + const r = await cli(["control", "status", "--json"]); + return JSON.parse(r.stdout); + } + + async function until(probe: () => Promise, ms = 5000): Promise { + const deadline = Date.now() + ms; + for (;;) { + const v = await probe(); + if (v) return v; + if (Date.now() > deadline) throw new Error("timed out waiting"); + await Bun.sleep(25); + } + } + + const warm = () => until(async () => ((await status()).warm ?? 0) >= 1); + + async function startDaemon() { + const r = await cli(["control", "start", "--json"]); + expect(r.code).toBe(0); + await warm(); + return JSON.parse(r.stdout) as { pid: number; alreadyRunning: boolean }; + } + + test("start is idempotent and status/stop report it", async () => { + expect((await cli(["control", "status"])).code).toBe(1); + const first = await startDaemon(); + expect(first.alreadyRunning).toBe(false); + const again = JSON.parse((await cli(["control", "start", "--json"])).stdout); + expect(again).toMatchObject({ alreadyRunning: true, pid: first.pid }); + const stop = JSON.parse((await cli(["control", "stop", "--json"])).stdout); + expect(stop).toMatchObject({ wasRunning: true, pid: first.pid }); + expect((await status()).running).toBe(false); + expect(JSON.parse((await cli(["control", "stop", "--json"])).stdout)).toMatchObject({ wasRunning: false }); + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + expect(existsSync(paths.socket)).toBe(false); + expect(existsSync(paths.pidFile)).toBe(false); + }); + + test("dispatches a command with the caller's argv, cwd, env, output and exit code", async () => { + const daemon = await startDaemon(); + const sub = join(work, "sub dir"); + mkdirSync(sub); + const r = await cli(["tap", "0.25", "0.75"], { cwd: sub, env: { FOO: "bar", EXIT_CODE: "3" } }); + expect(r.code).toBe(3); + expect(r.stderr).toBe("to stderr\n"); + const seen = JSON.parse(r.stdout); + expect(seen).toMatchObject({ + argv: ["tap", "0.25", "0.75"], + argv1: binFile, + cwd: sub, + foo: "bar", + role: null, + stdoutIsTTY: false, + }); + // It ran in one of the daemon's workers, not in the client. + expect(seen.ppid).toBe(daemon.pid); + expect((await status()).served).toBe(1); + }); + + test("process.exit codes, thrown errors and help/version come back intact", async () => { + await startDaemon(); + expect(await cli(["button", "9"])).toMatchObject({ code: 9, stdout: "exiting hard\n" }); + const thrown = await cli(["ax"]); + expect(thrown.code).toBe(1); + expect(thrown.stderr).toContain("boom from ax"); + expect(await cli(["--version"])).toMatchObject({ code: 0, stdout: "fake 1.0.0\n", stderr: "" }); + expect((await status()).served).toBe(3); + }); + + test("reuses the daemon with a fresh worker per call", async () => { + const daemon = await startDaemon(); + const a = JSON.parse((await cli(["tap", "1", "1"])).stdout); + const b = JSON.parse((await cli(["tap", "2", "2"])).stdout); + expect(a.ppid).toBe(daemon.pid); + expect(b.ppid).toBe(daemon.pid); + expect(a.pid).not.toBe(b.pid); + expect((await status()).pid).toBe(daemon.pid); + }); + + test("auto-starts on first use; that call runs in-process", async () => { + const first = await cli(["tap", "1", "1"]); + expect(first.code).toBe(0); + const firstSeen = JSON.parse(first.stdout); + const s = await until(async () => { + const v = await status(); + return v.running && (v.warm ?? 0) >= 1 ? v : null; + }); + expect(firstSeen.ppid).not.toBe(s.pid); + const second = JSON.parse((await cli(["tap", "1", "1"])).stdout); + expect(second.ppid).toBe(s.pid); + }); + + test("never starts with SERVE_SIM_CONTROL=0 or under CI, and stays in-process for other commands", async () => { + expect((await cli(["tap", "1", "1"], { env: { SERVE_SIM_CONTROL: "0" } })).code).toBe(0); + expect((await cli(["tap", "1", "1"], { env: { CI: "true" } })).code).toBe(0); + expect(await cli(["record"])).toMatchObject({ code: 0, stdout: "direct-only:record\n" }); + await Bun.sleep(300); + expect((await status()).running).toBe(false); + + // CI reuses one that is already running. + const daemon = await startDaemon(); + expect(JSON.parse((await cli(["tap", "1", "1"], { env: { CI: "true" } })).stdout).ppid).toBe(daemon.pid); + expect(JSON.parse((await cli(["tap", "1", "1"], { env: { SERVE_SIM_CONTROL: "0" } })).stdout).ppid).not.toBe(daemon.pid); + }); + + test("recovers from a stale socket and pid file left by a killed daemon", async () => { + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + // A listener that dies without cleanup leaves the socket file behind. + const dead = spawn(nodePath!, [ + "-e", + `require("net").createServer().listen(${JSON.stringify(paths.socket)}, () => process.kill(process.pid, "SIGKILL"))`, + ]); + await new Promise((r) => dead.on("close", r)); + expect(existsSync(paths.socket)).toBe(true); + writeFileSync(paths.pidFile, JSON.stringify({ pid: dead.pid })); + + // The caller still gets its answer (in-process) and a new daemon takes over. + const r = await cli(["tap", "1", "1"]); + expect(r.code).toBe(0); + const s = await until(async () => { + const v = await status(); + return v.running && (v.warm ?? 0) >= 1 ? v : null; + }); + expect(JSON.parse((await cli(["tap", "1", "1"])).stdout).ppid).toBe(s.pid); + }); + + test("stop clears stale files when nothing is listening", async () => { + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + mkdirSync(paths.dir, { recursive: true }); + writeFileSync(paths.socket, ""); + writeFileSync(paths.pidFile, JSON.stringify({ pid: 999_999 })); + expect(JSON.parse((await cli(["control", "stop", "--json"])).stdout)).toMatchObject({ + wasRunning: false, + clearedStale: true, + }); + expect(existsSync(paths.socket)).toBe(false); + expect(existsSync(paths.pidFile)).toBe(false); + }); + + test("exits on its own after the idle period and cleans up", async () => { + const r = await cli(["control", "start", "--json"], { env: { SERVE_SIM_CONTROL_IDLE_MS: "400" } }); + const { pid } = JSON.parse(r.stdout); + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + await until(async () => { + try { + process.kill(pid, 0); + return false; + } catch { + return true; + } + }, 5000); + expect(existsSync(paths.socket)).toBe(false); + expect(existsSync(paths.pidFile)).toBe(false); + // No orphaned workers: none of them is still a child of the dead daemon. + const ps = spawnSync("ps", ["-A", "-o", "ppid="], { encoding: "utf8" }).stdout; + expect(ps.split("\n").map((l) => Number(l.trim()))).not.toContain(pid); + }); + + test("a rebuilt dist makes the daemon step aside", async () => { + const daemon = await startDaemon(); + const later = new Date(Date.now() + 5000); + utimesSync(mainFile, later, later); + const r = JSON.parse((await cli(["tap", "1", "1"])).stdout); + expect(r.ppid).not.toBe(daemon.pid); + await until(async () => { + try { + process.kill(daemon.pid, 0); + return false; + } catch { + return true; + } + }); + }); + + test("callers with a different HOME/DEBUG run in-process", async () => { + const daemon = await startDaemon(); + const r = JSON.parse((await cli(["tap", "1", "1"], { env: { DEBUG: "serve-sim*" } })).stdout); + expect(r.ppid).not.toBe(daemon.pid); + expect((await status()).pid).toBe(daemon.pid); + }); + + test("forwards Ctrl+C to the worker", async () => { + await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + stray.push(child); + let stdout = ""; + await new Promise((resolve) => + child.stdout.on("data", (d) => { + stdout += d; + if (stdout.includes("waiting")) resolve(); + }), + ); + child.kill("SIGINT"); + const code = await new Promise((r) => child.on("close", (c) => r(c))); + expect(code).toBe(130); + expect(stdout).toBe("waiting\ngot SIGINT\n"); + }); + + test("a caller that dies mid-command takes its worker with it", async () => { + await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + await new Promise((resolve) => child.stdout.on("data", () => resolve())); + expect((await status()).busy).toBe(1); + child.kill("SIGKILL"); + // The fake settle would otherwise run for 10s. + await until(async () => (await status()).busy === 0, 3000); + }); + + test("concurrent starters share one daemon and concurrent calls all complete", async () => { + const starts = await Promise.all(Array.from({ length: 4 }, () => cli(["control", "start", "--json"]))); + const pids = new Set(starts.map((s) => JSON.parse(s.stdout).pid)); + expect(pids.size).toBe(1); + const [pid] = [...pids]; + + const results = await Promise.all( + Array.from({ length: 8 }, (_, i) => cli(["tap", String(i), "0"], { env: { EXIT_CODE: String(i % 3) } })), + ); + results.forEach((r, i) => { + expect(r.code).toBe(i % 3); + const seen = JSON.parse(r.stdout); + expect(seen.argv).toEqual(["tap", String(i), "0"]); + expect(seen.ppid).toBe(pid); + }); + expect(new Set(results.map((r) => JSON.parse(r.stdout).pid)).size).toBe(8); + expect((await status()).served).toBe(8); + }); + + test("concurrent auto-starts converge on one daemon", async () => { + const results = await Promise.all(Array.from({ length: 6 }, () => cli(["tap", "1", "1"]))); + for (const r of results) expect(r.code).toBe(0); + const s = await until(async () => { + const v = await status(); + return v.running ? v : null; + }); + // Losers notice the takeover on their next ownership check. + await until(async () => daemonPids().length === 1); + expect(daemonPids()).toEqual([String(s.pid)]); + }); + + test("rejects malformed and unknown first messages without wedging", async () => { + await startDaemon(); + const paths = controlPaths({ binFile, execPath: nodePath!, env: env() }); + const { createConnection } = await import("net"); + await new Promise((resolve) => { + const c = createConnection(paths.socket); + c.on("connect", () => c.write(encodeJson({ t: "accepted" } as ControlMessage))); + c.on("close", () => resolve()); + c.on("error", () => resolve()); + c.resume(); + }); + expect((await cli(["--version"])).stdout).toBe("fake 1.0.0\n"); + + // `run` requests missing or mistyping required fields are bypassed, + // never crash the daemon, and never stop it as a "stale build". + const fp = controlFingerprint({ binFile, mainFile, execPath: nodePath!, env: env() }); + const good = { + t: "run", + fingerprint: fp, + argv: ["tap", "1", "1"], + cwd: "/", + env: {}, + tty: { stdout: { isTTY: false }, stderr: { isTTY: false } }, + }; + const malformed: unknown[] = [ + { t: "run" }, + { ...good, fingerprint: undefined }, + { ...good, fingerprint: null }, + { ...good, fingerprint: {} }, + { ...good, fingerprint: { ...fp, protocol: "1" } }, + { ...good, argv: "tap" }, + { ...good, argv: ["tap", 1] }, + { ...good, cwd: undefined }, + { ...good, env: { A: 1 } }, + { ...good, tty: undefined }, + { ...good, tty: { stdout: { isTTY: false } } }, + { ...good, umask: "022" }, + ]; + for (const msg of malformed) { + const reply = await new Promise((resolve) => { + const c = createConnection(paths.socket); + let data = Buffer.alloc(0); + c.on("connect", () => c.write(encodeFrame(FRAME_JSON, JSON.stringify(msg)))); + c.on("data", (d) => (data = Buffer.concat([data, Buffer.from(d)]))); + c.on("close", () => resolve(new FrameDecoder().push(data).map((f) => f.payload.toString()).join(""))); + }); + expect(JSON.parse(reply)).toEqual({ t: "bypass", reason: "malformed run request" }); + } + const after = await status(); + expect(after).toMatchObject({ running: true, busy: 0, served: 1 }); + expect(JSON.parse((await cli(["tap", "1", "1"])).stdout).ppid).toBe(after.pid); + }); + // ─── Review regressions ────────────────────────────────────────────── + + function race(o: { stallAfter: string; stallMs: number; acceptTimeoutMs: number; marker: string }) { + return run(nodePath!, [driverFile], { + env: { + MARKER: o.marker, + RACE_OPTS: JSON.stringify({ binFile, mainFile, argv: ["tap", "1", "1"], ...o }), + }, + }).then((r) => { + const line = r.stderr.split("\n").find((l) => l.startsWith("RESULT ")); + return { ...r, result: JSON.parse(line!.slice(7)) as { kind: string; reason?: string; code?: number; signal?: string | null } }; + }); + } + + const ranCount = (marker: string) => (existsSync(marker) ? readFileSync(marker, "utf8").split("\n").filter(Boolean).length : 0); + + test("an accept timeout that fires before go never also runs the command in a worker", async () => { + await startDaemon(); + const marker = join(work, "ran.txt"); + // The client stalls right after `run`, so by the time it looks again its + // timer has expired even though `accepted` is waiting in the buffer. + const r = await race({ stallAfter: "run", stallMs: 400, acceptTimeoutMs: 50, marker }); + expect(r.result).toEqual({ kind: "bypass", reason: "accept timeout" }); + // The held worker went back to the pool untouched. + await until(async () => { + const s = await status(); + return s.busy === 0 && (s.warm ?? 0) >= 1; + }); + expect((await status()).served).toBe(0); + expect(ranCount(marker)).toBe(0); + }); + + test("once go is sent, a stall past the timeout never falls back", async () => { + await startDaemon(); + const marker = join(work, "ran.txt"); + const r = await race({ stallAfter: "go", stallMs: 1500, acceptTimeoutMs: 1000, marker }); + expect(r.result).toEqual({ kind: "done", code: 0, signal: null }); + expect(ranCount(marker)).toBe(1); + expect((await status()).served).toBe(1); + }); + + test("refuses a group/other-writable or symlinked control dir", async () => { + chmodSync(ctlDir, 0o777); + const r = await cli(["tap", "1", "1"]); + expect(r.code).toBe(0); + expect(JSON.parse(r.stdout).argv).toEqual(["tap", "1", "1"]); + const start = await cli(["control", "start"]); + expect(start.code).toBe(1); + expect(start.stderr).toMatch(/can't start: .* group\/other accessible/); + // The daemon itself refuses too. + const direct = await cli(["__control-daemon"]); + expect(direct.code).toBe(1); + expect(direct.stderr).toMatch(/refused to start/); + await Bun.sleep(200); + expect(daemonPids()).toEqual([]); + chmodSync(ctlDir, 0o700); + + const real = mkdtempSync(join(root, "real")); + const link = join(root, `link-${Date.now()}`); + symlinkSync(real, link); + const viaLink = { env: { [CONTROL_DIR_ENV]: link } }; + expect((await cli(["control", "start"], viaLink)).stderr).toMatch(/symlink/); + expect((await cli(["tap", "1", "1"], viaLink)).code).toBe(0); + await Bun.sleep(200); + expect(daemonPids()).toEqual([]); + }); + + test("never sends a command to a planted (symlinked) socket", async () => { + const elsewhere = mkdtempSync(join(root, "e")); + const planted = join(elsewhere, "p.sock"); + const log = join(elsewhere, "received"); + const listener = spawn(nodePath!, [ + "-e", + `const fs=require("fs");require("net").createServer(c=>c.on("data",d=>fs.appendFileSync(${JSON.stringify(log)},d))).listen(${JSON.stringify(planted)},()=>console.log("up"))`, + ]); + stray.push(listener); + await new Promise((resolve) => listener.stdout.on("data", () => resolve())); + symlinkSync(planted, paths().socket); + const r = await cli(["tap", "1", "1"], { env: { SECRET_TOKEN: "hunter2" } }); + expect(r.code).toBe(0); + expect(JSON.parse(r.stdout).argv).toEqual(["tap", "1", "1"]); + await Bun.sleep(100); + expect(existsSync(log)).toBe(false); + }); + + test("binds its socket owner-only", async () => { + await startDaemon(); + expect(statSync(paths().socket).mode & 0o777).toBe(0o600); + expect(statSync(ctlDir).mode & 0o077).toBe(0); + }); + + test("workers that can't load: start fails loudly, callers run in-process, no respawn loop", async () => { + const broken = { env: { FAKE_WORKER_LOAD_FAIL: "1" } }; + const start = await cli(["control", "start"], broken); + expect(start.code).toBe(1); + expect(start.stderr).toContain("workers failed to load the CLI"); + expect(start.stderr).toContain("cannot load ws"); + expect(existsSync(paths().failFile)).toBe(true); + await until(async () => daemonPids().length === 0); + // status explains why nothing is running. + const st = await cli(["control", "status"], broken); + expect(st.code).toBe(1); + expect(st.stdout).toMatch(/workers failed to load the CLI .*`serve-sim control start` to retry/s); + expect(st.stdout).toContain("cannot load ws"); + expect(JSON.parse((await cli(["control", "status", "--json"], broken)).stdout).failed.reason).toContain("cannot load ws"); + + // In-process still works, and the fail marker stops auto-start. + for (let i = 0; i < 3; i++) expect(await cli(["--version"], broken)).toMatchObject({ code: 0, stdout: "fake 1.0.0\n" }); + await Bun.sleep(300); + expect(daemonPids()).toEqual([]); + + // A caller queued on such a daemon is told to bypass, not exit 1. + rmSync(paths().failFile); + const daemon = spawn(nodePath!, [binFile, "__control-daemon"], { env: env(broken.env), stdio: "ignore" }); + stray.push(daemon); + const r = await cli(["tap", "1", "1"], broken); + expect(r.code).toBe(0); + expect(JSON.parse(r.stdout).argv).toEqual(["tap", "1", "1"]); + await new Promise((res) => (daemon.exitCode != null ? res(null) : daemon.on("close", res))); + }); + + test("a write over 64 KB followed by process.exit arrives intact", async () => { + await startDaemon(); + const r = await cli(["event-log", "500000"]); + expect(r.code).toBe(0); + expect(r.stdout.length).toBe(500_000); + expect((await status()).served).toBe(1); + }); + + test("a slow reader holds back a big output instead of buffering it in the daemon", async () => { + const daemon = await startDaemon(); + const rss = (pid: number) => Number(spawnSync("ps", ["-o", "rss=", "-p", String(pid)], { encoding: "utf8" }).stdout.trim()) * 1024; + const before = rss(daemon.pid); + const size = 64 * 1024 * 1024; + // Nobody reads the pipe for 3 s, then it is counted. Under 2>&1 and + // with separate streams. + const pending = Promise.all( + [`"$0" "$1" event-log $2 | (sleep 3; wc -c)`, `"$0" "$1" event-log $2 2>&1 | (sleep 3; wc -c)`].map((script) => + run("/bin/sh", ["-c", script, nodePath!, binFile, String(size)]), + ), + ); + await until(async () => (await status()).busy === 2); + let peakBuffered = 0; + let peakRss = 0; + const end = Date.now() + 2000; + while (Date.now() < end) { + const s = await status(); + // Still in flight: the workers are waiting on the readers. + expect(s.busy).toBe(2); + peakBuffered = Math.max(peakBuffered, s.buffered ?? 0); + peakRss = Math.max(peakRss, rss(daemon.pid)); + await Bun.sleep(100); + } + expect(peakBuffered).toBeLessThan(4 * 1024 * 1024); + expect(peakRss - before).toBeLessThan(32 * 1024 * 1024); + for (const r of await pending) { + expect(r.code).toBe(0); + expect(r.stdout.trim()).toBe(String(size)); + } + await until(async () => (await status()).busy === 0); + expect((await status()).served).toBe(2); + }, 30_000); + + test("keeps stdout/stderr order under 2>&1", async () => { + const daemon = await startDaemon(); + const expected = Array.from({ length: 40 }, (_, i) => `out${i}\nerr${i}\n`).join("") + `ppid ${daemon.pid}\n`; + for (let i = 0; i < 3; i++) { + const r = await run("/bin/sh", ["-c", `exec "$0" "$1" gesture 2>&1`, nodePath!, binFile]); + expect(r.stdout).toBe(expected); + } + // Separate streams stay separate. + const split = await cli(["gesture"]); + expect(split.stderr).toBe(Array.from({ length: 40 }, (_, i) => `err${i}\n`).join("")); + }); + + test("the first caller's NODE_OPTIONS doesn't leak; callers with node flags run in-process", async () => { + const pre = join(work, "pre.cjs"); + writeFileSync(pre, `globalThis.__pre = "preloaded-by-first-caller";`); + const withPre = { env: { NODE_OPTIONS: `--require ${pre}` } }; + const start = await cli(["control", "start", "--json"], withPre); + expect(start.code).toBe(0); + const { pid } = JSON.parse(start.stdout); + await warm(); + const plain = JSON.parse((await cli(["buffer"])).stdout); + expect(plain).toMatchObject({ pre: null, nodeOptions: null, ppid: pid }); + const own = JSON.parse((await cli(["buffer"], withPre)).stdout); + expect(own.pre).toBe("preloaded-by-first-caller"); + expect(own.ppid).not.toBe(pid); + const flagged = JSON.parse((await cli(["buffer"], { nodeArgs: ["--no-warnings"] })).stdout); + expect(flagged.execArgv).toEqual(["--no-warnings"]); + expect(flagged.ppid).not.toBe(pid); + }); + + test("works from a deleted cwd, with and without the control process", async () => { + const gone = join(work, "gone"); + const script = `mkdir "$2" && cd "$2" && rmdir "$2" && exec "$0" "$1" --version`; + for (const extra of [{ SERVE_SIM_CONTROL: "0" }, {}]) { + const r = await run("/bin/sh", ["-c", script, nodePath!, binFile, gone], { env: extra }); + expect(r).toMatchObject({ code: 0, stdout: "fake 1.0.0\n" }); + } + await startDaemon(); + const r = await run("/bin/sh", ["-c", script, nodePath!, binFile, gone]); + expect(r).toMatchObject({ code: 0, stdout: "fake 1.0.0\n" }); + }); + + test("the daemon re-checks that a command may run in a worker", async () => { + await startDaemon(); + const { createConnection } = await import("net"); + const fp = controlFingerprint({ binFile, mainFile, execPath: nodePath!, env: env() }); + const reply = await new Promise((resolve) => { + const c = createConnection(paths().socket); + let data = Buffer.alloc(0); + c.on("connect", () => + c.write( + encodeJson({ + t: "run", + fingerprint: fp, + argv: ["--port", "3412"], + cwd: "/", + env: {}, + tty: { stdout: { isTTY: false }, stderr: { isTTY: false } }, + }), + ), + ); + c.on("data", (d) => (data = Buffer.concat([data, Buffer.from(d)]))); + c.on("close", () => resolve(new FrameDecoder().push(data).map((f) => f.payload.toString()).join(""))); + }); + expect(JSON.parse(reply)).toEqual({ t: "bypass", reason: "not dispatchable" }); + expect((await status()).busy).toBe(0); + }); + test("a stop request lets a running command finish", async () => { + const daemon = await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + stray.push(child); + let stdout = ""; + await new Promise((resolve) => + child.stdout.on("data", (d) => { + stdout += d; + if (stdout.includes("waiting")) resolve(); + }), + ); + const { createConnection } = await import("net"); + await new Promise((resolve) => { + const c = createConnection(paths().socket); + c.on("connect", () => c.write(encodeJson({ t: "stop" }))); + c.resume(); + c.on("close", () => resolve()); + }); + // Longer than the daemon's reply-drain window. + await Bun.sleep(1500); + expect(child.exitCode).toBeNull(); + child.kill("SIGINT"); + const code = await new Promise((r) => child.on("close", (c) => r(c))); + expect(code).toBe(130); + expect(stdout).toBe("waiting\ngot SIGINT\n"); + await until(async () => { + try { + process.kill(daemon.pid, 0); + return false; + } catch { + return true; + } + }); + }); + const alive = (pid: number) => { + try { + process.kill(pid, 0); + return true; + } catch { + return false; + } + }; + const workerPids = (daemonPid: number) => + spawnSync("pgrep", ["-P", String(daemonPid)], { encoding: "utf8" }) + .stdout.split("\n") + .filter(Boolean) + .map(Number); + + test("a held worker that dies before go sends the caller in-process and frees the daemon", async () => { + // Idle longer than the client's stall, so the daemon is still there to + // report busy 0 once the stall ends. + const r0 = await cli(["control", "start", "--json"], { env: { SERVE_SIM_CONTROL_IDLE_MS: "7000" } }); + const daemon = JSON.parse(r0.stdout) as { pid: number }; + await warm(); + const marker = join(work, "ran.txt"); + // The client stalls after `run`, so the daemon holds a worker for it + // while we kill every worker (the held one included). + // stallMs only has to outlast the polling and kills below, and stay + // under the daemon's 10 s go timeout. + const pending = race({ stallAfter: "run", stallMs: 5000, acceptTimeoutMs: 30_000, marker }); + await until(async () => (await status()).busy === 1); + for (const pid of workerPids(daemon.pid)) process.kill(pid, "SIGKILL"); + const r = await pending; + expect(r.result).toEqual({ kind: "bypass", reason: "worker exited" }); + expect(ranCount(marker)).toBe(0); + await until(async () => (await status()).busy === 0); + // The real bin finishes such a call in-process. + expect((await cli(["--version"])).stdout).toBe("fake 1.0.0\n"); + // Nothing pins it: it still idle-exits. + await until(async () => !alive(daemon.pid), 12_000); + }, 30_000); + + test("stop gives up on a daemon that never acknowledges and terminates only the recorded one", async () => { + const p = paths(); + // Answers ping like a daemon but ignores stop; `__control-daemon` in its + // argv is what the pid check looks for. + const script = ` + const net = require("net"); + const pong = (pid) => { const b = Buffer.from(JSON.stringify({ t: "pong", status: { pid, startedAt: 0, lastActiveAt: Date.now(), idleMs: 60000, warm: 1, warming: 0, busy: 0, served: 0, socket: ${JSON.stringify(p.socket)} } })); const h = Buffer.alloc(5); h.writeUInt8(0x4a, 0); h.writeUInt32BE(b.length, 1); return Buffer.concat([h, b]); }; + net.createServer((c) => c.on("data", (d) => { if (d.includes('"ping"')) c.end(pong(process.pid)); })).listen(${JSON.stringify(p.socket)}, () => console.log("up"));`; + const startFake = async () => { + const fake = spawn(nodePath!, ["-e", script, "__control-daemon"]); + stray.push(fake); + await new Promise((resolve) => fake.stdout.on("data", () => resolve())); + return fake; + }; + + // The pid file names someone else: nothing is killed. + const fake = await startFake(); + const bystander = spawn("/bin/sleep", ["30"]); + stray.push(bystander); + writeFileSync(p.pidFile, JSON.stringify({ pid: bystander.pid })); + const t0 = Date.now(); + const r1 = JSON.parse((await cli(["control", "stop", "--json"])).stdout); + expect(Date.now() - t0).toBeLessThan(10_000); + expect(r1).toMatchObject({ wasRunning: true, pid: fake.pid, stopped: false }); + expect(alive(fake.pid!)).toBe(true); + expect(alive(bystander.pid!)).toBe(true); + + // The pid file names it: it is terminated after the deadline. + writeFileSync(p.pidFile, JSON.stringify({ pid: fake.pid })); + const r2 = JSON.parse((await cli(["control", "stop", "--json"])).stdout); + expect(r2).toMatchObject({ wasRunning: true, pid: fake.pid, stopped: true }); + expect(alive(fake.pid!)).toBe(false); + }, 30_000); + + test("stop with a command in flight reports stopping, not stopped", async () => { + const daemon = await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + stray.push(child); + await new Promise((resolve) => child.stdout.on("data", () => resolve())); + const stop = await cli(["control", "stop", "--json"]); + expect(JSON.parse(stop.stdout)).toEqual({ + wasRunning: true, + pid: daemon.pid, + stopped: false, + stopping: true, + busy: 1, + clearedStale: false, + }); + expect(alive(daemon.pid)).toBe(true); + child.kill("SIGINT"); + await until(async () => !alive(daemon.pid)); + expect(JSON.parse((await cli(["control", "stop", "--json"])).stdout)).toMatchObject({ wasRunning: false }); + }); + + test("stop text output says it is waiting for running commands", async () => { + await startDaemon(); + const child = spawn(nodePath!, [binFile, "settle"], { cwd: work, env: env() }); + stray.push(child); + await new Promise((resolve) => child.stdout.on("data", () => resolve())); + const stop = await cli(["control", "stop"]); + expect(stop.stdout).toMatch(/^stopping \(pid \d+\); waiting for 1 running command\(s\) to finish\n$/); + child.kill("SIGINT"); + }); + + test("workers run with the caller's umask", async () => { + const daemon = await startDaemon(); + const script = `umask $2 && exec "$0" "$1" tap 1 1`; + for (const mask of ["077", "027"]) { + const r = await run("/bin/sh", ["-c", script, nodePath!, binFile, mask]); + const seen = JSON.parse(r.stdout); + expect(seen.ppid).toBe(daemon.pid); + expect(seen.umask).toBe(parseInt(mask, 8)); + } + }); + + test("sandboxed callers run in-process and never start a daemon", async () => { + for (const marker of [{ CODEX_SANDBOX: "seatbelt" }, { SANDBOX_RUNTIME: "1" }]) { + expect((await cli(["tap", "1", "1"], { env: marker })).code).toBe(0); + } + await Bun.sleep(300); + expect((await status()).running).toBe(false); + expect(daemonPids()).toEqual([]); + const daemon = await startDaemon(); + const seen = JSON.parse((await cli(["tap", "1", "1"], { env: { CODEX_SANDBOX_NETWORK_DISABLED: "1" } })).stdout); + expect(seen.ppid).not.toBe(daemon.pid); + expect((await status()).served).toBe(0); + }); + + test("control start refuses inside a sandbox", async () => { + for (const [key, value] of [["CODEX_SANDBOX", "seatbelt"], ["SANDBOX_RUNTIME", "1"]] as const) { + const r = await cli(["control", "start"], { env: { [key]: value } }); + expect(r.code).toBe(1); + expect(r.stderr).toBe(`serve-sim: control process can't start inside a sandbox (${key})\n`); + } + await Bun.sleep(300); + expect((await status()).running).toBe(false); + expect(daemonPids()).toEqual([]); + expect(existsSync(ctlDir) ? readdirSync(ctlDir) : []).toEqual([]); + }); +}); diff --git a/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts b/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts new file mode 100644 index 000000000..91436ce45 --- /dev/null +++ b/packages/serve-sim/src/__tests__/fixtures/control-fake-cli.ts @@ -0,0 +1,80 @@ +// Stand-in for dist/serve-sim-cli.js in control-process tests: built next to +// a real bin build, it reports what the process it ran in looked like. +import { appendFileSync } from "fs"; +import { runCliMain } from "../../control-protocol"; + +// Simulates an install whose bundle can't load in a worker (only workers +// have an IPC channel), while direct runs still work. +if (process.env.FAKE_WORKER_LOAD_FAIL === "1" && process.send) throw new Error("cannot load ws"); + +async function main() { + const [command, ...rest] = process.argv.slice(2); + if (command === "--version") { + console.log("fake 1.0.0"); + return; + } + if (command === "tap") { + if (process.env.MARKER) appendFileSync(process.env.MARKER, `ran ${process.pid}\n`); + console.log( + JSON.stringify({ + argv: process.argv.slice(2), + argv1: process.argv[1], + cwd: process.cwd(), + foo: process.env.FOO ?? null, + role: process.env.SERVE_SIM_CONTROL_ROLE ?? null, + stdoutIsTTY: process.stdout.isTTY === true, + columns: process.stdout.columns ?? null, + pid: process.pid, + ppid: process.ppid, + umask: process.umask(), + }), + ); + process.stderr.write("to stderr\n"); + process.exitCode = Number(process.env.EXIT_CODE ?? 0); + return; + } + if (command === "button") { + console.log("exiting hard"); + process.exit(Number(rest[0] ?? 7)); + } + if (command === "settle") { + process.on("SIGINT", () => { + console.log("got SIGINT"); + process.exit(130); + }); + console.log("waiting"); + await new Promise((r) => setTimeout(r, 10_000)); + console.log("timed out"); + return; + } + if (command === "event-log") { + // A big write followed by a hard exit must not lose output. + process.stdout.write("x".repeat(Number(rest[0]))); + process.exit(0); + } + if (command === "gesture") { + for (let i = 0; i < 40; i++) { + process.stdout.write(`out${i}\n`); + process.stderr.write(`err${i}\n`); + } + console.log(`ppid ${process.ppid}`); + return; + } + if (command === "buffer") { + console.log( + JSON.stringify({ + pre: (globalThis as { __pre?: string }).__pre ?? null, + execArgv: process.execArgv, + nodeOptions: process.env.NODE_OPTIONS ?? null, + ppid: process.ppid, + }), + ); + return; + } + if (command === "ax") { + throw new Error("boom from ax"); + } + console.log(`direct-only:${command ?? ""}`); +} + +await runCliMain(main); diff --git a/packages/serve-sim/src/__tests__/fixtures/control-race-driver.ts b/packages/serve-sim/src/__tests__/fixtures/control-race-driver.ts new file mode 100644 index 000000000..10fe2e257 --- /dev/null +++ b/packages/serve-sim/src/__tests__/fixtures/control-race-driver.ts @@ -0,0 +1,31 @@ +// Drives dispatchViaControl under node with a synchronous stall injected +// right after a chosen client frame, to pin down what happens when the +// accept timer and the daemon's reply race. +import { dispatchViaControl } from "../../control-client"; + +const opts = JSON.parse(process.env.RACE_OPTS!) as { + binFile: string; + mainFile: string; + argv: string[]; + stallAfter: string; + stallMs: number; + acceptTimeoutMs: number; +}; + +const result = await dispatchViaControl(opts.argv, { + binFile: opts.binFile, + mainFile: opts.mainFile, + execPath: process.execPath, + execArgv: [], + env: process.env, + cwd: () => process.cwd(), + stdout: process.stdout, + stderr: process.stderr, + acceptTimeoutMs: opts.acceptTimeoutMs, + afterWrite: (t) => { + if (t !== opts.stallAfter) return; + const end = Date.now() + opts.stallMs; + while (Date.now() < end) {} + }, +}); +process.stderr.write(`RESULT ${JSON.stringify(result)}\n`); diff --git a/packages/serve-sim/src/bin.ts b/packages/serve-sim/src/bin.ts new file mode 100644 index 000000000..28d3977ad --- /dev/null +++ b/packages/serve-sim/src/bin.ts @@ -0,0 +1,68 @@ +#!/usr/bin/env node +/** + * The `serve-sim` bin. Deliberately tiny: short commands are handed to the + * persistent control process (see control-daemon.ts) so they skip loading + * the ~1 MB CLI bundle; everything else, and every case where the control + * process is unavailable, imports the bundle and runs in-process as before. + */ +import { fileURLToPath } from "url"; +import { controlCli, dispatchViaControl, type ControlContext } from "./control-client"; +import { runControlDaemonProcess } from "./control-daemon"; +import { + CONTROL_ACCEPT_ENV, + CONTROL_DAEMON_ARG, + CONTROL_IDLE_ENV, + CONTROL_ROLE_ENV, + DEFAULT_POOL_SIZE, + controlFingerprint, + controlPaths, + parseAcceptMs, + parseIdleMs, +} from "./control-protocol"; +import { runControlWorker } from "./control-worker"; + +// A sibling file at runtime; kept out of this bundle on purpose. +const mainUrl = new URL("./serve-sim-cli.js", import.meta.url); +const binFile = fileURLToPath(import.meta.url); +const args = process.argv.slice(2); + +function context(): ControlContext { + return { + binFile, + mainFile: fileURLToPath(mainUrl), + execPath: process.execPath, + execArgv: process.execArgv, + env: process.env, + // Lazy: a deleted cwd must not break commands that never dispatch. + cwd: () => process.cwd(), + stdout: process.stdout, + stderr: process.stderr, + acceptTimeoutMs: parseAcceptMs(process.env[CONTROL_ACCEPT_ENV]), + }; +} + +if (process.env[CONTROL_ROLE_ENV] === "worker") { + await runControlWorker(mainUrl.href); +} else if (args[0] === CONTROL_DAEMON_ARG) { + const ctx = context(); + const paths = controlPaths(ctx); + await runControlDaemonProcess({ + binFile, + paths, + fingerprint: controlFingerprint(ctx), + idleMs: parseIdleMs(process.env[CONTROL_IDLE_ENV]), + poolSize: DEFAULT_POOL_SIZE, + roleEnv: CONTROL_ROLE_ENV, + }); +} else if (args[0] === "control") { + process.exitCode = await controlCli(args.slice(1), context()); +} else { + const result = await dispatchViaControl(args, context()); + if (result.kind === "bypass") { + await import(mainUrl.href); + } else if (result.signal) { + process.kill(process.pid, result.signal); + } else { + process.exitCode = result.code ?? 1; + } +} diff --git a/packages/serve-sim/src/control-client.ts b/packages/serve-sim/src/control-client.ts new file mode 100644 index 000000000..f2686763c --- /dev/null +++ b/packages/serve-sim/src/control-client.ts @@ -0,0 +1,550 @@ +/** + * Thin client for the persistent control process, plus `serve-sim control + * start|stop|status`. Runs inside the tiny bin entry, so node builtins only. + * + * The daemon replies `accepted` once it holds a warm worker for the call, + * and only hands the worker the command after the client answers `go`. + * Every failure before `go` therefore means "run it in-process instead": + * nothing has run yet, so a missing, stale or wedged daemon only costs a + * failed connect. After `go` the client never falls back. + */ +import { execFileSync, spawn } from "child_process"; +import { existsSync, fstatSync, readFileSync, unlinkSync } from "fs"; +import { createConnection } from "net"; +import { + CONTROL_DAEMON_ARG, + FORWARDED_SIGNALS, + FRAME_STDERR, + FRAME_STDOUT, + FrameDecoder, + MAX_SOCKET_PATH_BYTES, + controlFingerprint, + controlMode, + controlPaths, + encodeJson, + isDispatchable, + nodeRuntimeOverride, + parseJsonFrame, + sandboxMarker, + unsafeControlDir, + unsafeControlSocket, + withoutNodeRuntimeEnv, + type ControlFingerprint, + type ControlPaths, + type ControlStatus, + type ForwardedSignal, +} from "./control-protocol"; +import { pingSocket } from "./control-daemon"; + +export interface ControlContext { + binFile: string; + mainFile: string; + execPath: string; + /** The caller's node flags; workers can't adopt them. */ + execArgv: readonly string[]; + env: NodeJS.ProcessEnv; + /** Read lazily: the caller's cwd may have been deleted. */ + cwd: () => string; + stdout: NodeJS.WriteStream; + stderr: NodeJS.WriteStream; + /** How long to wait for the daemon to accept before running in-process. */ + acceptTimeoutMs?: number; + /** Test hook: called right after each client frame is written. */ + afterWrite?: (t: string) => void; +} + +export type DispatchResult = + | { kind: "bypass"; reason: string } + | { kind: "done"; code: number | null; signal: NodeJS.Signals | null }; + +function pathsFor(ctx: ControlContext): ControlPaths { + return controlPaths({ binFile: ctx.binFile, execPath: ctx.execPath, env: ctx.env }); +} + +function stringEnv(env: NodeJS.ProcessEnv): Record { + const out: Record = {}; + for (const [k, v] of Object.entries(env)) if (typeof v === "string") out[k] = v; + return out; +} + +/** Whether fds 1 and 2 are the same open file (`2>&1`, one pty). */ +function sameOutputFile(): boolean { + try { + const out = fstatSync(1); + const err = fstatSync(2); + return out.dev === err.dev && out.ino === err.ino; + } catch { + return false; + } +} + +/** Don't retry a daemon whose workers couldn't load this build for a while. */ +const FAILED_BACKOFF_MS = 10 * 60_000; + +interface FailRecord { + at: number; + binMtimeMs: number; + mainMtimeMs: number; + reason?: string; +} + +function readFailRecord(file: string): FailRecord | null { + try { + const v = JSON.parse(readFileSync(file, "utf8")) as FailRecord; + return typeof v.at === "number" ? v : null; + } catch { + return null; + } +} + +function recentlyFailed(paths: ControlPaths, fp: ControlFingerprint): boolean { + const rec = readFailRecord(paths.failFile); + return ( + rec != null && + Date.now() - rec.at < FAILED_BACKOFF_MS && + rec.binMtimeMs === fp.binMtimeMs && + rec.mainMtimeMs === fp.mainMtimeMs + ); +} + +/** Start a detached daemon and return immediately. */ +function spawnDaemon(ctx: ControlContext): void { + try { + const child = spawn(ctx.execPath, [ctx.binFile, CONTROL_DAEMON_ARG], { + cwd: "/", + detached: true, + stdio: "ignore", + env: withoutNodeRuntimeEnv(ctx.env), + }); + child.on("error", () => {}); + child.unref(); + } catch {} +} + +/** Why the control socket can't be used, or null. "missing" means start one. */ +function unusableSocket(paths: ControlPaths): string | null { + if (Buffer.byteLength(paths.socket) > MAX_SOCKET_PATH_BYTES) return "socket path too long"; + const dir = unsafeControlDir(paths.dir); + if (dir) return dir === "missing" ? "missing" : `control dir ${dir}`; + const sock = unsafeControlSocket(paths.socket); + if (sock) return sock === "missing" ? "missing" : `control socket ${sock}`; + return null; +} + +/** + * Run `args` through the control process when possible. Resolves "bypass" + * whenever the caller should run the command in-process. + */ +export function dispatchViaControl(args: string[], ctx: ControlContext): Promise { + const bypass = (reason: string) => Promise.resolve({ kind: "bypass", reason }); + const mode = controlMode(ctx.env); + if (mode === "off") return bypass("disabled"); + let cwd: string; + try { + cwd = ctx.cwd(); + } catch { + return bypass("no cwd"); + } + if (!isDispatchable(args, cwd)) return bypass("not dispatchable"); + const runtime = nodeRuntimeOverride(ctx.env, ctx.execArgv); + if (runtime) return bypass(`caller sets ${runtime}`); + const sandbox = sandboxMarker(ctx.env); + if (sandbox) return bypass(`sandboxed (${sandbox})`); + const paths = pathsFor(ctx); + const fingerprint = controlFingerprint(ctx); + const unusable = unusableSocket(paths); + if (unusable === "missing") { + if (mode === "auto" && !recentlyFailed(paths, fingerprint)) spawnDaemon(ctx); + return bypass("not running"); + } + if (unusable) return bypass(unusable); + + return new Promise((resolve) => { + const conn = createConnection(paths.socket); + const decoder = new FrameDecoder(); + // Once `go` is written the worker may be running: never fall back after. + let committed = false; + let settled = false; + const signalHandlers = new Map void>(); + const send = (msg: Parameters[0]) => { + conn.write(encodeJson(msg)); + ctx.afterWrite?.(msg.t); + }; + + const finish = (result: DispatchResult) => { + if (settled) return; + settled = true; + clearTimeout(acceptTimer); + for (const [sig, handler] of signalHandlers) process.off(sig, handler); + conn.destroy(); + resolve(result); + }; + const lost = (detail: string) => { + ctx.stderr.write(`serve-sim: lost the control process mid-command (${detail})\n`); + finish({ kind: "done", code: 1, signal: null }); + }; + // Covers connect + waiting for a worker. It can only fire before `go`: + // the `accepted` handler clears it and sends `go` in the same tick. + const acceptTimer = setTimeout( + () => finish({ kind: "bypass", reason: "accept timeout" }), + ctx.acceptTimeoutMs ?? 1000, + ); + + conn.on("error", (error: NodeJS.ErrnoException) => { + if (committed) return lost(error.code ?? error.message); + if (mode === "auto" && (error.code === "ENOENT" || error.code === "ECONNREFUSED") && !recentlyFailed(paths, fingerprint)) spawnDaemon(ctx); + finish({ kind: "bypass", reason: error.code ?? "connect failed" }); + }); + conn.on("close", () => { + if (settled) return; + if (committed) lost("closed"); + else finish({ kind: "bypass", reason: "closed before accept" }); + }); + conn.on("connect", () => { + send({ + t: "run", + fingerprint, + argv: args, + cwd, + env: stringEnv(ctx.env), + tty: { + stdout: { isTTY: ctx.stdout.isTTY === true, columns: ctx.stdout.columns }, + stderr: { isTTY: ctx.stderr.isTTY === true, columns: ctx.stderr.columns }, + }, + sharedOutput: sameOutputFile(), + umask: process.umask(), + }); + }); + // Backpressure: stop reading the socket while stdout/stderr can't keep + // up, so the daemon stops reading the worker instead of anyone + // buffering a big output in memory. Resume once every full destination + // has drained. + const full = new Set(); + const relay = (dest: NodeJS.WriteStream, payload: Buffer) => { + if (dest.write(payload) || full.has(dest)) return; + full.add(dest); + conn.pause(); + dest.once("drain", () => { + full.delete(dest); + if (full.size === 0 && !settled) conn.resume(); + }); + }; + conn.on("data", (chunk) => { + if (settled) return; + let frames; + try { + frames = decoder.push(chunk); + } catch { + conn.destroy(); + return; + } + for (const frame of frames) { + if (settled) return; + if (frame.type === FRAME_STDOUT) { + relay(ctx.stdout, frame.payload); + continue; + } + if (frame.type === FRAME_STDERR) { + relay(ctx.stderr, frame.payload); + continue; + } + const msg = parseJsonFrame(frame); + if (!msg) continue; + // The daemon only says bypass before it handed the job to a worker. + if (msg.t === "bypass") finish({ kind: "bypass", reason: msg.reason }); + else if (msg.t === "accepted" && !committed) { + clearTimeout(acceptTimer); + committed = true; + send({ t: "go" }); + // From here the worker owns the command: forward signals to it. + for (const sig of FORWARDED_SIGNALS) { + const handler = () => send({ t: "signal", signal: sig }); + signalHandlers.set(sig, handler); + process.on(sig, handler); + } + } else if (msg.t === "exit") { + finish({ kind: "done", code: msg.code, signal: (msg.signal as NodeJS.Signals | null) ?? null }); + } + } + }); + }); +} + +// ─── serve-sim control start|stop|status ───────────────────────────────── + +const CONTROL_USAGE = `Usage: serve-sim control [status|start|stop] [--json] + +Persistent control process: keeps pre-warmed workers so short commands +(tap, type, button, ax, buffer, --help, ...) skip Node startup. Started +automatically on first use and exits after SERVE_SIM_CONTROL_IDLE_MS +(default 5 minutes) of quiet. SERVE_SIM_CONTROL=0 disables it; under CI it +is only used when already running unless SERVE_SIM_CONTROL=1. + + status Show whether it is running (exit 1 if not) + start Start it if needed and wait until it answers (idempotent) + stop Stop it and clear stale socket/pid files (idempotent)`; + +interface PidRecord { + pid: number; +} + +function readPidRecord(file: string): PidRecord | null { + try { + const v = JSON.parse(readFileSync(file, "utf8")) as PidRecord; + return typeof v.pid === "number" ? v : null; + } catch { + return null; + } +} + +function isAlive(pid: number): boolean { + try { + process.kill(pid, 0); + return true; + } catch (error) { + return (error as NodeJS.ErrnoException).code === "EPERM"; + } +} + +function looksLikeDaemon(pid: number): boolean { + try { + const args = execFileSync("ps", ["-p", String(pid), "-o", "args="], { encoding: "utf8", timeout: 1000 }); + return args.includes(CONTROL_DAEMON_ARG); + } catch { + return false; + } +} + +/** Remove socket/pid files no live daemon is behind. */ +async function clearStaleControlFiles(paths: ControlPaths): Promise { + if (await pingSocket(paths.socket)) return false; + let cleared = false; + if (existsSync(paths.socket)) { + try { + unlinkSync(paths.socket); + cleared = true; + } catch {} + } + const rec = readPidRecord(paths.pidFile); + if (existsSync(paths.pidFile) && (!rec || !isAlive(rec.pid))) { + try { + unlinkSync(paths.pidFile); + cleared = true; + } catch {} + } + return cleared; +} + +function sleep(ms: number) { + return new Promise((r) => setTimeout(r, ms)); +} + +async function waitFor(probe: () => Promise, timeoutMs: number): Promise { + const deadline = Date.now() + timeoutMs; + for (;;) { + const v = await probe(); + if (v) return v; + if (Date.now() >= deadline) return null; + await sleep(25); + } +} + +function waitForExit(pid: number, timeoutMs: number): Promise { + return waitFor(async () => (isAlive(pid) ? null : true), timeoutMs).then((v) => v === true); +} + +/** How long `control stop` waits for the daemon to acknowledge a stop. */ +const STOP_REPLY_TIMEOUT_MS = 2000; + +/** + * Ask the daemon to stop; resolves with how many commands it is still + * running, or null when it never acknowledged (wedged after answering ping). + */ +function requestStop(socket: string, timeoutMs = STOP_REPLY_TIMEOUT_MS): Promise { + return new Promise((resolve) => { + const conn = createConnection(socket); + const decoder = new FrameDecoder(); + let busy: number | null = null; + const done = () => { + clearTimeout(timer); + conn.destroy(); + resolve(busy); + }; + const timer = setTimeout(done, timeoutMs); + conn.on("connect", () => conn.write(encodeJson({ t: "stop" }))); + // Read the reply, or the socket never reaches end/close. + conn.on("data", (chunk) => { + try { + for (const frame of decoder.push(chunk)) { + const msg = parseJsonFrame(frame); + if (msg?.t === "stopping") busy = typeof msg.busy === "number" ? msg.busy : 0; + } + } catch {} + }); + conn.on("close", done); + conn.on("error", done); + }); +} + +/** + * SIGTERM an unresponsive daemon, but only if the pid file names a live + * control daemon (not us, not a recycled pid) and, when `expected` is known + * from a ping, the same one. Resolves the pid tried and whether it exited. + */ +async function terminateRecordedDaemon(paths: ControlPaths, expected?: number): Promise<{ pid: number; stopped: boolean } | null> { + const rec = readPidRecord(paths.pidFile); + if (!rec || rec.pid === process.pid || (expected != null && rec.pid !== expected)) return null; + if (!isAlive(rec.pid) || !looksLikeDaemon(rec.pid)) return null; + try { + process.kill(rec.pid, "SIGTERM"); + } catch {} + return { pid: rec.pid, stopped: await waitForExit(rec.pid, 3000) }; +} + +function formatStatus(s: ControlStatus): string { + const idleLeft = Math.max(0, s.idleMs - (Date.now() - s.lastActiveAt)); + return ( + `control process running (pid ${s.pid}): ${s.warm} warm, ${s.warming} warming, ${s.busy} busy, ` + + `${s.served} served; idle exit in ${Math.ceil(idleLeft / 1000)}s\n socket ${s.socket}` + ); +} + +export async function controlCli(args: string[], ctx: ControlContext): Promise { + const json = args.includes("--json"); + const rest = args.filter((a) => a !== "--json"); + const verb = rest[0] ?? "status"; + const out = (line: string) => ctx.stdout.write(`${line}\n`); + const paths = pathsFor(ctx); + + if (verb === "--help" || verb === "-h" || verb === "help" || rest.length > 1) { + (rest.length > 1 ? ctx.stderr : ctx.stdout).write(`${CONTROL_USAGE}\n`); + return rest.length > 1 ? 1 : 0; + } + const unsafeDir = unsafeControlDir(paths.dir); + if (unsafeDir && unsafeDir !== "missing" && verb !== "start") { + ctx.stderr.write(`serve-sim: ignoring control dir ${paths.dir}: ${unsafeDir}\n`); + return 1; + } + if (verb === "status") { + const status = unusableSocket(paths) ? null : await pingSocket(paths.socket); + // A recent fail record is why commands aren't starting one. + const failed = status ? null : readFailRecord(paths.failFile); + const recent = failed && Date.now() - failed.at < FAILED_BACKOFF_MS ? failed : null; + if (json) { + out( + JSON.stringify( + status + ? { running: true, ...status } + : { running: false, socket: paths.socket, ...(recent ? { failed: { at: recent.at, reason: recent.reason ?? "" } } : {}) }, + ), + ); + } else if (status) out(formatStatus(status)); + else if (recent) { + const ago = Math.max(0, Math.round((Date.now() - recent.at) / 1000)); + const reason = recent.reason?.trim() ? `\n${recent.reason.trimEnd()}` : ""; + out( + `control process not running: its workers failed to load the CLI ${ago}s ago, so commands run in-process ` + + `and won't auto-start it for ${Math.ceil(FAILED_BACKOFF_MS / 60_000)} minutes; ` + + `run \`serve-sim control start\` to retry${reason}`, + ); + } else out("control process not running"); + return status ? 0 : 1; + } + if (verb === "start") { + // A daemon born inside a sandbox would confine every other caller's + // commands for as long as it lives. + const sandbox = sandboxMarker(ctx.env); + if (sandbox) { + ctx.stderr.write(`serve-sim: control process can't start inside a sandbox (${sandbox})\n`); + return 1; + } + // Socket-level problems inside our own private dir are the daemon's to + // clear; refuse only what it can't fix. + const tooLong = Buffer.byteLength(paths.socket) > MAX_SOCKET_PATH_BYTES; + if (tooLong || (unsafeDir && unsafeDir !== "missing")) { + const why = tooLong + ? `socket path ${paths.socket} is ${Buffer.byteLength(paths.socket)} bytes (max ${MAX_SOCKET_PATH_BYTES}); set SERVE_SIM_CONTROL_DIR to a shorter directory` + : `${paths.dir} is ${unsafeDir}; it must be a directory owned by you with mode 0700`; + ctx.stderr.write(`serve-sim: control process can't start: ${why}\n`); + return 1; + } + let status = await pingSocket(paths.socket); + const already = status != null; + if (!status) { + // An explicit start retries even after workers failed to load. + try { + unlinkSync(paths.failFile); + } catch {} + spawnDaemon(ctx); + status = await waitFor(() => pingSocket(paths.socket), 5000); + // Don't report success until a worker could actually load the CLI; + // a daemon whose workers can't load writes its fail file and exits. + if (status && status.warm === 0) { + const ready = await waitFor(async () => { + const s = await pingSocket(paths.socket); + if (s) return s.warm > 0 ? s : null; + return existsSync(paths.failFile) ? "failed" : null; + }, 10_000); + status = ready && ready !== "failed" ? ready : null; + } + } + if (!status) { + const failed = readFailRecord(paths.failFile); + const detail = failed?.reason ? `: workers failed to load the CLI\n${failed.reason.trimEnd()}` : ""; + ctx.stderr.write(`serve-sim: control process did not start${detail}\n`); + return 1; + } + if (json) out(JSON.stringify({ running: true, alreadyRunning: already, ...status })); + else out(already ? `already running (pid ${status.pid})` : `started (pid ${status.pid})`); + if (controlMode(ctx.env) === "off") { + ctx.stderr.write("serve-sim: note: SERVE_SIM_CONTROL=0 is set, so commands won't use it\n"); + } + return 0; + } + if (verb === "stop") { + const status = await pingSocket(paths.socket); + let pid: number | null = status?.pid ?? null; + let stopped = false; + /** Commands the daemon is letting finish before it exits. */ + let running = 0; + const acked = status ? await requestStop(paths.socket) : null; + if (status && acked != null) { + running = acked; + stopped = await waitForExit(status.pid, running > 0 ? 1000 : 5000); + } else { + // Alive but not answering (wedged or stopped), or it answered ping + // but never acknowledged the stop: terminate it if the pid really is + // our daemon, not a recycled pid. + // (One that exited on its own meanwhile just counts as stopped.) + if (status && !isAlive(status.pid)) stopped = true; + else { + const killed = await terminateRecordedDaemon(paths, status?.pid); + if (killed) { + pid = killed.pid; + stopped = killed.stopped; + } + } + } + const cleared = await clearStaleControlFiles(paths); + const wasRunning = pid != null; + // Only report stopped once the process is really gone. + const stopping = wasRunning && !stopped; + if (json) { + out( + JSON.stringify({ + wasRunning, + pid, + stopped: wasRunning && stopped, + ...(stopping ? { stopping: true, busy: running } : {}), + clearedStale: cleared, + }), + ); + } else if (!wasRunning) out(cleared ? "not running (cleared stale files)" : "not running"); + else if (stopped) out(`stopped (pid ${pid})`); + else if (running > 0) out(`stopping (pid ${pid}); waiting for ${running} running command(s) to finish`); + else out(`stopping (pid ${pid}); it has not exited yet`); + return 0; + } + ctx.stderr.write(`serve-sim: unknown control verb '${verb}'\n${CONTROL_USAGE}\n`); + return 1; +} diff --git a/packages/serve-sim/src/control-daemon.ts b/packages/serve-sim/src/control-daemon.ts new file mode 100644 index 000000000..db3afe69b --- /dev/null +++ b/packages/serve-sim/src/control-daemon.ts @@ -0,0 +1,596 @@ +/** + * The persistent control process: a Unix-socket server that keeps a small + * pool of pre-warmed workers (see control-worker.ts) and hands each incoming + * command to one of them, relaying its stdout/stderr and exit status back to + * the thin client. It exits after a quiet period, when stopped, when its + * socket is taken over by another daemon, or when the dist it was started + * from is rebuilt. + */ +import { spawn, type ChildProcess } from "child_process"; +import { chmodSync, mkdirSync, renameSync, statSync, unlinkSync, writeFileSync } from "fs"; +import { createConnection, createServer, type Server, type Socket } from "net"; +import { + FORWARDED_SIGNALS, + FRAME_STDERR, + FRAME_STDOUT, + FrameDecoder, + encodeFrame, + encodeJson, + fingerprintMismatch, + isDispatchable, + isStaleBuild, + parseJsonFrame, + parseRunMessage, + unsafeControlDir, + withoutNodeRuntimeEnv, + type ControlFingerprint, + type ControlMessage, + type ControlPaths, + type ControlStatus, + type RunMessage, +} from "./control-protocol"; + +interface ControlDaemonOptions { + paths: ControlPaths; + /** Spawns one warm worker (stdio must include an IPC channel). */ + spawnWorker: () => ChildProcess; + fingerprint: ControlFingerprint; + idleMs: number; + poolSize: number; + /** Ownership/idle check period; defaults to min(1s, idleMs / 4). */ + checkIntervalMs?: number; +} + +interface ControlDaemon { + /** Resolves once the daemon has fully shut down. */ + closed: Promise; + stop: (reason: string) => void; +} + +interface Worker { + child: ChildProcess; + ready: boolean; + /** Last bytes a worker printed while loading, for the fail file. */ + loadOutput: string; +} + +const MAX_SPAWN_FAILURES = 3; +/** How long an accepted caller has to answer `go` before its worker is freed. */ +const GO_TIMEOUT_MS = 10_000; +/** Cap on waiting for replies to flush before the daemon exits. */ +const DRAIN_TIMEOUT_MS = 1000; + +/** Probe a socket path: true only if a control daemon answers a ping. */ +export function pingSocket(socket: string, timeoutMs = 500): Promise { + return new Promise((resolve) => { + const conn = createConnection(socket); + const decoder = new FrameDecoder(); + const done = (status: ControlStatus | null) => { + clearTimeout(timer); + conn.destroy(); + resolve(status); + }; + const timer = setTimeout(() => done(null), timeoutMs); + conn.on("connect", () => conn.write(encodeJson({ t: "ping" }))); + conn.on("data", (chunk) => { + try { + for (const frame of decoder.push(chunk)) { + const msg = parseJsonFrame(frame); + if (msg?.t === "pong") return done(msg.status); + } + } catch { + done(null); + } + }); + conn.on("error", () => done(null)); + conn.on("close", () => done(null)); + }); +} + +function listen(server: Server, socket: string): Promise { + return new Promise((resolve, reject) => { + const onError = (error: Error) => { + server.off("listening", onListening); + reject(error); + }; + const onListening = () => { + server.off("error", onError); + resolve(); + }; + server.once("error", onError); + server.once("listening", onListening); + // Create the socket owner-only from the start: no window before chmod. + const previous = process.umask(0o077); + try { + server.listen(socket); + } finally { + process.umask(previous); + } + }); +} + +/** + * Bind the socket, clearing a stale one left by a dead daemon. Returns false + * when a live daemon already owns it (the caller should just exit). + */ +async function bindExclusive(server: Server, socket: string): Promise { + for (let attempt = 0; attempt < 3; attempt++) { + try { + await listen(server, socket); + return true; + } catch (error) { + if ((error as NodeJS.ErrnoException).code !== "EADDRINUSE") throw error; + if (await pingSocket(socket)) return false; + try { + unlinkSync(socket); + } catch {} + } + } + return false; +} + +function inodeOf(path: string): number | null { + try { + return statSync(path).ino; + } catch { + return null; + } +} + +async function startControlDaemon(opts: ControlDaemonOptions): Promise { + const { socket, pidFile, failFile, dir } = opts.paths; + mkdirSync(dir, { recursive: true, mode: 0o700 }); + // Callers send their whole environment here: refuse a directory that + // someone else owns or can write to. + const unsafe = unsafeControlDir(dir); + if (unsafe) throw new Error(`control dir ${dir} is ${unsafe}`); + const server = createServer(); + if (!(await bindExclusive(server, socket))) { + server.close(); + return null; + } + try { + chmodSync(socket, 0o600); + } catch {} + const socketInode = inodeOf(socket); + const startedAt = Date.now(); + let lastActiveAt = startedAt; + let busy = 0; + let served = 0; + let spawnFailures = 0; + let lastLoadOutput = ""; + let stopping = false; + const pool: Worker[] = []; + const waiting: Array<(worker: Worker | null) => void> = []; + const busyChildren = new Set(); + /** Accepted callers that haven't said `go` yet, and the worker held for each. */ + const held = new Map(); + const holdTimers = new Map>(); + const holdWatchers = new Map void>(); + const connections = new Set(); + let resolveClosed!: () => void; + const closed = new Promise((resolve) => (resolveClosed = resolve)); + + const status = (): ControlStatus => ({ + pid: process.pid, + startedAt, + lastActiveAt, + idleMs: opts.idleMs, + warm: pool.filter((w) => w.ready).length, + warming: pool.filter((w) => !w.ready).length, + busy, + served, + socket, + buffered: [...connections].reduce((n, c) => n + c.writableLength, 0), + }); + + const writeJsonFile = (file: string, value: unknown) => { + const tmp = `${file}.${process.pid}.tmp`; + try { + writeFileSync(tmp, JSON.stringify(value), { mode: 0o600 }); + renameSync(tmp, file); + } catch {} + }; + writeJsonFile(pidFile, { pid: process.pid, socket, startedAt }); + + const ownsSocket = () => socketInode != null && inodeOf(socket) === socketInode; + /** Exited, or its IPC channel is gone; its `close` may not have been handled yet. */ + const isGone = (w: Worker) => w.child.exitCode != null || w.child.signalCode != null || !w.child.connected; + + function spawnWorker(): void { + if (stopping) return; + let child: ChildProcess; + try { + child = opts.spawnWorker(); + } catch (error) { + lastLoadOutput = (error as Error).message; + onSpawnFailure(); + return; + } + const worker: Worker = { child, ready: false, loadOutput: "" }; + pool.push(worker); + // Anything a worker prints before it is assigned is load noise, kept + // only to explain a worker that never becomes ready. + const keep = (chunk: Buffer) => { + if (!worker.ready) worker.loadOutput = (worker.loadOutput + chunk.toString()).slice(-4096); + }; + child.stdout?.on("data", keep); + child.stderr?.on("data", keep); + child.on("message", (msg: { t?: string }) => { + if (msg?.t !== "ready" || worker.ready) return; + worker.ready = true; + worker.loadOutput = ""; + if (spawnFailures > 0 || served === 0) { + try { + unlinkSync(failFile); + } catch {} + } + spawnFailures = 0; + const waiter = waiting.shift(); + if (waiter) { + removeFromPool(worker); + waiter(worker); + refill(); + } + }); + // "close", not "exit": a failed load's output can arrive after exit. + child.on("close", () => { + if (!pool.includes(worker)) return; + removeFromPool(worker); + if (!worker.ready) { + lastLoadOutput = worker.loadOutput; + onSpawnFailure(); + } else refill(); + }); + child.on("error", (error) => { + lastLoadOutput = error.message; + }); + } + + function onSpawnFailure(): void { + spawnFailures++; + if (spawnFailures >= MAX_SPAWN_FAILURES) { + // Workers can't load (broken install?). Tell callers to stop starting + // daemons for this build, and send everyone in-process. + writeJsonFile(failFile, { + at: Date.now(), + binMtimeMs: opts.fingerprint.binMtimeMs, + mainMtimeMs: opts.fingerprint.mainMtimeMs, + reason: lastLoadOutput, + }); + shutdown("workers failing to start"); + return; + } + // Back off a little, then keep the pool warm so the next caller doesn't + // pay for a cold spawn. + setTimeout(refill, 100 * spawnFailures).unref(); + } + + function removeFromPool(worker: Worker): void { + const i = pool.indexOf(worker); + if (i >= 0) pool.splice(i, 1); + } + + function refill(): void { + if (stopping) return; + const want = opts.poolSize + Math.max(0, waiting.length - pool.filter((w) => w.ready).length); + while (pool.length < want) spawnWorker(); + } + + function acquire(): Promise { + if (stopping) return Promise.resolve(null); + // A dead worker stays in the pool until its `close` handler refills. + const ready = pool.find((w) => w.ready && !isGone(w)); + if (ready) { + removeFromPool(ready); + refill(); + return Promise.resolve(ready); + } + return new Promise((resolve) => { + waiting.push(resolve); + refill(); + }); + } + + function release(worker: Worker): void { + // A pristine worker whose caller went away goes back to the pool. + if (stopping || isGone(worker) || pool.length >= opts.poolSize) worker.child.kill("SIGTERM"); + else pool.unshift(worker); + } + + function hold(conn: Socket, worker: Worker, onExit: () => void): void { + held.set(conn, worker); + holdWatchers.set(conn, onExit); + worker.child.once("close", onExit); + } + + /** Stop holding the caller's worker; returns it if it was still held. */ + function unhold(conn: Socket): Worker | undefined { + const worker = held.get(conn); + if (!worker) return undefined; + held.delete(conn); + clearTimeout(holdTimers.get(conn)); + holdTimers.delete(conn); + const onExit = holdWatchers.get(conn); + holdWatchers.delete(conn); + if (onExit) worker.child.off("close", onExit); + return worker; + } + + /** Nothing has run yet: tell the caller to run the command itself. */ + function bypass(conn: Socket, reason: string): void { + if (!conn.destroyed) conn.end(encodeJson({ t: "bypass", reason })); + } + + async function runJob(conn: Socket, msg: RunMessage): Promise { + const mismatch = fingerprintMismatch(opts.fingerprint, msg.fingerprint); + if (mismatch) { + bypass(conn, `fingerprint:${mismatch}`); + if (isStaleBuild(mismatch)) shutdown("dist rebuilt"); + return; + } + // Don't trust the client's filter: only short one-shot commands may + // occupy a worker (and keep the daemon alive). + if (!isDispatchable(msg.argv, msg.cwd)) return bypass(conn, "not dispatchable"); + if (stopping) return bypass(conn, "stopping"); + busy++; + lastActiveAt = Date.now(); + let clientGone = false; + let child: ChildProcess | null = null; + /** Called when the caller goes away, to stop holding back its output. */ + let releaseOutput = () => {}; + conn.on("close", () => { + clientGone = true; + releaseOutput(); + const worker = unhold(conn); + if (worker) { + // Accepted but never told to go: the worker is still pristine. + busy--; + release(worker); + maybeFinishStop(); + } + // The caller died mid-command (e.g. SIGKILL): don't leave it running. + child?.kill("SIGTERM"); + }); + conn.on("error", () => {}); + + // Hold a worker before accepting, so "no worker" is still a bypass. + const worker = await acquire(); + if (!worker || clientGone || stopping || isGone(worker)) { + busy--; + if (worker) release(worker); + if (!clientGone) bypass(conn, !worker ? "no worker available" : stopping ? "stopping" : "worker exited"); + maybeFinishStop(); + return; + } + // Nothing has run yet if the held worker dies before `go` (an outside + // `pkill`, a crash): send the caller in-process rather than leave it, + // and this daemon, waiting on a dead child. + const dropHeld = (reason: string) => { + if (!unhold(conn)) return; + busy--; + release(worker); + bypass(conn, reason); + maybeFinishStop(); + }; + hold(conn, worker, () => dropHeld("worker exited")); + // Freed before any late `go` is honoured, so bypass is still safe. + holdTimers.set(conn, setTimeout(() => dropHeld("go timeout"), GO_TIMEOUT_MS)); + conn.write(encodeJson({ t: "accepted" })); + + jobListeners.set(conn, (m: ControlMessage) => { + if (m.t === "go") { + if (held.get(conn) !== worker) return; + if (isGone(worker)) return dropHeld("worker exited"); + unhold(conn); + start(worker); + } else if (m.t === "signal" && child && FORWARDED_SIGNALS.includes(m.signal)) { + child.kill(m.signal); + } + }); + + function start(w: Worker): void { + const c = w.child; + child = c; + busyChildren.add(c); + served++; + lastActiveAt = Date.now(); + c.stdout?.removeAllListeners("data"); + c.stderr?.removeAllListeners("data"); + // Backpressure: while the caller isn't keeping up (a slow pipe, a + // stopped pager), stop reading the worker's output rather than queue + // it here, where one big command could exhaust the shared daemon. The + // worker's writes are blocking, so it simply waits, as it would on a + // full pipe in a direct run. + const streams = [c.stdout, c.stderr].filter((x) => x != null); + let paused = false; + const resume = () => { + if (!paused) return; + paused = false; + for (const x of streams) x.resume(); + }; + // A caller that left can't drain: discard the rest so the worker + // (killed on close) can finish closing its pipes. + releaseOutput = resume; + conn.on("drain", resume); + const relay = (type: number) => (chunk: Buffer) => { + if (clientGone) return; + if (!conn.write(encodeFrame(type, chunk)) && !paused) { + paused = true; + for (const x of streams) x.pause(); + } + }; + c.stdout?.on("data", relay(FRAME_STDOUT)); + c.stderr?.on("data", relay(FRAME_STDERR)); + // The command never reached the worker (it died just now): the + // caller can still run it itself. + let undelivered = false; + c.removeAllListeners("close"); + c.once("close", (code, signal) => { + busyChildren.delete(c); + busy--; + lastActiveAt = Date.now(); + if (undelivered) { + served--; + bypass(conn, "worker exited"); + } else if (!clientGone) conn.end(encodeJson({ t: "exit", code, signal })); + maybeFinishStop(); + }); + const { t: _t, fingerprint: _fp, ...payload } = msg; // already reduced to known fields + try { + c.send({ t: "run", ...payload }, (error) => { + if (error) undelivered = true; + }); + } catch { + undelivered = true; + } + } + } + + const jobListeners = new WeakMap void>(); + + server.on("connection", (conn) => { + connections.add(conn); + conn.on("close", () => { + connections.delete(conn); + if (stopping) maybeFinishStop(); + }); + const decoder = new FrameDecoder(); + let first = true; + conn.on("error", () => {}); + conn.on("data", (chunk) => { + let frames; + try { + frames = decoder.push(chunk); + } catch { + conn.destroy(); + return; + } + for (const frame of frames) { + const msg = parseJsonFrame(frame); + if (!msg) continue; + if (!first) { + jobListeners.get(conn)?.(msg); + continue; + } + first = false; + if (msg.t === "ping") conn.end(encodeJson({ t: "pong", status: status() })); + else if (msg.t === "stop") { + shutdown("stop requested"); + // What's left after shutdown is commands that are already running + // (queued and held callers were bypassed, though `busy` only + // drops for them a microtask later). + conn.end(encodeJson({ t: "stopping", busy: busyChildren.size + held.size })); + } else if (msg.t === "run") { + const runMsg = parseRunMessage(msg); + if (!runMsg) { + bypass(conn, "malformed run request"); + continue; + } + // Never let one caller's job take the shared daemon down. + runJob(conn, runMsg).catch(() => conn.destroy()); + } else conn.destroy(); + } + }); + }); + + const checkMs = opts.checkIntervalMs ?? Math.max(50, Math.min(1000, Math.floor(opts.idleMs / 4))); + const timer = setInterval(() => { + if (!ownsSocket()) { + // Another daemon replaced our socket (or it was deleted): nobody can + // reach us any more. + shutdown("socket taken over", { unlink: false }); + return; + } + if (busy === 0 && waiting.length === 0 && Date.now() - lastActiveAt >= opts.idleMs) shutdown("idle"); + }, checkMs); + + let unlinkOnExit = true; + let drainTimer: ReturnType | null = null; + function shutdown(_reason: string, o: { unlink?: boolean } = {}): void { + if (o.unlink === false) unlinkOnExit = false; + if (stopping) return; + stopping = true; + clearInterval(timer); + server.close(); + if (unlinkOnExit && ownsSocket()) { + try { + unlinkSync(socket); + } catch {} + } + if (unlinkOnExit) { + try { + unlinkSync(pidFile); + } catch {} + } + // Queued and accepted-but-not-started callers haven't run anything. + for (const waiter of waiting.splice(0)) waiter(null); + for (const conn of [...held.keys()]) { + const worker = unhold(conn)!; + busy--; + worker.child.kill("SIGTERM"); + bypass(conn, "stopping"); + } + for (const w of pool.splice(0)) w.child.kill("SIGTERM"); + maybeFinishStop(); + } + + function maybeFinishStop(): void { + // Running commands finish first; then replies already queued (bypass, + // exit) get a moment to reach their callers before the process exits. + if (!stopping || busy > 0 || busyChildren.size > 0) return; + if (connections.size === 0) { + if (drainTimer) clearTimeout(drainTimer); + resolveClosed(); + return; + } + drainTimer ??= setTimeout(() => { + for (const conn of connections) conn.destroy(); + resolveClosed(); + }, DRAIN_TIMEOUT_MS); + } + + refill(); + return { closed, stop: (reason) => shutdown(reason) }; +} + +/** Entry for `node serve-sim.js __control-daemon`. */ +export async function runControlDaemonProcess(opts: { + binFile: string; + paths: ControlPaths; + fingerprint: ControlFingerprint; + idleMs: number; + poolSize: number; + roleEnv: string; +}): Promise { + // Don't pin whatever directory the first caller happened to be in. + try { + process.chdir("/"); + } catch {} + let daemon: ControlDaemon | null; + try { + daemon = await startControlDaemon({ + paths: opts.paths, + fingerprint: opts.fingerprint, + idleMs: opts.idleMs, + poolSize: opts.poolSize, + spawnWorker: () => + spawn(process.execPath, [opts.binFile], { + cwd: "/", + // The first caller's node flags must not leak into later callers. + env: { ...withoutNodeRuntimeEnv(process.env), [opts.roleEnv]: "worker" }, + stdio: ["ignore", "pipe", "pipe", "ipc"], + }), + }); + } catch (error) { + process.stderr.write(`serve-sim: control process refused to start: ${(error as Error).message}\n`); + process.exit(1); + } + if (!daemon) return; // another daemon already owns the socket + const running = daemon; + process.on("SIGTERM", () => running.stop("SIGTERM")); + process.on("SIGINT", () => running.stop("SIGINT")); + process.on("SIGHUP", () => {}); + await running.closed; + process.exit(0); +} diff --git a/packages/serve-sim/src/control-protocol.ts b/packages/serve-sim/src/control-protocol.ts new file mode 100644 index 000000000..c15ab6cd5 --- /dev/null +++ b/packages/serve-sim/src/control-protocol.ts @@ -0,0 +1,473 @@ +/** + * Shared pieces of the persistent control process: which commands it may + * run, where its socket lives, the wire framing, and the fingerprint that + * decides whether a warm worker matches the caller. + * + * This file is imported by the tiny bin entry (src/bin.ts), so it must only + * pull in node builtins — anything heavier defeats the point. + */ +import { createHash } from "crypto"; +import { lstatSync, readlinkSync, realpathSync, statSync } from "fs"; +import { homedir, tmpdir } from "os"; +import { basename, dirname, isAbsolute, join, resolve } from "path"; + +const CONTROL_PROTOCOL = 2; +/** argv[2] marker for the daemon process (visible in `ps`). */ +export const CONTROL_DAEMON_ARG = "__control-daemon"; +/** Set on pre-warmed worker processes; stripped before the command runs. */ +export const CONTROL_ROLE_ENV = "SERVE_SIM_CONTROL_ROLE"; +/** `0`/`off` disables the control process; `1`/`on` auto-starts even in CI. */ +const CONTROL_ENV = "SERVE_SIM_CONTROL"; +/** Quiet period before the daemon exits on its own (ms). */ +export const CONTROL_IDLE_ENV = "SERVE_SIM_CONTROL_IDLE_MS"; +/** Override the socket/pid directory (tests, unusual TMPDIRs). @lintignore Exported for tests. */ +export const CONTROL_DIR_ENV = "SERVE_SIM_CONTROL_DIR"; +/** How long a caller waits for the daemon to hand it a worker (ms). */ +export const CONTROL_ACCEPT_ENV = "SERVE_SIM_CONTROL_ACCEPT_MS"; +const DEFAULT_ACCEPT_MS = 1000; +const DEFAULT_IDLE_MS = 5 * 60_000; +/** Warm workers kept ready; each is single-use, then replaced. */ +export const DEFAULT_POOL_SIZE = 2; + +/** + * Short, one-shot commands that only talk to a running preview server and + * print a result. Anything that starts servers, injects into apps, records, + * reads stdin or runs an interactive shell keeps running in-process. + */ +const DISPATCHABLE_COMMANDS: ReadonlySet = new Set([ + "tap", + "gesture", + "settle", + "button", + "type", + "paste", + "rotate", + "fold", + "ca-debug", + "memory-warning", + "event-log", + "ax", + "buffer", +]); + +const ROOT_INFO_FLAGS = new Set(["--help", "-h", "--version", "-v"]); + +/** + * Whether `args` (argv after the script) may run in a warm worker. `cwd` is + * the caller's working directory, used to resolve relative `--file` paths. + */ +export function isDispatchable(args: readonly string[], cwd?: string): boolean { + const [first] = args; + if (first == null) return false; // bare `serve-sim` starts the preview server + if (args.length === 1 && ROOT_INFO_FLAGS.has(first)) return true; + if (first === "help") return args.length <= 2; + if (!DISPATCHABLE_COMMANDS.has(first)) return false; + // stdin is not forwarded to workers (nor are its /dev aliases). + if (args.includes("--stdin")) return false; + if (readsDevFile(args, cwd)) return false; + return true; +} + +/** + * `--file /dev/stdin`, `--file=/dev/fd/0` and friends read the caller's fds. + * Relative paths (`../../dev/stdin`) and symlinks into /dev count too. + */ +export function readsDevFile(args: readonly string[], cwd?: string): boolean { + for (let i = 0; i < args.length; i++) { + const a = args[i]!; + const value = a === "--file" ? args[i + 1] : a.startsWith("--file=") ? a.slice("--file=".length) : null; + if (value == null || value === "") continue; + if (!isAbsolute(value) && cwd == null) continue; + if (intoDev(isAbsolute(value) ? resolve(value) : resolve(cwd!, value))) return true; + } + return false; +} + +/** + * Whether `path` lands in /dev/, following symlinks one hop at a time + * (realpath on /dev/stdin itself resolves fd 0, which can fail or vary). + */ +function intoDev(path: string): boolean { + let p = path; + for (let hop = 0; hop < 32; hop++) { + if (isFdPath(p)) return true; + try { + p = join(realpathSync(dirname(p)), basename(p)); + if (isFdPath(p)) return true; + if (!lstatSync(p).isSymbolicLink()) return false; + p = resolve(dirname(p), readlinkSync(p)); + } catch { + return false; + } + } + return false; +} + +/** /dev/... or, on Linux where /dev/fd -> /proc/self/fd, /proc//fd/... */ +function isFdPath(p: string): boolean { + return p.startsWith("/dev/") || /^\/proc\/(?:self|thread-self|\d+)\/fd\//.test(p); +} + +export type ControlMode = "off" | "use" | "auto"; + +/** + * off: never touch the control process. use: dispatch to one that is already + * running but never start one (the default under CI, so jobs don't leave a + * daemon behind). auto: dispatch, and start one in the background if absent. + */ +export function controlMode(env: NodeJS.ProcessEnv): ControlMode { + const raw = env[CONTROL_ENV]?.trim().toLowerCase(); + if (raw === "0" || raw === "false" || raw === "off" || raw === "no") return "off"; + if (raw === "1" || raw === "true" || raw === "on" || raw === "yes") return "auto"; + const ci = env.CI?.trim().toLowerCase(); + if (ci && ci !== "0" && ci !== "false") return "use"; + return "auto"; +} + +export function parseAcceptMs(raw: string | undefined): number { + const n = raw == null || raw.trim() === "" ? NaN : Number(raw); + return Number.isFinite(n) && n > 0 ? Math.floor(n) : DEFAULT_ACCEPT_MS; +} + +/** + * Node runtime settings a warm worker can't adopt after it has started: + * they shape how node itself boots (preloads, inspector, CA store, proxy). + * They are stripped from the daemon and its workers, and a caller that sets + * any of them runs in-process. + */ +const NODE_RUNTIME_ENV = ["NODE_OPTIONS", "NODE_EXTRA_CA_CERTS", "NODE_USE_ENV_PROXY"] as const; + +export function withoutNodeRuntimeEnv(env: NodeJS.ProcessEnv): NodeJS.ProcessEnv { + const out = { ...env }; + for (const key of NODE_RUNTIME_ENV) delete out[key]; + return out; +} + +/** + * Env markers of an OS sandbox around the caller (Codex's seatbelt, Claude + * Code's sandbox runtime). A worker can't enter the caller's sandbox, and a + * daemon started inside one would confine everyone else's commands, so + * these callers run in-process and never start a daemon. + */ +const SANDBOX_ENV = ["CODEX_SANDBOX", "CODEX_SANDBOX_NETWORK_DISABLED", "SANDBOX_RUNTIME"] as const; + +export function sandboxMarker(env: NodeJS.ProcessEnv): string | null { + for (const key of SANDBOX_ENV) if (env[key]) return key; + return null; +} + +/** The first runtime setting the caller has that a worker can't honor. */ +export function nodeRuntimeOverride(env: NodeJS.ProcessEnv, execArgv: readonly string[]): string | null { + for (const key of NODE_RUNTIME_ENV) if (env[key]) return key; + return execArgv.length > 0 ? "execArgv" : null; +} + +export function parseIdleMs(raw: string | undefined): number { + if (raw == null || raw.trim() === "") return DEFAULT_IDLE_MS; + const n = Number(raw); + return Number.isFinite(n) && n >= 100 ? Math.floor(n) : DEFAULT_IDLE_MS; +} + +export interface ControlPaths { + dir: string; + socket: string; + pidFile: string; + /** Written when workers can't load, so callers stop respawning a daemon. */ + failFile: string; +} + +/** + * One daemon per (bin file, node binary, HOME): different installs or node + * versions never share warm workers. + */ +export function controlPaths(opts: { + binFile: string; + execPath: string; + env: NodeJS.ProcessEnv; +}): ControlPaths { + // Per-uid so another user on a shared /tmp can't pre-create the directory. + const uid = typeof process.getuid === "function" ? process.getuid() : null; + const dir = opts.env[CONTROL_DIR_ENV] || join(tmpdir(), uid == null ? "serve-sim-control" : `serve-sim-control-${uid}`); + const id = createHash("sha256") + .update(`${opts.binFile}\0${opts.execPath}\0${opts.env.HOME ?? homedir()}`) + .digest("hex") + .slice(0, 12); + return { + dir, + socket: join(dir, `control-${id}.sock`), + pidFile: join(dir, `control-${id}.json`), + failFile: join(dir, `control-${id}.failed`), + }; +} + +/** sun_path is 104 bytes on macOS, including the terminating NUL. */ +export const MAX_SOCKET_PATH_BYTES = 103; + +function currentUid(): number | null { + return typeof process.getuid === "function" ? process.getuid() : null; +} + +/** + * Why `dir` can't hold the control socket, or null if it is a real + * directory owned by us that nobody else can write to. The client sends its + * whole environment over the socket, so it must be ours. + */ +export function unsafeControlDir(dir: string): string | null { + let st; + try { + st = lstatSync(dir); + } catch (error) { + return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unreadable"; + } + if (st.isSymbolicLink()) return "symlink"; + if (!st.isDirectory()) return "not a directory"; + const uid = currentUid(); + if (uid != null && st.uid !== uid) return `owned by uid ${st.uid}`; + if ((st.mode & 0o077) !== 0) return `mode ${(st.mode & 0o777).toString(8)} is group/other accessible`; + return null; +} + +/** Why `socket` isn't a socket we own ("missing" when absent), or null. */ +export function unsafeControlSocket(socket: string): string | null { + let st; + try { + st = lstatSync(socket); + } catch (error) { + return (error as NodeJS.ErrnoException).code === "ENOENT" ? "missing" : "unreadable"; + } + if (st.isSymbolicLink()) return "symlink"; + if (!st.isSocket()) return "not a socket"; + const uid = currentUid(); + if (uid != null && st.uid !== uid) return `owned by uid ${st.uid}`; + return null; +} + +/** + * What a warm worker baked in at load time. The main bundle reads HOME and + * TMPDIR into module constants and `debug` reads DEBUG on import, so a caller + * whose values differ must run in-process. The mtimes catch a rebuilt dist + * under a still-running daemon. + */ +export interface ControlFingerprint { + protocol: number; + execPath: string; + home: string; + tmpdir: string; + debug: string; + binMtimeMs: number; + mainMtimeMs: number; +} + +function mtimeMs(file: string): number { + try { + return statSync(file).mtimeMs; + } catch { + return -1; + } +} + +export function controlFingerprint(opts: { + binFile: string; + mainFile: string; + execPath: string; + env: NodeJS.ProcessEnv; +}): ControlFingerprint { + return { + protocol: CONTROL_PROTOCOL, + execPath: opts.execPath, + home: opts.env.HOME ?? "", + tmpdir: opts.env.TMPDIR ?? "", + debug: opts.env.DEBUG ?? "", + binMtimeMs: mtimeMs(opts.binFile), + mainMtimeMs: mtimeMs(opts.mainFile), + }; +} + +/** First differing field, or null when the worker matches the caller. */ +export function fingerprintMismatch( + daemon: ControlFingerprint, + caller: ControlFingerprint, +): keyof ControlFingerprint | null { + for (const key of Object.keys(daemon) as (keyof ControlFingerprint)[]) { + if (daemon[key] !== caller[key]) return key; + } + return null; +} + +/** A rebuilt dist means the daemon itself is stale and should go away. */ +export function isStaleBuild(field: keyof ControlFingerprint | null): boolean { + return field === "binMtimeMs" || field === "mainMtimeMs" || field === "protocol"; +} + +// ─── Wire framing ──────────────────────────────────────────────────────── +// [type u8][length u32 BE][payload]. JSON frames carry control messages; +// stdout/stderr frames carry raw command output bytes. + +/** @lintignore Exported for tests. */ +export const FRAME_JSON = 0x4a; // J +export const FRAME_STDOUT = 0x4f; // O +export const FRAME_STDERR = 0x45; // E +const MAX_FRAME_BYTES = 64 * 1024 * 1024; + +export function encodeFrame(type: number, payload: Buffer | string): Buffer { + const body = typeof payload === "string" ? Buffer.from(payload) : payload; + const header = Buffer.allocUnsafe(5); + header.writeUInt8(type, 0); + header.writeUInt32BE(body.length, 1); + return Buffer.concat([header, body]); +} + +export function encodeJson(message: ControlMessage): Buffer { + return encodeFrame(FRAME_JSON, JSON.stringify(message)); +} + +export interface Frame { + type: number; + payload: Buffer; +} + +export class FrameDecoder { + private buffer: Buffer = Buffer.alloc(0); + + push(chunk: Buffer | string): Frame[] { + const bytes = typeof chunk === "string" ? Buffer.from(chunk) : chunk; + this.buffer = this.buffer.length === 0 ? bytes : Buffer.concat([this.buffer, bytes]); + const frames: Frame[] = []; + while (this.buffer.length >= 5) { + const length = this.buffer.readUInt32BE(1); + if (length > MAX_FRAME_BYTES) throw new Error(`control frame too large (${length} bytes)`); + if (this.buffer.length < 5 + length) break; + frames.push({ + type: this.buffer.readUInt8(0), + payload: this.buffer.subarray(5, 5 + length), + }); + this.buffer = this.buffer.subarray(5 + length); + } + return frames; + } +} + +export interface StreamTty { + isTTY: boolean; + columns?: number; +} + +export const FORWARDED_SIGNALS = ["SIGINT", "SIGTERM", "SIGHUP"] as const; +export type ForwardedSignal = (typeof FORWARDED_SIGNALS)[number]; + +export type ControlMessage = + | { + t: "run"; + fingerprint: ControlFingerprint; + argv: string[]; + cwd: string; + env: Record; + tty: { stdout: StreamTty; stderr: StreamTty }; + /** The caller's stdout and stderr are the same file (e.g. `2>&1`). */ + sharedOutput?: boolean; + /** The caller's umask, so files the command writes get its modes. */ + umask?: number; + } + // Two-phase start: the daemon replies `accepted` once it holds a worker + // for the caller, and only hands it the command after the caller's `go`. + | { t: "go" } + | { t: "signal"; signal: ForwardedSignal } + | { t: "ping" } + | { t: "stop" } + | { t: "accepted" } + | { t: "bypass"; reason: string } + | { t: "exit"; code: number | null; signal: string | null } + | { t: "pong"; status: ControlStatus } + /** `busy`: commands still running; the daemon exits once they finish. */ + | { t: "stopping"; busy?: number }; + +export interface ControlStatus { + pid: number; + startedAt: number; + lastActiveAt: number; + idleMs: number; + warm: number; + warming: number; + busy: number; + served: number; + socket: string; + /** Command output queued for callers that aren't reading it yet. */ + buffered?: number; +} + +export function parseJsonFrame(frame: Frame): ControlMessage | null { + if (frame.type !== FRAME_JSON) return null; + try { + const value = JSON.parse(frame.payload.toString("utf8")) as ControlMessage; + return value && typeof value === "object" && typeof value.t === "string" ? value : null; + } catch { + return null; + } +} + +export type RunMessage = Extract; + +const isObject = (v: unknown): v is Record => typeof v === "object" && v !== null && !Array.isArray(v); +const isStreamTty = (v: unknown): v is StreamTty => + isObject(v) && typeof v.isTTY === "boolean" && (v.columns === undefined || typeof v.columns === "number"); + +const FINGERPRINT_TYPES: Record = { + protocol: "number", + execPath: "string", + home: "string", + tmpdir: "string", + debug: "string", + binMtimeMs: "number", + mainMtimeMs: "number", +}; +const isFingerprint = (v: unknown): v is ControlFingerprint => + isObject(v) && Object.entries(FINGERPRINT_TYPES).every(([k, type]) => typeof v[k] === type); + +/** + * A well-formed `run` request, rebuilt from only the fields the protocol + * defines; null for anything else. The daemon must not trust its callers' + * JSON: a missing field would otherwise throw deep inside the job. + */ +export function parseRunMessage(msg: ControlMessage): RunMessage | null { + const m = msg as unknown as Record; + if (m.t !== "run") return null; + const { fingerprint, argv, cwd, env, tty, sharedOutput, umask } = m; + if (!isFingerprint(fingerprint)) return null; + if (!Array.isArray(argv) || !argv.every((a) => typeof a === "string")) return null; + if (typeof cwd !== "string") return null; + if (!isObject(env) || !Object.values(env).every((v) => typeof v === "string")) return null; + if (!isObject(tty) || !isStreamTty(tty.stdout) || !isStreamTty(tty.stderr)) return null; + if (sharedOutput !== undefined && typeof sharedOutput !== "boolean") return null; + if (umask !== undefined && (typeof umask !== "number" || !Number.isInteger(umask) || umask < 0 || umask > 0o777)) return null; + return { + t: "run", + fingerprint, + argv: argv as string[], + cwd, + env: env as Record, + tty: { stdout: tty.stdout, stderr: tty.stderr }, + ...(sharedOutput !== undefined ? { sharedOutput } : {}), + ...(umask !== undefined ? { umask } : {}), + }; +} + +// ─── Deferred main ─────────────────────────────────────────────────────── +// A warm worker imports the full CLI bundle ahead of time; the bundle hands +// its entry point back instead of parsing argv right away. + +const DEFER_KEY = Symbol.for("serve-sim.control.defer-main"); +type DeferredMain = () => Promise; + +/** Called by the CLI bundle in place of `await main()`. */ +export async function runCliMain(main: DeferredMain): Promise { + const hook = (globalThis as Record)[DEFER_KEY]; + if (typeof hook === "function") { + (hook as (main: DeferredMain) => void)(main); + return; + } + await main(); +} + +export function deferCliMain(capture: (main: DeferredMain) => void): void { + (globalThis as Record)[DEFER_KEY] = capture; +} diff --git a/packages/serve-sim/src/control-worker.ts b/packages/serve-sim/src/control-worker.ts new file mode 100644 index 000000000..a54486fd9 --- /dev/null +++ b/packages/serve-sim/src/control-worker.ts @@ -0,0 +1,96 @@ +/** + * A pre-warmed, single-use worker. It loads the full CLI bundle ahead of time + * (that load is most of a cold `serve-sim` call), tells the daemon it is + * ready, then waits for one command: it adopts the caller's argv, cwd, env, + * umask and TTY shape, runs the CLI exactly as the normal bin would, and exits. + * + * Because every command still gets its own process, `process.exit`, exit + * codes, signal handlers and module state behave as in a direct run. + */ +import { CONTROL_ROLE_ENV, deferCliMain, type ControlMessage, type RunMessage, type StreamTty } from "./control-protocol"; + +function adoptTty(stream: NodeJS.WriteStream, tty: StreamTty | undefined): void { + if (!tty?.isTTY) return; + // Help wrapping and a couple of commands key off these; the stream itself + // is a pipe to the daemon, so don't fake any TTY methods. + Object.defineProperty(stream, "isTTY", { value: true, configurable: true }); + if (tty.columns != null) Object.defineProperty(stream, "columns", { value: tty.columns, configurable: true }); +} + +interface PipeHandle { + setBlocking?: (blocking: boolean) => void; +} + +/** + * Make writes to the daemon pipe synchronous, as they are for a file or TTY + * in a direct run, so `write(big); process.exit()` doesn't lose output. + */ +function blockingWrites(stream: NodeJS.WriteStream): void { + (stream as unknown as { _handle?: PipeHandle })._handle?.setBlocking?.(true); +} + +/** @lintignore Exported for tests. */ +export function adoptCaller(message: RunMessage, proc: NodeJS.Process = process): void { + proc.chdir(message.cwd); + if (typeof message.umask === "number") proc.umask(message.umask); + for (const key of Object.keys(proc.env)) { + if (!(key in message.env)) delete proc.env[key]; + } + Object.assign(proc.env, message.env); + proc.argv.splice(2, proc.argv.length - 2, ...message.argv); + adoptTty(proc.stdout, message.tty.stdout); + adoptTty(proc.stderr, message.tty.stderr); + blockingWrites(proc.stdout); + blockingWrites(proc.stderr); + if (message.sharedOutput) { + // The caller's stdout and stderr are one file (`2>&1`): send both down + // one pipe so the daemon can't reorder them. Writes from child + // processes that inherit fd 2 still travel separately. + const stdout = proc.stdout; + proc.stderr.write = ((...args: Parameters) => + stdout.write(...args)) as NodeJS.WriteStream["write"]; + } +} + +export async function runControlWorker(mainUrl: string): Promise { + delete process.env[CONTROL_ROLE_ENV]; + const send = process.send?.bind(process); + if (!send) { + console.error("serve-sim: control worker needs an IPC channel"); + process.exit(70); + } + // While idle, follow the daemon down. + const onDisconnect = () => process.exit(0); + process.on("disconnect", onDisconnect); + + let main: (() => Promise) | null = null; + deferCliMain((m) => { + main = m; + }); + await import(mainUrl); + const run = main as (() => Promise) | null; + if (!run) { + console.error("serve-sim: CLI bundle did not hand back its entry point"); + process.exit(70); + } + + process.once("message", (message: ControlMessage) => { + if (message?.t !== "run") process.exit(70); + try { + adoptCaller(message); + } catch (error) { + console.error(`serve-sim: ${(error as Error).message}`); + process.exit(1); + } + // Drop the IPC channel so the event loop drains like a normal run. + process.off("disconnect", onDisconnect); + process.disconnect?.(); + run().catch((error) => { + // Same as an uncaught top-level await rejection: stack on stderr, exit 1. + setImmediate(() => { + throw error; + }); + }); + }); + send({ t: "ready" }); +} diff --git a/packages/serve-sim/src/index.ts b/packages/serve-sim/src/index.ts index 6ce5013a1..655efc9c2 100755 --- a/packages/serve-sim/src/index.ts +++ b/packages/serve-sim/src/index.ts @@ -107,6 +107,7 @@ import { import { redactHome } from "./diagnostics-redact"; import { BUFFER_VERBS, runBufferCommand, startBufferOnReusedServer, type BufferCliOptions, type BufferVerb } from "./buffer-cli"; import { ROLLING_BUFFER_ENV, parseRollingBufferEnv } from "./rolling-buffer"; +import { runCliMain } from "./control-protocol"; // `import.meta.dir` is Bun-only; resolve once via fileURLToPath so the bundled // CLI works under plain `node` too. @@ -2974,6 +2975,19 @@ program .argument("[args...]") .action((args: string[]) => uiSettings(args)); +// Handled by the node bin (src/bin.ts) before this bundle loads; registered +// here so it shows in --help and explains itself in other builds. +program + .command("control") + .description("Persistent control process that keeps short commands fast (status|start|stop)") + .allowUnknownOption(true) + .helpOption(false) + .argument("[args...]") + .action(() => { + console.error("serve-sim: the control process is only available from the node bin (dist/serve-sim.js)."); + process.exit(1); + }); + // Settle the device set before any command runs. Commander matches the root // --device-set after a subcommand's name too. program.hook("preAction", () => { @@ -2984,4 +2998,4 @@ program.hook("preAction", () => { process.exit(1); } }); -await program.parseAsync(process.argv); +await runCliMain(() => program.parseAsync(process.argv));