pi-browser-harness 0.10.2 → 0.12.0

package/src/daemon/index.ts

@@ -1,13 +1,3 @@
-/**
- * Browser daemon entry point — standalone long-lived process.
- *
- * Owns a single persistent WebSocket to Chrome. Exposes a Unix domain socket
- * for pi instances to connect through. One Allow dialog ever (per Chrome
- * lifetime), zero repeated prompts.
- *
- * Run: npx tsx src/daemon/index.ts
- */
-
 import { createIpcServer } from "./server";
 import { createCdpBridge, type SendToClient } from "./bridge";
 import { DAEMON_IDLE_TIMEOUT_MS } from "./protocol";
@@ -18,9 +8,6 @@ async function main() {
   const ipcServer = createIpcServer();
   const cdpBridge = createCdpBridge();
 
-  // ── Wire IpcServer → CdpBridge ─────────────────────────────────────────
-
-  // When a pi client sends a CDP request, proxy it through the bridge to Chrome.
   ipcServer.onMessage((msg, client) => {
     if (msg.type !== "request") return;
 
@@ -31,19 +18,16 @@ async function main() {
     cdpBridge.handleRequest(msg, client.id, send);
   });
 
-  // When Chrome sends an event, route it to the correct pi client(s).
   cdpBridge.onEvent((event, targetClientIds) => {
     for (const cid of targetClientIds) {
       ipcServer.send(cid, event);
     }
   });
 
-  // When a client disconnects, clean up its CDP state.
   ipcServer.onDisconnect((client) => {
     cdpBridge.removeClient(client.id);
   });
 
-  // When Chrome disconnects, notify all clients.
   cdpBridge.onClose(() => {
     console.log("[pi-browser-daemon] Chrome disconnected");
     ipcServer.broadcast({
@@ -53,11 +37,6 @@ async function main() {
     });
   });
 
-  // ── Idle timeout ───────────────────────────────────────────────────────
-
-  // The daemon exits after DAEMON_IDLE_TIMEOUT_MS with zero connected clients.
-  // This prevents zombie processes when pi sessions end and never reconnect.
-  // The timeout resets whenever a client connects.
   let idleTimer: ReturnType<typeof setTimeout> | null = null;
 
   const resetIdleTimer = (): void => {
@@ -78,8 +57,6 @@ async function main() {
   ipcServer.onConnect(() => { cancelIdleTimer(); });
   ipcServer.onDisconnect(() => { resetIdleTimer(); });
 
-  // ── Start ──────────────────────────────────────────────────────────────
-
   try {
     await ipcServer.start();
     console.log("[pi-browser-daemon] IPC server listening");
@@ -88,15 +65,10 @@ async function main() {
     process.exit(1);
   }
 
-  // Connect to Chrome (auto-retries with backoff in the background).
-  // The daemon is ready immediately — Chrome may connect later.
   await cdpBridge.start();
 
-  // Start the idle timer (no clients yet at startup).
   resetIdleTimer();
 
-  // ── Graceful shutdown ──────────────────────────────────────────────────
-
   const shutdown = async () => {
     console.log("[pi-browser-daemon] Shutting down...");
     await cdpBridge.stop();

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,
   };
 };