pi-browser-harness 0.10.2 → 0.11.0

package/src/daemon/bridge.ts

@@ -1,22 +1,10 @@
-/**
- * CdpBridge — persistent WebSocket to Chrome, ID multiplexing, event routing.
- *
- * A single long-lived process connection to Chrome that proxies CDP traffic
- * for multiple pi clients connected via the IpcServer. One Allow dialog ever.
- *
- * References:
- *   - CDP message format: https://github.com/aslushnikov/getting-started-with-cdp#protocol-fundamentals
- *   - CDP sessions + IDs: https://github.com/aslushnikov/getting-started-with-cdp#targets--sessions
- *   - Target domain: https://chromedevtools.github.io/devtools-protocol/tot/Target/
- */
-
 import WebSocket from "ws";
 import { discoverWsUrl } from "../cdp/discovery";
+import { isCdpRawMessage } from "../cdp/types";
 import type { CdpRawMessage } from "../cdp/types";
 import type { WireRequest, WireResponse, WireEvent } from "./protocol";
 import { CDP_CONNECT_TIMEOUT_MS, CDP_COMMAND_TIMEOUT_MS } from "./protocol";
-
-// ── Types ──────────────────────────────────────────────────────────────────────
+import { asString, isRecord } from "../util/guards";
 
 export type SendToClient = (clientId: string, msg: WireResponse | WireEvent) => void;
 
@@ -25,146 +13,147 @@ export type EventHandler = (event: WireEvent, targetClientIds: string[]) => void
 export type CloseHandler = () => void;
 
 export type CdpBridge = {
-  /** Start the bridge. Resolves when the daemon IPC + Chrome discovery loop
-   *  are initialized (not when Chrome is connected — that may take retries). */
   start(): Promise<void>;
   stop(): Promise<void>;
   handleRequest(req: WireRequest, clientId: string, send: SendToClient): Promise<void>;
-  /** True when the Chrome WebSocket is open and ready. */
   isAlive(): boolean;
-  recordSession(clientId: string, sessionId: string): void;
-  releaseSession(sessionId: string): void;
   getSessionOwner(sessionId: string): string | undefined;
   removeClient(clientId: string): void;
   onEvent(handler: EventHandler): void;
   onClose(handler: CloseHandler): void;
 };
 
-// ── ID Multiplexer ────────────────────────────────────────────────────────────
-
-interface PendingEntry {
-  clientId: string;
-  localId: number;
-}
-
-class IdMultiplexer {
-  private nextId = 1;
-  private localToRemote = new Map<string, Map<number, number>>();
-  private pending = new Map<number, PendingEntry>();
-
-  allocate(clientId: string, localId: number): number {
-    const daemonId = this.nextId++;
-    let m = this.localToRemote.get(clientId);
-    if (!m) { m = new Map(); this.localToRemote.set(clientId, m); }
-    m.set(localId, daemonId);
-    this.pending.set(daemonId, { clientId, localId });
-    return daemonId;
-  }
-
-  resolve(daemonId: number): PendingEntry | null {
-    const e = this.pending.get(daemonId);
-    if (!e) return null;
-    this.pending.delete(daemonId);
-    const m = this.localToRemote.get(e.clientId);
-    if (m) m.delete(e.localId);
-    return e;
-  }
-
-  clearClient(clientId: string): void {
-    const m = this.localToRemote.get(clientId);
-    if (m) { for (const [, did] of m) this.pending.delete(did); }
-    this.localToRemote.delete(clientId);
-  }
-}
-
-// ── Event Router ───────────────────────────────────────────────────────────────
-
-class EventRouter {
-  private owners = new Map<string, string>();       // sessionId → clientId
-  private clientSessions = new Map<string, Set<string>>(); // clientId → sessions
-
-  record(clientId: string, sessionId: string): void {
-    const prev = this.owners.get(sessionId);
-    if (prev && prev !== clientId) {
-      this.clientSessions.get(prev)?.delete(sessionId);
-    }
-    this.owners.set(sessionId, clientId);
-    let s = this.clientSessions.get(clientId);
-    if (!s) { s = new Set(); this.clientSessions.set(clientId, s); }
-    s.add(sessionId);
-  }
-
-  release(sessionId: string): void {
-    const owner = this.owners.get(sessionId);
-    if (owner) this.clientSessions.get(owner)?.delete(sessionId);
-    this.owners.delete(sessionId);
-  }
-
-  getOwner(sessionId: string): string | undefined {
-    return this.owners.get(sessionId);
-  }
-
-  removeClient(clientId: string): void {
-    const sessions = this.clientSessions.get(clientId);
-    if (sessions) { for (const sid of sessions) this.owners.delete(sid); }
-    this.clientSessions.delete(clientId);
-  }
-
-  /**
-   * Route a CDP event to client(s).
-   * Session-scoped → only the owning client.
-   * Browser-level (no sessionId) → all connected clients.
-   */
-  route(event: WireEvent): string[] {
-    if (event.sessionId) {
-      const owner = this.owners.get(event.sessionId);
-      return owner ? [owner] : [];
-    }
-    return [...this.clientSessions.keys()];
-  }
+export type InFlight = {
+  readonly clientId: string;
+  readonly localId: number;
+  readonly send: SendToClient;
+  readonly timer: ReturnType<typeof setTimeout>;
+  readonly isAttach: boolean;
+};
 
-  allClients(): string[] {
-    return [...this.clientSessions.keys()];
-  }
-}
+// One map, keyed by the daemon-side id: the client that asked, the id it used, and everything needed to answer it.
+export type IdMultiplexer = {
+  allocate(entry: Omit<InFlight, "timer">, arm: (daemonId: number) => InFlight["timer"]): number;
+  take(daemonId: number): InFlight | undefined;
+  takeAll(): ReadonlyArray<InFlight>;
+  clearClient(clientId: string): void;
+};
+
+export const createIdMultiplexer = (): IdMultiplexer => {
+  let nextId = 1;
+  const inFlight = new Map<number, InFlight>();
+
+  return {
+    allocate(entry, arm) {
+      const daemonId = nextId++;
+      inFlight.set(daemonId, { ...entry, timer: arm(daemonId) });
+      return daemonId;
+    },
+    take(daemonId) {
+      const e = inFlight.get(daemonId);
+      if (!e) return undefined;
+      inFlight.delete(daemonId);
+      clearTimeout(e.timer);
+      return e;
+    },
+    takeAll() {
+      const all = [...inFlight.values()];
+      inFlight.clear();
+      for (const e of all) clearTimeout(e.timer);
+      return all;
+    },
+    // A disconnected client must not be answered later: dropping its entries also cancels their timeouts.
+    clearClient(clientId) {
+      for (const [daemonId, e] of inFlight) {
+        if (e.clientId !== clientId) continue;
+        clearTimeout(e.timer);
+        inFlight.delete(daemonId);
+      }
+    },
+  };
+};
+
+export type EventRouter = {
+  record(clientId: string, sessionId: string): void;
+  release(sessionId: string): void;
+  getOwner(sessionId: string): string | undefined;
+  removeClient(clientId: string): void;
+  route(event: WireEvent): string[];
+};
+
+export const createEventRouter = (): EventRouter => {
+  const owners = new Map<string, string>();
+  const clientSessions = new Map<string, Set<string>>();
+
+  return {
+    record(clientId, sessionId) {
+      const prev = owners.get(sessionId);
+      if (prev && prev !== clientId) clientSessions.get(prev)?.delete(sessionId);
+      owners.set(sessionId, clientId);
+      let s = clientSessions.get(clientId);
+      if (!s) { s = new Set(); clientSessions.set(clientId, s); }
+      s.add(sessionId);
+    },
+    release(sessionId) {
+      const owner = owners.get(sessionId);
+      if (owner) clientSessions.get(owner)?.delete(sessionId);
+      owners.delete(sessionId);
+    },
+    getOwner(sessionId) {
+      return owners.get(sessionId);
+    },
+    removeClient(clientId) {
+      const sessions = clientSessions.get(clientId);
+      if (sessions) { for (const sid of sessions) owners.delete(sid); }
+      clientSessions.delete(clientId);
+    },
+    route(event) {
+      if (event.sessionId) {
+        const owner = owners.get(event.sessionId);
+        return owner ? [owner] : [];
+      }
+      return [...clientSessions.keys()];
+    },
+  };
+};
 
-// ── Implementation ─────────────────────────────────────────────────────────────
+const CONNECT_WAIT_MS = 15_000;
 
 export const createCdpBridge = (): CdpBridge => {
   let ws: WebSocket | null = null;
   let wsUrl: string | null = null;
-  const mux = new IdMultiplexer();
-  const router = new EventRouter();
+  const mux = createIdMultiplexer();
+  const router = createEventRouter();
   let eventHandler: EventHandler | null = null;
   let closeHandler: CloseHandler | null = null;
 
-  // daemonId → { send, timer, isAttach }
-  const callbacks = new Map<number, {
-    send: SendToClient;
-    clientId: string;
-    localId: number;
-    timer: ReturnType<typeof setTimeout>;
-    isAttach: boolean;
-  }>();
+  const connectedWaiters: Array<() => void> = [];
+  const signalConnected = (): void => {
+    for (const w of connectedWaiters.splice(0)) w();
+  };
 
-  // ── Handle raw CDP messages from Chrome ─────────────────────────────────
+  const waitForConnection = (timeoutMs: number): Promise<void> =>
+    new Promise((resolve) => {
+      let settled = false;
+      const finish = (): void => {
+        if (settled) return;
+        settled = true;
+        clearTimeout(timer);
+        resolve();
+      };
+      const timer = setTimeout(finish, timeoutMs);
+      connectedWaiters.push(finish);
+    });
 
   const onChromeMessage = (raw: string): void => {
-    let msg: CdpRawMessage;
-    try { msg = JSON.parse(raw); } catch { return; }
+    let parsed: unknown;
+    try { parsed = JSON.parse(raw); } catch { return; }
+    if (!isCdpRawMessage(parsed)) return;
+    const msg: CdpRawMessage = parsed;
 
-    // ---- Response (has id) ----
     if (msg.id !== undefined) {
-      const cb = callbacks.get(msg.id);
-      if (!cb) {
-        // Stale response — client already timed out or disconnected.
-        // Still clean up the multiplexer mapping.
-        mux.resolve(msg.id);
-        return;
-      }
-      clearTimeout(cb.timer);
-      callbacks.delete(msg.id);
-
+      const cb = mux.take(msg.id);
+      if (!cb) return;
       const localId = cb.localId;
 
       if (msg.error) {
@@ -174,24 +163,19 @@ export const createCdpBridge = (): CdpBridge => {
           error: { code: msg.error.code ?? -1, message: msg.error.message },
         });
       } else {
-        // Track session ownership for attach responses
         if (cb.isAttach && msg.result) {
-          const result = msg.result as { sessionId?: string };
-          if (result.sessionId) {
-            router.record(cb.clientId, result.sessionId);
+          const sessionId = isRecord(msg.result) ? asString(msg.result["sessionId"]) : undefined;
+          if (sessionId) {
+            router.record(cb.clientId, sessionId);
           }
         }
         cb.send(cb.clientId, { type: "response", id: localId, result: msg.result });
       }
-
-      mux.resolve(msg.id);
       return;
     }
 
-    // ---- Event (no id, has method) ----
     if (!msg.method) return;
 
-    // Inspector.detached — release session ownership
     if (msg.method === "Inspector.detached" && msg.sessionId) {
       router.release(msg.sessionId);
     }
@@ -203,7 +187,6 @@ export const createCdpBridge = (): CdpBridge => {
       ...(msg.sessionId !== undefined ? { sessionId: msg.sessionId } : {}),
     };
 
-    // Route through the event handler for the IpcServer to broadcast
     if (eventHandler) {
       const targets = router.route(wireEvent);
       if (targets.length > 0) {
@@ -212,35 +195,26 @@ export const createCdpBridge = (): CdpBridge => {
     }
   };
 
-  // ── Connect to Chrome ───────────────────────────────────────────────────
-
-  // ── Auto-reconnecting Chrome connection ───────────────────────────────
-
   let reconnectTimer: ReturnType<typeof setTimeout> | null = null;
   let reconnectAttempt = 0;
   let stopped = false;
 
-  /**
-   * Try to discover Chrome and open a WebSocket. On failure, schedule
-   * an exponential backoff retry (capped at 60s). When Chrome finally
-   * becomes available, the bridge connects automatically — no manual
-   * daemon restart needed.
-   */
   const tryConnect = (): void => {
     if (stopped) return;
     if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
 
     const attempt = async (): Promise<void> => {
-      // Already connected — nothing to do.
       if (ws && ws.readyState === WebSocket.OPEN) return;
 
-      // Resolve URL (discover if not cached, or clear cache on retry)
-      let url = wsUrl;
-      if (!url || reconnectAttempt > 0) {
+      const cachedUrl = wsUrl;
+      let url: string;
+      if (cachedUrl === null || cachedUrl === "" || reconnectAttempt > 0) {
         const d = await discoverWsUrl();
         if (!d.success) { scheduleRetry(); return; }
         url = d.data;
         wsUrl = url;
+      } else {
+        url = cachedUrl;
       }
 
       const settledPromise = new Promise<void>((settle) => {
@@ -253,7 +227,7 @@ export const createCdpBridge = (): CdpBridge => {
 
         let sock: WebSocket;
         try {
-          sock = new WebSocket(url!, { perMessageDeflate: false });
+          sock = new WebSocket(url, { perMessageDeflate: false });
         } catch {
           scheduleRetry();
           return;
@@ -268,9 +242,9 @@ export const createCdpBridge = (): CdpBridge => {
           clearTimeout(timer);
           ws = sock;
           reconnectAttempt = 0;
-          // Enable target discovery so we see page events
           ws.send(JSON.stringify({ id: 0, method: "Target.setDiscoverTargets", params: { discover: true } }));
           console.log("[pi-browser-daemon] Connected to Chrome ✓");
+          signalConnected();
           settleOnce();
         });
 
@@ -286,25 +260,19 @@ export const createCdpBridge = (): CdpBridge => {
         sock.on("close", () => {
           clearTimeout(timer);
           ws = null;
-          // Reject all pending callbacks
-          for (const [daemonId, cb] of callbacks) {
-            clearTimeout(cb.timer);
+          for (const cb of mux.takeAll()) {
             cb.send(cb.clientId, {
               type: "response",
               id: cb.localId,
               error: { code: -32000, message: "Chrome disconnected" },
             });
-            callbacks.delete(daemonId);
-            mux.resolve(daemonId);
           }
           closeHandler?.();
-          // Auto-reconnect on unexpected close
           scheduleRetry();
         });
       });
 
       await settledPromise;
-      // If connection didn't succeed, schedule a retry
       if (!ws || ws.readyState !== WebSocket.OPEN) {
         scheduleRetry();
       }
@@ -313,28 +281,24 @@ export const createCdpBridge = (): CdpBridge => {
     attempt().catch(() => scheduleRetry());
   };
 
-  /** Exponential backoff: 1s, 2s, 4s, 8s, 16s, 32s, 60s (capped). */
   const scheduleRetry = (): void => {
     if (stopped) return;
     const delay = Math.min(1000 * Math.pow(2, Math.min(reconnectAttempt, 6)), 60_000);
     reconnectAttempt++;
-    wsUrl = null; // force re-discovery on next attempt
+    wsUrl = null;
     reconnectTimer = setTimeout(tryConnect, delay);
   };
 
   const start = async (): Promise<void> => {
     stopped = false;
-    // Don't await — the retry loop runs in the background.
-    // The daemon is "started" when the IPC server is listening, not when
-    // Chrome is connected.
     tryConnect();
   };
 
   const stop = async (): Promise<void> => {
     stopped = true;
     if (reconnectTimer) { clearTimeout(reconnectTimer); reconnectTimer = null; }
-    for (const [, cb] of callbacks) clearTimeout(cb.timer);
-    callbacks.clear();
+    mux.takeAll();
+    signalConnected();
     if (ws) { try { ws.close(1000, "Shutdown"); } catch {} ws = null; }
     wsUrl = null;
   };
@@ -344,15 +308,8 @@ export const createCdpBridge = (): CdpBridge => {
     clientId: string,
     send: SendToClient,
   ): Promise<void> => {
-    // ponytail: wait for Chrome to connect (user may still be clicking "Allow").
-    // Bridge retries in background; this polls so the client doesn't fail first try.
-    if (!ws || ws.readyState !== WebSocket.OPEN) {
-      const deadline = Date.now() + 15_000;
-      while (Date.now() < deadline) {
-        await new Promise((r) => setTimeout(r, 250));
-        if (ws && ws.readyState === WebSocket.OPEN) break;
-      }
-    }
+    // Every queued request awaits the same connect signal rather than each spinning its own poll loop.
+    if (!ws || ws.readyState !== WebSocket.OPEN) await waitForConnection(CONNECT_WAIT_MS);
 
     if (!ws || ws.readyState !== WebSocket.OPEN) {
       send(clientId, {
@@ -363,27 +320,21 @@ export const createCdpBridge = (): CdpBridge => {
       return;
     }
 
-    const daemonId = mux.allocate(clientId, req.id);
-
-    // Store callback for the response
-    const timer = setTimeout(() => {
-      callbacks.delete(daemonId);
-      mux.resolve(daemonId);
-      send(clientId, {
-        type: "response",
-        id: req.id,
-        error: { code: -32000, message: `Timeout after ${CDP_COMMAND_TIMEOUT_MS}ms: ${req.method}` },
-      });
-    }, CDP_COMMAND_TIMEOUT_MS);
-
-    const isAttach = req.method === "Target.attachToTarget";
     const isDetach = req.method === "Target.detachFromTarget";
-
-    if (isDetach && req.sessionId) {
-      router.release(req.sessionId);
-    }
-
-    callbacks.set(daemonId, { send, clientId, localId: req.id, timer, isAttach });
+    if (isDetach && req.sessionId) router.release(req.sessionId);
+
+    const daemonId = mux.allocate(
+      { clientId, localId: req.id, send, isAttach: req.method === "Target.attachToTarget" },
+      (id) =>
+        setTimeout(() => {
+          mux.take(id);
+          send(clientId, {
+            type: "response",
+            id: req.id,
+            error: { code: -32000, message: `Timeout after ${CDP_COMMAND_TIMEOUT_MS}ms: ${req.method}` },
+          });
+        }, CDP_COMMAND_TIMEOUT_MS),
+    );
 
     const payload: Record<string, unknown> = {
       id: daemonId,
@@ -395,9 +346,7 @@ export const createCdpBridge = (): CdpBridge => {
     try {
       ws.send(JSON.stringify(payload));
     } catch (e) {
-      clearTimeout(timer);
-      callbacks.delete(daemonId);
-      mux.resolve(daemonId);
+      mux.take(daemonId);
       send(clientId, {
         type: "response",
         id: req.id,
@@ -411,8 +360,6 @@ export const createCdpBridge = (): CdpBridge => {
     stop,
     handleRequest,
     isAlive: () => ws !== null && ws.readyState === WebSocket.OPEN,
-    recordSession: (cid, sid) => router.record(cid, sid),
-    releaseSession: (sid) => router.release(sid),
     getSessionOwner: (sid) => router.getOwner(sid),
     removeClient: (cid) => { mux.clearClient(cid); router.removeClient(cid); },
     onEvent: (h) => { eventHandler = h; },

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();