@monoes/monobrowse 1.0.25 → 1.0.26

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@monoes/monobrowse",
-  "version": "1.0.25",
+  "version": "1.0.26",
   "description": "Native browser automation via Chrome DevTools Protocol — the engine powering monomind browse",
   "type": "module",
   "bin": {

package/src/__tests__/browser-launch.test.ts

@@ -5,12 +5,13 @@
  * launchBrowser would ever exec a browser binary, so these run fast and
  * don't depend on Chrome being installed in CI.
  *
- * Fixed port range (23470-23479) chosen to avoid colliding with real
- * services; each test binds/tears down its own listeners.
+ * Fixed port range (23460-23489) chosen to avoid colliding with real
+ * services and with reap-idle-browser.test.ts's 23490-23499, which runs in a
+ * parallel worker; each test binds/tears down its own listeners.
  */
 
 import { execFileSync } from 'node:child_process';
-import { chmodSync, mkdirSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
+import { chmodSync, mkdirSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
 import { createServer as createHttpServer, type Server as HttpServer } from 'node:http';
 import { createServer as createTcpServer, type Socket, type Server as TcpServer } from 'node:net';
 import { tmpdir } from 'node:os';
@@ -310,25 +311,33 @@ describe.skipIf(process.platform === 'win32')(
 // port too — see cli/commands.ts's `port` option default). If the bind
 // fails (another process already has it), it exits the way real Chrome does
 // when a concurrent launch wins the same "free-looking" port: before its
-// CDP endpoint ever opens.
+// CDP endpoint ever opens. Like real Chrome on a fixed port, it writes no
+// DevToolsActivePort; it announces its browser websocket on stderr, with an
+// id unique to this process that /json/version reports too.
 const FAKE_CHROME_FIXED_PORT = `#!/usr/bin/env node
 ${FIXTURE_WATCHDOG}const { createServer } = require('node:http');
+const { randomUUID } = require('node:crypto');
 const { writeFileSync, mkdirSync } = require('node:fs');
 const { join } = require('node:path');
 const port = Number(
   process.argv.find((a) => a.startsWith('--remote-debugging-port=')).slice('--remote-debugging-port='.length),
 );
 const dir = process.argv.find((a) => a.startsWith('--user-data-dir=')).slice('--user-data-dir='.length);
+const ws = 'ws://127.0.0.1:' + port + '/devtools/browser/' + randomUUID();
 const server = createServer((req, res) => {
   res.writeHead(200, { 'Content-Type': 'application/json' });
-  res.end(req.url === '/json/version' ? JSON.stringify({ Browser: 'Chrome/999.0.0.0' }) : '[]');
+  res.end(
+    req.url === '/json/version'
+      ? JSON.stringify({ Browser: 'Chrome/999.0.0.0', webSocketDebuggerUrl: ws })
+      : '[]',
+  );
 });
 server.on('error', () => {
   process.exit(21);
 });
 server.listen(port, '127.0.0.1', () => {
   mkdirSync(dir, { recursive: true });
-  writeFileSync(join(dir, 'DevToolsActivePort'), port + '\\n/devtools/browser/fake');
+  process.stderr.write('\\nDevTools listening on ' + ws + '\\n');
 });
 `;
 
@@ -385,5 +394,68 @@ describe.skipIf(process.platform === 'win32')(
       expect(dirs[0]).toBeTruthy();
       expect(dirs[1]).toBeTruthy();
     }, 15000);
+
+    it('a launch whose Chrome is still booting does not adopt a concurrent launch that took the port', async () => {
+      // The loaded-machine shape of the race above, made deterministic: both
+      // launches probe the port as free, the "fast" Chrome binds it first,
+      // and the "slow" one is still starting when its poll finds a Chrome
+      // answering there. That Chrome is not the slow launch's own, so it
+      // must not be returned — nor may the slow launch record its own pid
+      // (about to exit on the lost bind) under the fast launch's port.
+      const dir = fixtureDir('monobrowse-adopt-');
+      const fast = join(dir, 'fast-chrome.cjs');
+      const slow = join(dir, 'slow-chrome.cjs');
+      writeFileSync(fast, fixedPortChrome(500));
+      writeFileSync(slow, fixedPortChrome(2500));
+      chmodSync(fast, 0o755);
+      chmodSync(slow, 0o755);
+      // Below BASE: this file's fixed ports, clear of the kernel's
+      // ephemeral range, where another test's listen(0) server can land on
+      // the candidate the slow launch scans on to.
+      const port = BASE - 10;
+
+      let results: PromiseSettledResult<number>[] = [];
+      try {
+        results = await Promise.allSettled([
+          launchBrowser({ port, executablePath: fast, launchTimeoutMs: 10_000 }),
+          launchBrowser({ port, executablePath: slow, launchTimeoutMs: 10_000 }),
+        ]);
+      } finally {
+        for (const r of results) {
+          const pid = r.status === 'fulfilled' ? getLaunchedPid(r.value) : undefined;
+          if (pid) {
+            try {
+              process.kill(pid, 'SIGKILL');
+            } catch {
+              /* already gone */
+            }
+          }
+        }
+      }
+
+      const [fastResult, slowResult] = results;
+      expect(fastResult).toEqual({ status: 'fulfilled', value: port });
+      if (slowResult.status === 'rejected') throw slowResult.reason;
+      expect(slowResult.value).not.toBe(port);
+      // The pid tracked for the port is the Chrome that actually serves it.
+      const fastDir = getLaunchedUserDataDir(port)!;
+      expect(fastDir).toBeTruthy();
+      expect(getLaunchedPid(port)).toBe(Number(readFileSync(join(fastDir, 'pid'), 'utf8')));
+    }, 20_000);
   },
 );
+
+/** FAKE_CHROME_FIXED_PORT that waits `delayMs` before binding, and records
+ *  its own pid in its profile dir. */
+function fixedPortChrome(delayMs: number): string {
+  return FAKE_CHROME_FIXED_PORT.replace(
+    'mkdirSync(dir, { recursive: true });',
+    `mkdirSync(dir, { recursive: true });
+  writeFileSync(join(dir, 'pid'), String(process.pid));`,
+  )
+    .replace(
+      "server.listen(port, '127.0.0.1', () => {",
+      "setTimeout(() => server.listen(port, '127.0.0.1', () => {",
+    )
+    .replace(/\}\);\n$/, `}), ${delayMs});\n`);
+}

package/src/__tests__/launch-close-settle.test.ts

@@ -27,11 +27,18 @@
  *      manual repro. vi.useFakeTimers() (used throughout close-browser.test.ts)
  *      cannot catch this class of bug, because fake timers do not model real
  *      event-loop-drain semantics — hence a dedicated, real-timer test here.
+ *
+ * Ports come from the OS (listen on 0), never a fixed number (#351): these
+ * tests used 23495-23497, inside reap-idle-browser.test.ts's 23490-23499
+ * range, whose fake Chrome endpoints run in a parallel worker. A spawn that
+ * failed on 23495 while that file had 23495 bound looked like a lost launch
+ * race to launchBrowser, which moved on and reported port 23496 instead.
  */
 
 import { spawn } from 'node:child_process';
 import { chmodSync, writeFileSync } from 'node:fs';
 import { mkdir, mkdtemp, rm, writeFile } from 'node:fs/promises';
+import { createServer } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
 import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -88,6 +95,19 @@ afterEach(async () => {
   await rm(tempDir, { recursive: true, force: true });
 });
 
+/** A port nothing is listening on, picked by the kernel from its ephemeral
+ *  range — which the fixed-port fixtures of other test files stay below. */
+function freePort(): Promise<number> {
+  return new Promise((resolve, reject) => {
+    const server = createServer();
+    server.once('error', reject);
+    server.listen(0, '127.0.0.1', () => {
+      const { port } = server.address() as { port: number };
+      server.close(() => resolve(port));
+    });
+  });
+}
+
 async function writePersistedPort(port: number, pid: number, savedAt: number): Promise<void> {
   const dir = join(tempDir, '.monomind', 'monobrowse');
   await mkdir(dir, { recursive: true });
@@ -118,21 +138,22 @@ describe('#314: launchBrowser settles instead of hanging when Chrome fails to st
     // "file not found" that launchBrowser would reject before ever exec'ing.
     writeFileSync(fake, 'not an executable\n');
     chmodSync(fake, 0o644);
+    const port = await freePort();
 
     const start = Date.now();
     await expect(
-      launchBrowser({ executablePath: fake, port: 23495, launchTimeoutMs: 3000 }),
-    ).rejects.toThrow(/Chrome failed to start on port 23495/);
+      launchBrowser({ executablePath: fake, port, launchTimeoutMs: 10_000 }),
+    ).rejects.toThrow(`Chrome failed to start on port ${port}: `);
     // Without a child 'error' listener, this used to depend entirely on
     // whether something outside this function happened to intercept the
     // resulting uncaught exception (a bare node:test process has nothing
     // that does — see the module doc comment); where it happened not to
     // crash the process outright, the promise still only ever settled by
     // burning the full launchTimeoutMs. The fix rejects as soon as the
-    // spawn error fires, so this must land in well under a second, not
-    // ride the 3000ms timeout out.
-    expect(Date.now() - start).toBeLessThan(1000);
-  }, 8000);
+    // spawn error fires, so this must land well inside the 10s timeout
+    // rather than ride it out — with room for a loaded machine.
+    expect(Date.now() - start).toBeLessThan(5000);
+  }, 20_000);
 
   it('rejects with a clear message when Chrome exits immediately instead of opening its CDP port', async () => {
     vi.resetModules();
@@ -140,18 +161,19 @@ describe('#314: launchBrowser settles instead of hanging when Chrome fails to st
     const fake = join(tempDir, 'chrome.sh');
     writeFileSync(fake, '#!/bin/sh\nexit 1\n');
     chmodSync(fake, 0o755);
+    const port = await freePort();
 
     await expect(
-      launchBrowser({ executablePath: fake, port: 23496, launchTimeoutMs: 3000 }),
-    ).rejects.toThrow(/Chrome exited before the CDP endpoint opened on port 23496/);
-  }, 8000);
+      launchBrowser({ executablePath: fake, port, launchTimeoutMs: 10_000 }),
+    ).rejects.toThrow(`Chrome exited before the CDP endpoint opened on port ${port} `);
+  }, 20_000);
 });
 
 describe('#314: closeBrowser settles under the real event loop, not fake timers', () => {
   it('resolves promptly when nothing else is pinning the event loop', async () => {
     vi.resetModules();
     const { closeBrowser } = await import('../browser/browser.js');
-    const port = 23497;
+    const port = await freePort();
 
     // A real, short-lived child — not Chrome, just something with a genuine,
     // observable exit so process.kill(pid, 0) behaves for real and there is

package/src/browser/browser.ts

@@ -1,4 +1,5 @@
 import { execSync, spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
 import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { connect } from 'node:net';
 import { tmpdir } from 'node:os';
@@ -258,19 +259,27 @@ function readDevToolsActivePort(file: string): number | null {
  * for a free port at bind time — atomic, nothing to collide on — and writes
  * the port it got to DevToolsActivePort in its own (caller-dedicated) profile
  * directory, which is proof the endpoint is the process we spawned.
+ *
+ * A fixed port needs its own proof, since Chrome writes DevToolsActivePort
+ * only for port 0. Once listening, Chrome prints `DevTools listening on
+ * ws://…/devtools/browser/<id>` to stderr, and `<id>` is unique to that
+ * browser process, the same one `/json/version` reports. An endpoint is
+ * adopted only when it reports the id our own child printed. Without that
+ * check, a launch whose Chrome was still booting found a concurrent
+ * launch's Chrome on the shared port and returned it, recording its own
+ * doomed pid there. It also covers Chrome's [::1] fallback described above.
  */
 async function launchOnFreePort(config: BrowserConfig, port: number): Promise<number> {
   const chromePath = findChrome(config.executablePath);
-  // Suffixed with our own pid: two concurrent launches that both probe the
-  // same candidate port as free (the race this function exists to survive —
-  // see the retry-on-collision caller above) briefly run Chrome with
-  // *identical* --user-data-dir values if it were derived from the port
-  // alone, sharing a profile directory (lock files, preferences, the
-  // DevToolsActivePort file itself) between two unrelated Chrome processes
-  // for as long as the loser stays alive. Different processes always have
-  // different pids, so this can never collide even when the port does.
+  // Unique per launch, not just per port and pid: two concurrent launches
+  // that both probe the same candidate port as free (the race this function
+  // exists to survive — see the retry-on-collision caller above) would
+  // otherwise share one profile directory (lock files, preferences, the
+  // DevToolsActivePort file itself) — including two launches from the same
+  // process, where a pid suffix alone is identical.
   const userDataDir =
-    config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}-${process.pid}`);
+    config.userDataDir ??
+    join(tmpdir(), `monomind-browser-${port}-${process.pid}-${randomUUID().slice(0, 8)}`);
   const activePortFile = join(userDataDir, 'DevToolsActivePort');
   // A reused profile dir may hold a previous run's file naming a port some
   // other process now owns.
@@ -317,8 +326,26 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   const args = [...defaultArgs, ...callerArgs];
   const child = spawn(chromePath, args, {
     detached: true,
-    stdio: 'ignore',
+    // stderr carries the fixed-port ownership proof (see above). The pipe is
+    // closed as soon as this launch settles, so a Chrome that outlives us
+    // never blocks writing to it.
+    stdio: port === 0 ? 'ignore' : ['ignore', 'ignore', 'pipe'],
   });
+  let announcedBrowserId: string | null = null;
+  if (child.stderr) {
+    let stderrTail = '';
+    child.stderr.setEncoding('utf8');
+    child.stderr.on('data', (chunk: string) => {
+      if (announcedBrowserId) return;
+      stderrTail = (stderrTail + chunk).slice(-4096);
+      announcedBrowserId = browserIdOf(
+        /DevTools listening on (ws:\/\/\S+)\r?\n/.exec(stderrTail)?.[1],
+      );
+    });
+    child.stderr.on('error', () => {
+      /* closed under us — nothing to read */
+    });
+  }
 
   // Without this, a spawn failure (e.g. EACCES/ENOENT — chromePath exists per
   // findChrome()'s existsSync check but isn't actually executable, or is
@@ -362,8 +389,8 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   // process's pid overwriting the real winner's, corrupting the very map
   // closeBrowser()'s kill fallback depends on.
 
-  // With port 0 a refused or timed-out launch is not tracked under any port,
-  // so no closeBrowser() could ever reach it — stop it rather than leave it
+  // A refused or timed-out launch is not tracked under any port, so no
+  // closeBrowser() could ever reach it — stop it rather than leave it
   // running.
   const killUntracked = () => {
     try {
@@ -373,52 +400,83 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     }
   };
 
+  // Our own Chrome, not just some Chrome, is serving `boundPort`. For port 0
+  // the port came from our own profile's DevToolsActivePort, so it is.
+  const isOwnEndpoint = async (boundPort: number): Promise<boolean> => {
+    if (port === 0) return true;
+    if (!announcedBrowserId) return false;
+    const wsUrl = await fetchBrowserWebSocketUrl(boundPort).catch(() => null);
+    return browserIdOf(wsUrl ?? undefined) === announcedBrowserId;
+  };
+
   const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
   const deadline = Date.now() + launchTimeout;
-  while (Date.now() < deadline) {
-    if (earlyFailure) throw earlyFailure;
-    await sleep(POLL_INTERVAL);
-    if (earlyFailure) throw earlyFailure;
-    const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
-    if (boundPort !== null && (await isPortOpen(boundPort))) {
-      const identity = await chromeIdentity(boundPort);
-      if (identity === 'chrome') {
-        track(boundPort);
-        return boundPort;
+  try {
+    while (Date.now() < deadline) {
+      if (earlyFailure) throw earlyFailure;
+      await sleep(POLL_INTERVAL);
+      if (earlyFailure) throw earlyFailure;
+      const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
+      if (boundPort !== null && (await isPortOpen(boundPort))) {
+        const identity = await chromeIdentity(boundPort);
+        if (identity === 'chrome') {
+          if (await isOwnEndpoint(boundPort)) {
+            track(boundPort);
+            return boundPort;
+          }
+          // Some Chrome answers on the port, but not the one we started: a
+          // concurrent launch's, or ours before its stderr line arrived. Our
+          // child exiting (it lost the bind) or the deadline decides.
+          continue;
+        }
+        // A Chrome that has only just opened its endpoint, on a loaded
+        // machine, can answer /json/list (no timeout) yet miss the identity
+        // check's 1 s timeout on /json/version. That says nothing about who is
+        // listening — keep polling rather than refuse our own Chrome.
+        if (identity === 'unknown') continue;
+        killUntracked();
+        throw new Error(
+          `Port ${boundPort} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
+            `Refusing to attach — pass a different port or free port ${boundPort}.`,
+        );
       }
-      // A Chrome that has only just opened its endpoint, on a loaded
-      // machine, can answer /json/list (no timeout) yet miss the identity
-      // check's 1 s timeout on /json/version. That says nothing about who is
-      // listening — keep polling rather than refuse our own Chrome.
-      if (identity === 'unknown') continue;
-      if (port === 0) killUntracked();
+    }
+
+    if (earlyFailure) throw earlyFailure;
+    killUntracked();
+
+    if (port === 0) {
       throw new Error(
-        `Port ${boundPort} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
-          `Refusing to attach — pass a different port or free port ${boundPort}.`,
+        `Chrome did not report a CDP port in ${activePortFile} within ${launchTimeout}ms`,
       );
     }
-  }
 
-  if (earlyFailure) throw earlyFailure;
-
-  if (port === 0) {
-    killUntracked();
-    throw new Error(
-      `Chrome did not report a CDP port in ${activePortFile} within ${launchTimeout}ms`,
-    );
-  }
+    // Timed out waiting for our Chrome to come up on the port. Distinguish
+    // "another Chrome holds it", "nothing is listening" (real launch failure)
+    // and "something non-CDP is squatting the port" (confusing generic
+    // timeout otherwise).
+    if (await isChromeIdentity(port)) {
+      throw new Error(
+        `Port ${port} is held by a Chrome/Chromium this launch did not start (a concurrent launch took it).`,
+      );
+    }
+    if (await isTcpPortOpen(port)) {
+      throw new Error(
+        `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${launchTimeout}ms). ` +
+          `Free the port or pass a different one.`,
+      );
+    }
 
-  // Timed out waiting for our Chrome to come up on the port. Distinguish
-  // "nothing is listening" (real launch failure) from "something non-CDP is
-  // squatting the port" (confusing generic timeout otherwise) via a raw TCP probe.
-  if (await isTcpPortOpen(port)) {
-    throw new Error(
-      `Port ${port} is occupied by a non-Chrome process (TCP connection succeeds but no CDP response within ${launchTimeout}ms). ` +
-        `Free the port or pass a different one.`,
-    );
+    throw new Error(`Chrome failed to start on port ${port} within ${launchTimeout}ms`);
+  } finally {
+    child.stderr?.destroy();
   }
+}
 
-  throw new Error(`Chrome failed to start on port ${port} within ${launchTimeout}ms`);
+/** The per-process id in a browser-level CDP websocket URL
+ *  (`ws://host:port/devtools/browser/<id>`), or null. */
+function browserIdOf(wsUrl: string | undefined): string | null {
+  return wsUrl?.match(/\/devtools\/browser\/([^/?#\s]+)/)?.[1] ?? null;
 }
 
 export async function enableSessionDomains(client: CdpClient, sessionId: string): Promise<void> {