pi-browser-harness 0.11.0 → 0.13.0

package/src/daemon/server.ts

@@ -1,6 +1,7 @@
 import { createServer, type Server, type Socket } from "node:net";
-import { createInterface, type Interface } from "node:readline";
+import { readLines } from "./lines";
 import { unlinkSync } from "node:fs";
+import { destroyQuietly } from "./socket";
 import {
   type WireMessage,
   type WireControl,
@@ -13,7 +14,7 @@ import {
 export type ClientSocket = {
   id: string;
   readonly socket: Socket;
-  readonly rl: Interface;
+  readonly stopReading: () => void;
   registered: boolean;
 };
 
@@ -21,51 +22,86 @@ export type MessageHandler = (msg: WireMessage, client: ClientSocket) => void;
 
 export type ConnectionHandler = (client: ClientSocket) => void;
 
+export type Disposer = () => void;
+
+export type IpcServerOptions = {
+  readonly socketPath?: string;
+  readonly maxClients?: number;
+};
+
 export type IpcServer = {
-  start(): Promise<void>;
-  stop(): Promise<void>;
-  onMessage(handler: MessageHandler): void;
-  onConnect(handler: ConnectionHandler): void;
-  onDisconnect(handler: ConnectionHandler): void;
-  send(clientId: string, msg: WireMessage): void;
-  broadcast(msg: WireMessage): void;
-  clientCount(): number;
+  readonly start: () => Promise<void>;
+  readonly stop: () => Promise<void>;
+  readonly onMessage: (handler: MessageHandler) => Disposer;
+  readonly onConnect: (handler: ConnectionHandler) => Disposer;
+  // Runs once per registered client when it goes away, whether its socket closed or it sent
+  // "deregister". Every registered handler runs; registering is additive, not a replacement.
+  readonly onDisconnect: (handler: ConnectionHandler) => Disposer;
+  readonly send: (clientId: string, msg: WireMessage) => void;
+  readonly broadcast: (msg: WireMessage) => void;
+  readonly clientCount: () => number;
+  // Every open socket, registered or not; the connection cap counts these.
+  readonly socketCount: () => number;
 };
 
-export const createIpcServer = (): IpcServer => {
+const listen = <H>(handlers: Set<H>) => (handler: H): Disposer => {
+  handlers.add(handler);
+  return () => { handlers.delete(handler); };
+};
+
+
+export const createIpcServer = (options: IpcServerOptions = {}): IpcServer => {
+  const socketPath = options.socketPath ?? DAEMON_SOCKET_PATH;
+  const maxClients = options.maxClients ?? DAEMON_MAX_CLIENTS;
   let server: Server | null = null;
-  const sockets = new Map<string, ClientSocket>();
+  // Sockets that have not registered yet, by their temporary id.
+  const anonymous = new Map<string, ClientSocket>();
   const clients = new Map<string, ClientSocket>();
-  let messageHandler: MessageHandler | null = null;
-  let connectHandler: ConnectionHandler | null = null;
-  let disconnectHandler: ConnectionHandler | null = null;
+  const messageHandlers = new Set<MessageHandler>();
+  const connectHandlers = new Set<ConnectionHandler>();
+  const disconnectHandlers = new Set<ConnectionHandler>();
   let nextTempId = 1;
 
+  const unlinkSocketFile = (): void => {
+    if (process.platform === "win32") return;
+    try {
+      unlinkSync(socketPath);
+    } catch {
+      // Nothing to unlink, or no permission: listen() reports the real problem if there is one.
+    }
+  };
+
+  // A registered client leaves exactly once: either its socket closes or it deregisters first.
+  const forget = (client: ClientSocket): void => {
+    if (!client.registered) return;
+    client.registered = false;
+    clients.delete(client.id);
+    for (const h of disconnectHandlers) h(client);
+  };
+
   const start = (): Promise<void> =>
     new Promise((resolve, reject) => {
-      try {
-        unlinkSync(DAEMON_SOCKET_PATH);
-      } catch {}
+      unlinkSocketFile();
 
       server = createServer({ pauseOnConnect: false }, (socket: Socket) => {
-        if (clients.size >= DAEMON_MAX_CLIENTS) {
+        if (anonymous.size + clients.size >= maxClients) {
           socket.destroy();
           return;
         }
 
         const tempId = `anon-${nextTempId++}`;
-        const rl = createInterface({ input: socket, crlfDelay: Infinity });
-        let currentClient: ClientSocket = { id: tempId, socket, rl, registered: false };
+        const stopReading = readLines(socket, (line) => { onLine(line); });
+        const client: ClientSocket = { id: tempId, socket, stopReading, registered: false };
 
-        sockets.set(tempId, currentClient);
+        anonymous.set(tempId, client);
 
-        rl.on("line", (line: string) => {
+        function onLine(line: string): void {
           const msg = deserialize(line);
           if (!msg) return;
 
-          if (msg.type === "control" && msg.action === "register" && !currentClient.registered) {
+          if (msg.type === "control" && msg.action === "register") {
+            if (client.registered) return;
             const clientId = msg.clientId;
-            if (!clientId) return;
 
             if (clients.has(clientId)) {
               const reply: WireControl = {
@@ -73,41 +109,43 @@ export const createIpcServer = (): IpcServer => {
                 action: "shutdown",
                 reason: `clientId ${clientId} is already connected`,
               };
-              socket.write(serialize(reply) + "\n");
-              socket.destroy();
+              // end() flushes the reply before closing; destroy() would race it.
+              socket.end(serialize(reply) + "\n");
               return;
             }
 
             // 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);
+            anonymous.delete(tempId);
+            client.id = clientId;
+            client.registered = true;
+            clients.set(clientId, client);
 
             const ack: WireControl = { type: "control", action: "registered", clientId };
             socket.write(serialize(ack) + "\n");
 
-            connectHandler?.(currentClient);
+            for (const h of connectHandlers) h(client);
             return;
           }
 
-          if (!currentClient.registered) return;
+          if (!client.registered) return;
 
-          messageHandler?.(msg, currentClient);
-        });
+          if (msg.type === "control" && msg.action === "deregister") {
+            if (msg.clientId !== client.id) return;
+            forget(client);
+            socket.end();
+            return;
+          }
+
+          for (const h of messageHandlers) h(msg, client);
+        }
 
-        socket.on("error", () => {});
+        // A client socket error is always followed by "close", which does the cleanup.
+        socket.on("error", () => undefined);
 
         socket.on("close", () => {
-          const found = clients.get(currentClient.id) ?? sockets.get(tempId);
-          if (found) {
-            clients.delete(found.id);
-            sockets.delete(tempId);
-            if (found.registered) {
-              disconnectHandler?.(found);
-            }
-          }
-          rl.close();
+          anonymous.delete(tempId);
+          forget(client);
+          stopReading();
         });
       });
 
@@ -115,25 +153,27 @@ export const createIpcServer = (): IpcServer => {
         reject(err);
       });
 
-      server.listen(DAEMON_SOCKET_PATH, () => {
+      server.listen(socketPath, () => {
         resolve();
       });
     });
 
   const stop = (): Promise<void> =>
     new Promise((resolve) => {
+      // Stopping is not a client leaving: no disconnect handler runs for sockets torn down here.
       for (const [, client] of clients) {
-        try { client.socket.destroy(); } catch {}
+        client.registered = false;
+        destroyQuietly(client.socket);
       }
-      for (const [, client] of sockets) {
-        try { client.socket.destroy(); } catch {}
+      for (const [, client] of anonymous) {
+        destroyQuietly(client.socket);
       }
       clients.clear();
-      sockets.clear();
+      anonymous.clear();
 
       if (server) {
         server.close(() => {
-          try { unlinkSync(DAEMON_SOCKET_PATH); } catch {}
+          unlinkSocketFile();
           resolve();
         });
       } else {
@@ -146,25 +186,22 @@ export const createIpcServer = (): IpcServer => {
     if (!client) return;
     try {
       client.socket.write(serialize(msg) + "\n");
-    } catch {}
+    } catch {
+      // The client went away mid-write; its "close" handler forgets it.
+    }
   };
 
   return {
     start,
     stop,
-    onMessage(handler) {
-      messageHandler = handler;
-    },
-    onConnect(handler) {
-      connectHandler = handler;
-    },
-    onDisconnect(handler) {
-      disconnectHandler = handler;
-    },
+    onMessage: listen(messageHandlers),
+    onConnect: listen(connectHandlers),
+    onDisconnect: listen(disconnectHandlers),
     send,
-    broadcast(msg) {
+    broadcast: (msg) => {
       for (const [clientId] of clients) send(clientId, msg);
     },
-    clientCount: (): number => clients.size,
+    clientCount: () => clients.size,
+    socketCount: () => anonymous.size + clients.size,
   };
 };

package/src/daemon/socket.ts

@@ -0,0 +1,10 @@
+import type { Socket } from "node:net";
+
+// destroy() on a socket whose handle is already gone throws; the socket is gone either way.
+export const destroyQuietly = (socket: Socket): void => {
+  try {
+    socket.destroy();
+  } catch {
+    // Already torn down.
+  }
+};

package/src/daemon/spawn.ts

@@ -1,19 +1,25 @@
 import { spawn, type ChildProcess } from "node:child_process";
+import { accessSync } from "node:fs";
 import { access, unlink } from "node:fs/promises";
-import { existsSync } from "node:fs";
+import { createRequire } from "node:module";
 import { fileURLToPath } from "node:url";
 import { dirname, join } from "node:path";
 import { createConnection } from "node:net";
-import { DAEMON_SOCKET_PATH, serialize, type WireControl } from "./protocol";
+import { readLines } from "./lines";
+import { DAEMON_SOCKET_PATH, deserialize, serialize, type WireControl } from "./protocol";
+import { destroyQuietly } from "./socket";
 
 const moduleDir = dirname(fileURLToPath(import.meta.url));
 
+const requireFromHere = createRequire(import.meta.url);
+
 const isWindows = process.platform === "win32";
 
 // 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(() => {});
+  // ENOENT is the normal case; anything else surfaces when listen() fails.
+  unlink(DAEMON_SOCKET_PATH).catch(() => undefined);
 };
 
 export const daemonSocketMayExist = async (
@@ -42,7 +48,7 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
 
     const sock = createConnection(DAEMON_SOCKET_PATH);
     const timer = setTimeout(() => {
-      sock.destroy();
+      destroyQuietly(sock);
       cleanupStaleSocket();
       done(false);
     }, timeoutMs);
@@ -52,20 +58,20 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
       sock.write(serialize(regMsg) + "\n");
     });
 
-    sock.on("data", (chunk: Buffer) => {
-      const text = chunk.toString();
-      if (text.includes('"registered"')) {
-        clearTimeout(timer);
-        const deregMsg: WireControl = { type: "control", action: "deregister", clientId: "_liveness_probe" };
-        try { sock.write(serialize(deregMsg) + "\n"); } catch {}
-        sock.destroy();
-        done(true);
-      }
+    // Line-framed like every other reader of this protocol: a chunk may hold a partial line.
+    readLines(sock, (line) => {
+      const msg = deserialize(line);
+      if (msg?.type !== "control" || msg.action !== "registered") return;
+      clearTimeout(timer);
+      const deregMsg: WireControl = { type: "control", action: "deregister", clientId: "_liveness_probe" };
+      // end() lets the deregister reach the daemon; destroy() would drop it unflushed.
+      try { sock.end(serialize(deregMsg) + "\n"); } catch { destroyQuietly(sock); }
+      done(true);
     });
 
     sock.on("error", () => {
       clearTimeout(timer);
-      sock.destroy();
+      destroyQuietly(sock);
       cleanupStaleSocket();
       done(false);
     });
@@ -78,28 +84,79 @@ export const isDaemonRunning = async (timeoutMs = 2_000): Promise<boolean> => {
   });
 };
 
-export const spawnDaemon = (): ChildProcess | null => {
-  const daemonScript = join(moduleDir, "index.ts");
+// Walks upward like Node's own node_modules lookup. Exported with an injectable start so the
+// hoisted layout pi uses can be exercised against a fixture instead of this checkout.
+export const resolveTsxCliFromFilesystem = (startDir: string = moduleDir): string | null => {
+  for (let dir = startDir; ; dir = dirname(dir)) {
+    const candidate = join(dir, "node_modules", "tsx", "dist", "cli.mjs");
+    try {
+      accessSync(candidate);
+      return candidate;
+    } catch {
+      // Keep walking toward the filesystem root. This mirrors Node's node_modules lookup
+      // without relying on createRequire().resolve(), which is broken for external modules
+      // loaded through jiti/static inside a Bun-compiled executable such as pi.exe.
+    }
+    // dirname() of the filesystem root is the root itself.
+    if (dirname(dir) === dir) return null;
+  }
+};
+
+const resolveTsxCli = (): string | null => {
+  try {
+    const resolved = requireFromHere.resolve("tsx/cli");
+    // A compiled runtime may theoretically return a virtual path that a separately spawned
+    // Node process cannot read. Only accept a resolver result that exists on the host FS.
+    accessSync(resolved);
+    return resolved;
+  } catch {
+    return resolveTsxCliFromFilesystem();
+  }
+};
 
-  // 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);
+export const daemonNodeExecutable = (
+  env: NodeJS.ProcessEnv = process.env,
+  versions: Readonly<Record<string, string | undefined>> = process.versions,
+  platform: NodeJS.Platform = process.platform,
+  execPath: string = process.execPath,
+): string => {
+  const override = env["PI_BROWSER_NODE"];
+  if (override) return override;
 
-  const cmd = hasLocalTsx ? tsxBin : isWindows ? "npx.cmd" : "npx";
-  const args = hasLocalTsx ? [daemonScript] : ["tsx", daemonScript];
+  // Under normal Node keep the exact executable that launched pi/the extension. Under Bun,
+  // process.execPath is bun/pi.exe, not Node, so run the tsx CLI with the required Node runtime.
+  if ("bun" in versions) return platform === "win32" ? "node.exe" : "node";
 
-  // 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);
+  return execPath;
+};
 
-  const child = spawn(quote(cmd), args.map(quote), {
+export const daemonSpawnCommand = (): { readonly command: string; readonly args: ReadonlyArray<string> } | null => {
+  const daemonScript = join(moduleDir, "main.ts");
+  const tsxCli = resolveTsxCli();
+  if (!tsxCli) return null;
+
+  return {
+    command: daemonNodeExecutable(),
+    args: [tsxCli, daemonScript],
+  };
+};
+
+export const spawnDaemon = (): ChildProcess | null => {
+  const spec = daemonSpawnCommand();
+  if (!spec) return null;
+
+  const child = spawn(spec.command, [...spec.args], {
     detached: true,
     stdio: "ignore",
     env: { ...process.env },
-    shell: isWindows,
-    windowsVerbatimArguments: isWindows,
+    windowsHide: true,
   });
 
+  // `spawn` reports a missing executable (a bare `node` that is not on PATH under a Bun host)
+  // asynchronously via `error`; without a listener that is an uncaught exception in pi.
+  // ensureDaemon's poll loop reports the failure as a timeout, which is what the user sees.
+  child.on("error", () => undefined);
+
   child.unref();
   return child;
 };

package/src/daemon/transport.ts

@@ -1,5 +1,6 @@
 import { createConnection, type Socket } from "node:net";
-import { createInterface } from "node:readline";
+import { readLines } from "./lines";
+import { destroyQuietly } from "./socket";
 import { type Result, err, ok } from "../util/result";
 import { type CdpError, cdpError, classifyRemoteError } from "../cdp/errors";
 import { DEFAULT_TIMEOUT_MS, type CdpTransport } from "../cdp/types";
@@ -13,72 +14,85 @@ import {
   serialize,
 } from "./protocol";
 
-export const createDaemonTransport = (clientId: string): CdpTransport => {
+type ConnectResult = Result<void, CdpError>;
+
+export const createDaemonTransport = (clientId: string, socketPath: string = DAEMON_SOCKET_PATH): CdpTransport => {
   let socket: Socket | null = null;
-  let rl: ReturnType<typeof createInterface> | null = null;
+  let stopReading: (() => void) | null = null;
   let queue = makeEventQueue();
   const closeListeners = new Set<() => void>();
   const pending = new Map<number, Pending>();
   let registered = false;
   let nextRequestId = 1;
+  // The handshake in progress, so that concurrent connect() callers share one socket instead
+  // of each opening their own and the later one orphaning the earlier.
+  let inFlight: Promise<ConnectResult> | null = null;
+
+  // Tears down `sock` only if it is still the transport's socket: a socket from a superseded
+  // attempt is just destroyed, without touching the state that belongs to the current one.
+  const cleanup = (sock: Socket, reason: string): void => {
+    if (socket !== sock) {
+      destroyQuietly(sock);
+      return;
+    }
 
-  const cleanup = (reason: string): void => {
     rejectAllPending(pending, reason);
     queue.end();
     queue = makeEventQueue();
     registered = false;
 
-    if (rl) { rl.close(); rl = null; }
-    if (socket) { try { socket.destroy(); } catch {} socket = null; }
+    if (stopReading) { stopReading(); stopReading = null; }
+    socket = null;
+    destroyQuietly(sock);
 
     for (const cb of closeListeners) cb();
   };
 
-  const connect = (_url: string, opts?: { timeoutMs?: number }): Promise<Result<void, CdpError>> => {
-    const timeoutMs = opts?.timeoutMs ?? 10_000;
-
-    if (socket && !socket.destroyed && registered) {
-      return Promise.resolve(ok(undefined));
-    }
-
-    return new Promise((resolve) => {
-      let settled = false;
-      const settle = (r: Result<void, CdpError>): void => {
-        if (settled) return;
-        settled = true;
-        resolve(r);
-      };
-
+  const handshake = (timeoutMs: number): Promise<ConnectResult> =>
+    new Promise((resolve) => {
       let sock: Socket;
       try {
-        sock = createConnection(DAEMON_SOCKET_PATH);
+        sock = createConnection(socketPath);
       } catch (e) {
-        settle(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e))));
+        resolve(err(cdpError("transport_closed", e instanceof Error ? e.message : String(e))));
         return;
       }
       socket = sock;
-
+      // The client is kept connected across sessions on purpose (index.ts session_shutdown), so this
+      // socket must not be what keeps the process alive: in `pi -p` it was the last handle standing
+      // and pi never exited (#39). In-flight requests hold their own ref'd timers, so nothing a
+      // caller is awaiting can be dropped by this.
+      sock.unref();
+
+      // The timer is the one ref'd handle for the whole handshake: with the socket unref'd, nothing
+      // else stops the process exiting between TCP connect and the daemon's "registered" reply.
+      // It is cleared only in settle(), so a daemon that accepts but never registers times out.
+      let settled = false;
       const connectTimer = setTimeout(() => {
-        cleanup("Connection timeout");
+        cleanup(sock, "Connection timeout");
         settle(err(cdpError("timeout", `Daemon connection timed out after ${timeoutMs}ms`)));
       }, timeoutMs);
-
-      sock.on("connect", () => {
+      const settle = (r: ConnectResult): void => {
+        if (settled) return;
+        settled = true;
         clearTimeout(connectTimer);
-        rl = createInterface({ input: sock, crlfDelay: Infinity });
+        resolve(r);
+      };
 
-        rl.on("line", (line: string) => {
+      sock.on("connect", () => {
+        stopReading = readLines(sock, (line) => {
+          if (socket !== sock) return;
           const msg = deserialize(line);
           if (!msg) return;
 
-          if (msg.type === "control" && msg.action === "registered" && msg.clientId === clientId) {
-            registered = true;
-            settle(ok(undefined));
-            return;
-          }
-
-          if (msg.type === "control" && msg.action === "shutdown") {
-            cleanup(`Daemon shutting down: ${msg.reason ?? "unknown"}`);
+          if (msg.type === "control") {
+            if (msg.action === "registered" && msg.clientId === clientId) {
+              registered = true;
+              settle(ok(undefined));
+            } else if (msg.action === "shutdown") {
+              cleanup(sock, `Daemon shutting down: ${msg.reason ?? "unknown"}`);
+              settle(err(cdpError("transport_closed", `Daemon refused the connection: ${msg.reason ?? "unknown"}`)));
+            }
             return;
           }
 
@@ -104,38 +118,60 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
               params: msg.params,
               ...(msg.sessionId !== undefined ? { sessionId: msg.sessionId } : {}),
             });
-            return;
           }
         });
 
-        sock.on("error", () => {});
-
-        sock.on("close", () => {
-          clearTimeout(connectTimer);
-          cleanup("Daemon socket closed");
-          settle(err(cdpError("transport_closed", "Daemon socket closed before registration")));
-        });
-
         const regMsg: WireControl = { type: "control", action: "register", clientId };
         sock.write(serialize(regMsg) + "\n");
       });
 
+      // Fires before "close" on any failure, so the message it carries wins over the generic one.
+      // Tearing down here too means state() reads "closed" as soon as the caller sees the error.
       sock.on("error", (e: NodeJS.ErrnoException) => {
-        clearTimeout(connectTimer);
         const msg = e.code === "ENOENT"
           ? "Daemon not running — socket not found"
           : e.message;
+        cleanup(sock, msg);
         settle(err(cdpError("transport_closed", msg)));
       });
+
+      sock.on("close", () => {
+        cleanup(sock, "Daemon socket closed");
+        settle(err(cdpError("transport_closed", "Daemon socket closed before registration")));
+      });
     });
+
+  // `_url` is part of CdpTransport but meaningless here: the daemon discovers and owns the
+  // Chrome endpoint itself, and this transport always dials the daemon's own socket path.
+  const connect = (_url: string, opts?: { timeoutMs?: number }): Promise<ConnectResult> => {
+    const timeoutMs = opts?.timeoutMs ?? 10_000;
+
+    if (socket && !socket.destroyed && registered) {
+      return Promise.resolve(ok(undefined));
+    }
+    if (inFlight) return inFlight;
+
+    const attempt = handshake(timeoutMs).then((r) => {
+      if (inFlight === attempt) inFlight = null;
+      return r;
+    });
+    inFlight = attempt;
+    return attempt;
   };
 
-  const close = async (): Promise<void> => {
-    if (registered && socket && !socket.destroyed) {
+  const close = (): Promise<void> => {
+    const sock = socket;
+    if (!sock) return Promise.resolve();
+    if (registered && !sock.destroyed) {
       const dereg: WireControl = { type: "control", action: "deregister", clientId };
-      try { socket.write(serialize(dereg) + "\n"); } catch {}
+      try {
+        sock.write(serialize(dereg) + "\n");
+      } catch {
+        // The daemon is already gone; cleanup below drops the socket regardless.
+      }
     }
-    cleanup("close() called");
+    cleanup(sock, "close() called");
+    return Promise.resolve();
   };
 
   const request = (
@@ -157,7 +193,7 @@ export const createDaemonTransport = (clientId: string): CdpTransport => {
       id,
       method,
       params,
-      ...(sessionId !== null && sessionId !== undefined ? { sessionId } : {}),
+      ...(sessionId !== null ? { sessionId } : {}),
     };
 
     return sendWithTimeout(pending, id, method, timeoutMs, "Daemon", () => sock.write(serialize(req) + "\n"));