pi-browser-harness 0.10.2 → 0.11.0

package/src/daemon/protocol.ts

@@ -1,32 +1,15 @@
-/**
- * Unix socket daemon protocol — wire message types, type guards, and constants.
- *
- * The daemon speaks JSON-line protocol over a Unix domain socket.
- * One JSON object per newline. Four message types: request, response, event, control.
- *
- * References:
- *   - CDP message format: https://github.com/aslushnikov/getting-started-with-cdp#protocol-fundamentals
- *   - net.createServer IPC: https://nodejs.org/docs/latest-v22.x/api/net.html#serverlistenpath-backlog-callback
- *   - readline line-delimited: https://nodejs.org/docs/latest-v22.x/api/readline.html#event-line
- */
+import { isRecord } from "../util/guards";
 
-// ── Message types ──────────────────────────────────────────────────────────────
-
-/** A CDP command sent from a pi client to the daemon. */
 export type WireRequest = {
   readonly type: "request";
-  /** Client-local CDP id. The daemon remaps this to a globally-unique id for Chrome. */
   readonly id: number;
   readonly method: string;
   readonly params?: Record<string, unknown>;
-  /** Optional CDP session id. Omitted for browser-level commands. */
   readonly sessionId?: string;
 };
 
-/** A CDP response (result or error) sent from the daemon back to the pi client. */
 export type WireResponse = {
   readonly type: "response";
-  /** Matches the id from the corresponding WireRequest. */
   readonly id: number;
   readonly result?: unknown;
   readonly error?: {
@@ -36,39 +19,24 @@ export type WireResponse = {
   };
 };
 
-/** A CDP event forwarded from Chrome through the daemon to pi client(s). */
 export type WireEvent = {
   readonly type: "event";
   readonly method: string;
   readonly params?: Record<string, unknown>;
-  /** Session-scoped events carry this; browser-level events omit it. */
   readonly sessionId?: string;
 };
 
-/** Daemon lifecycle control messages. Bidirectional. */
 export type WireControl = {
   readonly type: "control";
   readonly action: "register" | "registered" | "deregister" | "shutdown";
-  /** pi client namespace (required for register/registered/deregister). */
   readonly clientId?: string;
-  /** Human-readable reason for shutdown. */
   readonly reason?: string;
 };
 
-/** All messages that may appear on the Unix socket. */
 export type WireMessage = WireRequest | WireResponse | WireEvent | WireControl;
 
-// ── Type guard ─────────────────────────────────────────────────────────────────
-
-const isObject = (v: unknown): v is Readonly<Record<string, unknown>> =>
-  typeof v === "object" && v !== null && !Array.isArray(v);
-
-/**
- * Validates that an unknown parsed-JSON value is a well-formed WireMessage.
- * Does NOT validate the full CDP semantics — only structural shape.
- */
-export const isWireMessage = (v: unknown): v is WireMessage => {
-  if (!isObject(v)) return false;
+const isWireMessage = (v: unknown): v is WireMessage => {
+  if (!isRecord(v)) return false;
   const t = v["type"];
   if (typeof t !== "string") return false;
 
@@ -84,7 +52,7 @@ export const isWireMessage = (v: unknown): v is WireMessage => {
       if (typeof v["id"] !== "number") return false;
       const errVal = v["error"];
       if (errVal !== undefined) {
-        if (!isObject(errVal)) return false;
+        if (!isRecord(errVal)) return false;
         if (typeof errVal["message"] !== "string") return false;
         if (typeof errVal["code"] !== "number") return false;
       }
@@ -114,12 +82,8 @@ export const isWireMessage = (v: unknown): v is WireMessage => {
   }
 };
 
-// ── Wire message constructors ──────────────────────────────────────────────────
-
-/** Serialize a WireMessage to a JSON line (no trailing newline — caller adds \\n). */
 export const serialize = (msg: WireMessage): string => JSON.stringify(msg);
 
-/** Deserialize a single JSON-line string to a WireMessage. Returns null on parse failure. */
 export const deserialize = (line: string): WireMessage | null => {
   let parsed: unknown;
   try {
@@ -131,42 +95,16 @@ export const deserialize = (line: string): WireMessage | null => {
   return parsed;
 };
 
-// ── Constants ──────────────────────────────────────────────────────────────────
-
-/**
- * IPC endpoint for the daemon.
- *
- * On POSIX platforms this is a Unix domain socket path. On Windows, Node's IPC
- * requires a named pipe of the form `\\.\pipe\<name>` — a Unix path like
- * `/tmp/…` is not a valid `net` listen/connect target there and causes setup
- * to fail. See https://nodejs.org/api/net.html#ipc-support.
- */
+// Windows requires a named pipe (`\\.\pipe\<name>`); a Unix path is not a valid `net` listen/connect target there.
 export const DAEMON_SOCKET_PATH =
   process.platform === "win32"
     ? "\\\\.\\pipe\\pi-browser-daemon"
     : "/tmp/pi-browser-daemon.sock";
 
-/**
- * How long the daemon stays alive with zero connected clients before exiting
- * (milliseconds). After this period, the daemon cleans up and shuts down.
- */
-export const DAEMON_IDLE_TIMEOUT_MS = 30 * 60 * 1000; // 30 minutes
+export const DAEMON_IDLE_TIMEOUT_MS = 30 * 60 * 1000;
 
-/**
- * Hard cap on concurrent pi client connections. Extra connections are rejected
- * immediately to prevent resource exhaustion.
- */
 export const DAEMON_MAX_CLIENTS = 16;
 
-/**
- * If true, the daemon unlinks (deletes) any stale socket file from a previous
- * daemon crash before calling server.listen(). Without this, a crashed daemon
- * leaves a socket inode that blocks the next listen() call with EADDRINUSE.
- */
-export const DAEMON_STALE_SOCKET_CLEANUP = true;
-
-/** CDP WebSocket connection timeout (ms). */
 export const CDP_CONNECT_TIMEOUT_MS = 10_000;
 
-/** CDP command timeout when proxying through daemon (ms). */
 export const CDP_COMMAND_TIMEOUT_MS = 10_000;

package/src/daemon/queue.ts

@@ -0,0 +1,85 @@
+import { type Result, err } from "../util/result";
+import { type CdpError, cdpError } from "../cdp/errors";
+import type { CdpEvent } from "../cdp/types";
+
+export type EventQueue = {
+  readonly push: (e: CdpEvent) => void;
+  readonly end: () => void;
+  readonly iter: AsyncIterable<CdpEvent>;
+};
+
+export const makeEventQueue = (): EventQueue => {
+  const buf: CdpEvent[] = [];
+  const waiters: Array<(v: IteratorResult<CdpEvent, undefined>) => void> = [];
+  let ended = false;
+  return {
+    push(e) {
+      if (ended) return;
+      const w = waiters.shift();
+      if (w) w({ value: e, done: false });
+      else buf.push(e);
+    },
+    end() {
+      ended = true;
+      for (const w of waiters.splice(0)) w({ value: undefined, done: true });
+    },
+    iter: {
+      [Symbol.asyncIterator](): AsyncIterator<CdpEvent, undefined, undefined> {
+        return {
+          next: (): Promise<IteratorResult<CdpEvent, undefined>> =>
+            new Promise((resolve) => {
+              const next = buf.shift();
+              if (next) resolve({ value: next, done: false });
+              else if (ended) resolve({ value: undefined, done: true });
+              else waiters.push(resolve);
+            }),
+        };
+      },
+    },
+  };
+};
+
+export type CdpResult = Result<unknown, CdpError>;
+
+export type Pending = {
+  readonly resolve: (v: Result<unknown, CdpError>) => void;
+  readonly timer: ReturnType<typeof setTimeout>;
+  readonly method: string;
+};
+
+export const rejectAllPending = (pending: Map<number, Pending>, reason: string): void => {
+  for (const [, p] of pending) {
+    clearTimeout(p.timer);
+    p.resolve(err(cdpError("transport_closed", reason, p.method)));
+  }
+  pending.clear();
+};
+
+export const sendWithTimeout = (
+  pending: Map<number, Pending>,
+  id: number,
+  method: string,
+  timeoutMs: number,
+  timeoutLabel: string,
+  send: () => void,
+): Promise<CdpResult> =>
+  new Promise((resolve) => {
+    const timer = setTimeout(() => {
+      pending.delete(id);
+      resolve(err(cdpError("timeout", `${timeoutLabel} timeout after ${timeoutMs}ms: ${method}`, method)));
+    }, timeoutMs);
+    pending.set(id, { resolve, timer, method });
+    try {
+      send();
+    } catch (e) {
+      clearTimeout(timer);
+      pending.delete(id);
+      resolve(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e), method)));
+    }
+  });
+
+export const makeOnClose = (closeListeners: Set<() => void>) =>
+  (cb: () => void): (() => void) => {
+    closeListeners.add(cb);
+    return () => closeListeners.delete(cb);
+  };

package/src/daemon/server.ts

@@ -1,76 +1,40 @@
-/**
- * IpcServer — Unix socket server for daemon ↔ pi client communication.
- *
- * Accepts multiple concurrent pi client connections over a Unix domain
- * stream socket. Uses newline-delimited JSON framing (one WireMessage per
- * line). Clients are anonymous until they send a control.register message.
- *
- * References:
- *   - net.createServer: https://nodejs.org/docs/latest-v22.x/api/net.html#netcreateserveroptions-connectionlistener
- *   - server.listen(path): https://nodejs.org/docs/latest-v22.x/api/net.html#serverlistenpath-backlog-callback
- *   - readline.createInterface: https://nodejs.org/docs/latest-v22.x/api/readline.html#readlinecreateinterfaceoptions
- */
-
 import { createServer, type Server, type Socket } from "node:net";
 import { createInterface, type Interface } from "node:readline";
 import { unlinkSync } from "node:fs";
 import {
   type WireMessage,
   type WireControl,
-  isWireMessage,
+  deserialize,
+  serialize,
   DAEMON_SOCKET_PATH,
   DAEMON_MAX_CLIENTS,
-  DAEMON_STALE_SOCKET_CLEANUP,
 } from "./protocol";
 
-// ── Types ──────────────────────────────────────────────────────────────────────
-
-/** A connected pi client with its socket and readline interface. */
 export type ClientSocket = {
-  /** Client namespace (set after registration). */
   id: string;
   readonly socket: Socket;
   readonly rl: Interface;
-  /** True once a valid control.register message has been received. */
   registered: boolean;
 };
 
-/** Handler called for every valid WireMessage from any client. */
 export type MessageHandler = (msg: WireMessage, client: ClientSocket) => void;
 
-/** Handler called when a client connects or disconnects. */
 export type ConnectionHandler = (client: ClientSocket) => void;
 
 export type IpcServer = {
-  /** Start listening on the Unix socket. Resolves when the server is ready. */
   start(): Promise<void>;
-  /** Close the server and all client connections. Resolves when cleaned up. */
   stop(): Promise<void>;
-  /** Register a handler for incoming WireMessages from any client. */
   onMessage(handler: MessageHandler): void;
-  /** Register a handler for client connect events. */
   onConnect(handler: ConnectionHandler): void;
-  /** Register a handler for client disconnect events. */
   onDisconnect(handler: ConnectionHandler): void;
-  /** Send a WireMessage to a specific client by clientId. No-op if client not found. */
   send(clientId: string, msg: WireMessage): void;
-  /** Send a WireMessage to all connected (registered) clients. */
   broadcast(msg: WireMessage): void;
-  /** Force-disconnect a client by clientId. */
-  disconnectClient(clientId: string): void;
-  /** All currently connected clients (by clientId). */
-  clients(): ReadonlyMap<string, ClientSocket>;
-  /** Number of connected clients. */
   clientCount(): number;
 };
 
-// ── Implementation ─────────────────────────────────────────────────────────────
-
 export const createIpcServer = (): IpcServer => {
   let server: Server | null = null;
-  // Anonymous temp-id → ClientSocket. Temp ids are assigned before registration.
   const sockets = new Map<string, ClientSocket>();
-  // clientId → ClientSocket (only registered clients).
   const clients = new Map<string, ClientSocket>();
   let messageHandler: MessageHandler | null = null;
   let connectHandler: ConnectionHandler | null = null;
@@ -79,17 +43,11 @@ export const createIpcServer = (): IpcServer => {
 
   const start = (): Promise<void> =>
     new Promise((resolve, reject) => {
-      // Clean up stale socket file from a previous crashed daemon.
-      if (DAEMON_STALE_SOCKET_CLEANUP) {
-        try {
-          unlinkSync(DAEMON_SOCKET_PATH);
-        } catch {
-          // ENOENT is expected — no stale socket to clean.
-        }
-      }
+      try {
+        unlinkSync(DAEMON_SOCKET_PATH);
+      } catch {}
 
       server = createServer({ pauseOnConnect: false }, (socket: Socket) => {
-        // Reject if at capacity (check registered clients only).
         if (clients.size >= DAEMON_MAX_CLIENTS) {
           socket.destroy();
           return;
@@ -101,77 +59,54 @@ export const createIpcServer = (): IpcServer => {
 
         sockets.set(tempId, currentClient);
 
-        // Buffer for partial lines. readline handles line splitting, but
-        // we store a reference in case we need it for diagnostics.
-        let lineCount = 0;
-
         rl.on("line", (line: string) => {
-          lineCount++;
-          let msg: WireMessage | null;
-          try {
-            const parsed: unknown = JSON.parse(line);
-            if (!isWireMessage(parsed)) return;
-            msg = parsed;
-          } catch {
-            // Malformed JSON — ignore silently, don't crash the daemon.
-            return;
-          }
+          const msg = deserialize(line);
+          if (!msg) return;
 
-          // Handle registration before forwarding to the general handler.
           if (msg.type === "control" && msg.action === "register" && !currentClient.registered) {
             const clientId = msg.clientId;
             if (!clientId) return;
 
-            // If a client with this id is already connected, reject.
             if (clients.has(clientId)) {
               const reply: WireControl = {
                 type: "control",
                 action: "shutdown",
                 reason: `clientId ${clientId} is already connected`,
               };
-              socket.write(JSON.stringify(reply) + "\n");
+              socket.write(serialize(reply) + "\n");
               socket.destroy();
               return;
             }
 
-            // Promote from anonymous to registered — mutate in place so the
-            // closure captures the updated client reference.
+            // Mutate in place so the already-captured closure sees the promoted client.
             sockets.delete(tempId);
             currentClient.id = clientId;
             currentClient.registered = true;
             clients.set(clientId, currentClient);
 
-            // Acknowledge registration.
             const ack: WireControl = { type: "control", action: "registered", clientId };
-            socket.write(JSON.stringify(ack) + "\n");
+            socket.write(serialize(ack) + "\n");
 
             connectHandler?.(currentClient);
             return;
           }
 
-          // Require registration for non-control messages.
           if (!currentClient.registered) return;
 
-          // Forward to the general handler.
           messageHandler?.(msg, currentClient);
         });
 
-        socket.on("error", () => {
-          // Socket errors (ECONNRESET, etc.) are handled by the 'close' event.
-        });
+        socket.on("error", () => {});
 
         socket.on("close", () => {
-          // Clean up whichever map the client is in.
           const found = clients.get(currentClient.id) ?? sockets.get(tempId);
           if (found) {
             clients.delete(found.id);
             sockets.delete(tempId);
-            // Notify if this was a registered client.
             if (found.registered) {
               disconnectHandler?.(found);
             }
           }
-          // Clean up readline to prevent memory leaks.
           rl.close();
         });
       });
@@ -187,20 +122,18 @@ export const createIpcServer = (): IpcServer => {
 
   const stop = (): Promise<void> =>
     new Promise((resolve) => {
-      // Close all client sockets.
       for (const [, client] of clients) {
-        try { client.socket.destroy(); } catch { /* best-effort */ }
+        try { client.socket.destroy(); } catch {}
       }
       for (const [, client] of sockets) {
-        try { client.socket.destroy(); } catch { /* best-effort */ }
+        try { client.socket.destroy(); } catch {}
       }
       clients.clear();
       sockets.clear();
 
       if (server) {
         server.close(() => {
-          // Clean up the socket file.
-          try { unlinkSync(DAEMON_SOCKET_PATH); } catch { /* ENOENT ok */ }
+          try { unlinkSync(DAEMON_SOCKET_PATH); } catch {}
           resolve();
         });
       } else {
@@ -208,6 +141,14 @@ export const createIpcServer = (): IpcServer => {
       }
     });
 
+  const send = (clientId: string, msg: WireMessage): void => {
+    const client = clients.get(clientId);
+    if (!client) return;
+    try {
+      client.socket.write(serialize(msg) + "\n");
+    } catch {}
+  };
+
   return {
     start,
     stop,
@@ -220,26 +161,10 @@ export const createIpcServer = (): IpcServer => {
     onDisconnect(handler) {
       disconnectHandler = handler;
     },
-    send(clientId, msg) {
-      const client = clients.get(clientId);
-      if (!client) return;
-      try {
-        client.socket.write(JSON.stringify(msg) + "\n");
-      } catch {
-        // Socket write error — the close handler will clean up.
-      }
-    },
+    send,
     broadcast(msg) {
-      for (const [clientId] of clients) {
-        this.send(clientId, msg);
-      }
-    },
-    disconnectClient(clientId) {
-      const client = clients.get(clientId);
-      if (!client) return;
-      client.socket.destroy();
+      for (const [clientId] of clients) send(clientId, msg);
     },
-    clients: (): ReadonlyMap<string, ClientSocket> => clients,
     clientCount: (): number => clients.size,
   };
 };

package/src/daemon/spawn.ts

@@ -1,14 +1,3 @@
-/**
- * Daemon lifecycle helpers — spawn detection and lazy launch.
- *
- * The daemon is a standalone long-lived process that owns the single WebSocket
- * to Chrome. pi instances connect to it via a Unix domain socket. This module
- * provides the plumbing to detect a running daemon and spawn one if needed.
- *
- * Reference:
- *   - child_process.spawn detached: https://nodejs.org/docs/latest-v22.x/api/child_process.html#optionsdetached
- */
-
 import { spawn, type ChildProcess } from "node:child_process";
 import { access, unlink } from "node:fs/promises";
 import { existsSync } from "node:fs";
@@ -21,34 +10,27 @@ const moduleDir = dirname(fileURLToPath(import.meta.url));
 
 const isWindows = process.platform === "win32";
 
-/**
- * Remove a stale POSIX socket file. On Windows the daemon endpoint is a named
- * pipe, which is not a filesystem entry and is torn down automatically when the
- * owning process exits — so there is nothing to unlink, and calling unlink on a
- * pipe path throws. This is a no-op on Windows.
- */
+// No-op on Windows: a named pipe is not a filesystem entry and unlinking a pipe path throws.
 const cleanupStaleSocket = (): void => {
   if (isWindows) return;
   unlink(DAEMON_SOCKET_PATH).catch(() => {});
 };
 
-/**
- * Check whether the daemon is running by probing its Unix socket.
- * A file-existence check is unreliable — a crashed daemon leaves a stale socket.
- * We connect, send a register, wait for the registered ack, then disconnect.
- * On failure, clean up the stale socket so ensureDaemon can spawn a fresh one.
- */
-export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
-  // On POSIX, a missing socket file means the daemon definitely isn't running,
-  // so we can short-circuit. Windows named pipes are not filesystem entries —
-  // access() always fails there — so skip the pre-check and probe directly.
-  if (!isWindows) {
-    try {
-      await access(DAEMON_SOCKET_PATH);
-    } catch {
-      return false;
-    }
+export const daemonSocketMayExist = async (
+  platform: NodeJS.Platform = process.platform,
+  socketPath: string = DAEMON_SOCKET_PATH,
+): Promise<boolean> => {
+  if (platform === "win32") return true;
+  try {
+    await access(socketPath);
+    return true;
+  } catch {
+    return false;
   }
+};
+
+export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
+  if (!(await daemonSocketMayExist())) return false;
 
   return new Promise((resolve) => {
     let settled = false;
@@ -61,7 +43,6 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
     const sock = createConnection(DAEMON_SOCKET_PATH);
     const timer = setTimeout(() => {
       sock.destroy();
-      // ponytail: stale socket cleanup; ENOENT = already gone, fine
       cleanupStaleSocket();
       done(false);
     }, timeoutMs);
@@ -75,7 +56,6 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
       const text = chunk.toString();
       if (text.includes('"registered"')) {
         clearTimeout(timer);
-        // Send deregister so the probe doesn't hog a slot
         const deregMsg: WireControl = { type: "control", action: "deregister", clientId: "_liveness_probe" };
         try { sock.write(serialize(deregMsg) + "\n"); } catch {}
         sock.destroy();
@@ -86,13 +66,11 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
     sock.on("error", () => {
       clearTimeout(timer);
       sock.destroy();
-      // ponytail: connection refused = daemon dead, clean up stale socket
       cleanupStaleSocket();
       done(false);
     });
 
-    // close without 'registered' ack = daemon alive but rejected us (e.g. max clients);
-    // don't unlink — the daemon is still using that socket.
+    // Closed without a 'registered' ack: the daemon is alive but rejected us, so do NOT unlink its socket.
     sock.on("close", () => {
       clearTimeout(timer);
       done(false);
@@ -100,45 +78,24 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
   });
 };
 
-/**
- * Spawn the daemon as a detached child process. The daemon will continue
- * running after the parent pi process exits.
- *
- * The daemon entry point is resolved relative to this module. When running
- * from source (tsx), the entry is src/daemon/index.ts. When running compiled,
- * it's dist/daemon/index.js.
- *
- * Returns the child process handle (caller should call child.unref()).
- */
 export const spawnDaemon = (): ChildProcess | null => {
-  // Resolve the daemon entry point and tsx binary.
   const daemonScript = join(moduleDir, "index.ts");
 
-  // On Windows, npm installs binaries as `.cmd` shims, not bare executables,
-  // and the npx fallback is `npx.cmd`. A `.cmd` file can only be launched
-  // through a shell (spawning it directly yields EINVAL), so set shell: true
-  // whenever we invoke one.
+  // Windows npm binaries are `.cmd` shims, which only launch through a shell — spawning one directly yields EINVAL.
   const tsxBinBase = join(moduleDir, "..", "..", "node_modules", ".bin", "tsx");
   const tsxBin = isWindows ? `${tsxBinBase}.cmd` : tsxBinBase;
   const hasLocalTsx = existsSync(tsxBin);
 
-  // Use the local tsx binary to run the daemon TypeScript source directly.
-  // The spawned process inherits the parent's env so module resolution works.
-  // Fall back to `npx tsx` if the local binary isn't available.
   const cmd = hasLocalTsx ? tsxBin : isWindows ? "npx.cmd" : "npx";
   const args = hasLocalTsx ? [daemonScript] : ["tsx", daemonScript];
 
-  // With shell: true, Node passes the command line to the shell verbatim
-  // without quoting, so any path containing spaces (e.g. C:\Users\Some Name)
-  // would be split into multiple tokens. Wrap each token in double quotes on
-  // Windows to keep space-containing paths intact.
+  // With shell: true Node passes the command line verbatim, so a path containing spaces must be quoted or it splits into tokens.
   const quote = (s: string): string => (isWindows ? `"${s}"` : s);
 
   const child = spawn(quote(cmd), args.map(quote), {
     detached: true,
     stdio: "ignore",
     env: { ...process.env },
-    // `.cmd` shims (local tsx or npx.cmd on Windows) must run via a shell.
     shell: isWindows,
     windowsVerbatimArguments: isWindows,
   });
@@ -147,19 +104,12 @@ export const spawnDaemon = (): ChildProcess | null => {
   return child;
 };
 
-/**
- * Ensure the daemon is running. If not, spawn it and wait (up to timeoutMs)
- * for the socket file to appear.
- *
- * Returns true if the daemon is running (or was successfully spawned).
- */
 export const ensureDaemon = async (timeoutMs = 10_000): Promise<boolean> => {
   if (await isDaemonRunning()) return true;
 
   const child = spawnDaemon();
   if (!child) return false;
 
-  // Poll for the socket file to appear
   const deadline = Date.now() + timeoutMs;
   while (Date.now() < deadline) {
     if (await isDaemonRunning()) return true;