@monoes/monobrowse 1.0.17 → 1.0.19

package/package.json

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

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

@@ -9,10 +9,13 @@
  * services; each test binds/tears down its own listeners.
  */
 
+import { chmodSync, mkdirSync, mkdtempSync, 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';
+import { join } from 'node:path';
 import { afterEach, describe, expect, it } from 'vitest';
-import { launchBrowser } from '../browser/browser.js';
+import { getLaunchedPid, getLaunchedUserDataDir, launchBrowser } from '../browser/browser.js';
 
 const BASE = 23470;
 
@@ -111,3 +114,141 @@ describe('launchBrowser — port scan/attach decisions', () => {
     );
   }, 15000); // generous margin — 10 candidates, each a fast isTcpPortOpen check
 });
+
+// A stand-in for the Chrome binary: like real Chrome given
+// --remote-debugging-port=0, it binds a kernel-assigned port and only then
+// writes that port to <user-data-dir>/DevToolsActivePort.
+const FAKE_CHROME = `#!/usr/bin/env node
+const { createServer } = require('node:http');
+const { writeFileSync } = require('node:fs');
+const { join } = require('node:path');
+const dir = process.argv.find((a) => a.startsWith('--user-data-dir=')).slice('--user-data-dir='.length);
+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' }) : '[]');
+});
+// Start slower than launchBrowser's first poll, so a stale file is read first.
+setTimeout(() => server.listen(0, '127.0.0.1', () => {
+  writeFileSync(join(dir, 'DevToolsActivePort'), server.address().port + '\\n/devtools/browser/fake');
+}), 600);
+`;
+
+describe.skipIf(process.platform === 'win32')(
+  'launchBrowser — port 0 (Chrome picks the port)',
+  () => {
+    it('returns the port its own Chrome reported, never another CDP endpoint', async () => {
+      const dir = mkdtempSync(join(tmpdir(), 'monobrowse-port0-'));
+      const exe = join(dir, 'fake-chrome.cjs');
+      writeFileSync(exe, FAKE_CHROME);
+      chmodSync(exe, 0o755);
+      const profile = join(dir, 'profile');
+      // A Chrome-looking endpoint that is NOT ours, named by a stale
+      // DevToolsActivePort left in the profile dir by an earlier run.
+      const foreign = BASE + 5;
+      const s = createHttpServer((req, res) => {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(req.url === '/json/version' ? JSON.stringify({ Browser: 'Chrome/1.0' }) : '[]');
+      });
+      s.on('connection', (sock) => sockets.push(sock));
+      await new Promise<void>((resolve) => s.listen(foreign, '127.0.0.1', () => resolve()));
+      servers.push(s);
+      mkdirSync(profile);
+      writeFileSync(join(profile, 'DevToolsActivePort'), `${foreign}\n/devtools/browser/stale`);
+
+      let port: number | undefined;
+      try {
+        port = await launchBrowser({ port: 0, userDataDir: profile, executablePath: exe });
+        expect(port).not.toBe(foreign);
+        expect(port).toBeGreaterThan(0);
+        expect(getLaunchedPid(port)).toBeTypeOf('number');
+      } finally {
+        const pid = port === undefined ? undefined : getLaunchedPid(port);
+        if (pid) process.kill(pid, 'SIGKILL');
+        rmSync(dir, { recursive: true, force: true });
+      }
+    });
+
+    it('refuses port 0 without a dedicated userDataDir', async () => {
+      await expect(launchBrowser({ port: 0 })).rejects.toThrow(/requires a dedicated userDataDir/);
+    });
+  },
+);
+
+// A stand-in for the Chrome binary that, unlike FAKE_CHROME above, actually
+// binds the FIXED port it is given via --remote-debugging-port (real Chrome,
+// launched with no --port flag, always resolves to the same literal default
+// 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.
+const FAKE_CHROME_FIXED_PORT = `#!/usr/bin/env node
+const { createServer } = require('node:http');
+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 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' }) : '[]');
+});
+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');
+});
+`;
+
+describe.skipIf(process.platform === 'win32')(
+  'launchBrowser — concurrent launches with no explicit --port (TOCTOU race)',
+  () => {
+    it('two concurrent launches racing for the same default port both succeed, on different ports and profiles', async () => {
+      const dir = mkdtempSync(join(tmpdir(), 'monobrowse-concurrent-'));
+      const exe = join(dir, 'fake-chrome.cjs');
+      writeFileSync(exe, FAKE_CHROME_FIXED_PORT);
+      chmodSync(exe, 0o755);
+      // Both calls target the SAME literal port on purpose: that is exactly
+      // what two real `monomind browse open` invocations with no --port flag
+      // do, since the CLI's `port` option always defaults to the same value
+      // whether or not the user passed it (cli/commands.ts:288).
+      const port = BASE + 10;
+
+      let ports: number[] = [];
+      try {
+        ports = await Promise.all([
+          launchBrowser({ port, executablePath: exe, launchTimeoutMs: 5000 }),
+          launchBrowser({ port, executablePath: exe, launchTimeoutMs: 5000 }),
+        ]);
+      } finally {
+        for (const p of ports) {
+          const pid = getLaunchedPid(p);
+          if (pid) {
+            try {
+              process.kill(pid, 'SIGKILL');
+            } catch {
+              /* already gone */
+            }
+          }
+        }
+        rmSync(dir, { recursive: true, force: true });
+      }
+
+      expect(ports).toHaveLength(2);
+      // The old probe-then-launch race let both calls observe the same
+      // candidate as free and spawn Chrome on it — one bind wins, the
+      // other's Chrome exits before its CDP endpoint opens and the whole
+      // launchBrowser() call rejects. Both resolving at all is the
+      // regression check; landing on different ports (rather than one
+      // silently adopting the other's browser) proves the scan actually
+      // moved on instead of colliding.
+      expect(ports[0]).not.toBe(ports[1]);
+      const dirs = ports.map((p) => getLaunchedUserDataDir(p));
+      expect(dirs[0]).not.toBe(dirs[1]);
+      expect(dirs[0]).toBeTruthy();
+      expect(dirs[1]).toBeTruthy();
+    }, 15000);
+  },
+);

package/src/browser/browser.ts

@@ -1,5 +1,5 @@
 import { execSync, spawn } from 'node:child_process';
-import { existsSync } from 'node:fs';
+import { existsSync, readFileSync, rmSync } from 'node:fs';
 import { connect } from 'node:net';
 import { tmpdir } from 'node:os';
 import { join } from 'node:path';
@@ -128,9 +128,17 @@ const LAUNCH_PORT_SCAN_TRIES = 10;
 
 export async function launchBrowser(config: BrowserConfig = {}): Promise<number> {
   const rawPort = config.port ?? DEFAULT_PORT;
-  // Validate port is in a safe range for localhost CDP debugging
-  if (!Number.isInteger(rawPort) || rawPort < 1024 || rawPort > 65535) {
-    throw new Error(`Invalid port: ${rawPort}. Must be an integer between 1024 and 65535.`);
+  // Port 0 means "let Chrome bind a free port and tell us which" — see
+  // launchOnFreePort. Otherwise validate port is in a safe range for
+  // localhost CDP debugging.
+  if (rawPort === 0) {
+    if (!config.userDataDir) {
+      throw new Error(
+        'port 0 requires a dedicated userDataDir (Chrome reports the port it bound inside it).',
+      );
+    }
+  } else if (!Number.isInteger(rawPort) || rawPort < 1024 || rawPort > 65535) {
+    throw new Error(`Invalid port: ${rawPort}. Must be 0 or an integer between 1024 and 65535.`);
   }
 
   // Every launch/attach is this tool's only chance to notice that a previous
@@ -139,6 +147,8 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   // instance on the port we are about to use is freed before we probe it.
   await reapIdleLaunchedBrowser();
 
+  if (rawPort === 0) return launchOnFreePort(config, 0);
+
   // strictPort: fail fast on the exact requested port, matching the old
   // behavior (Vite has the same escape hatch for the same reason) — for
   // callers that treat the error as a signal ("this port is taken by
@@ -158,19 +168,7 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   for (let i = 0; i < LAUNCH_PORT_SCAN_TRIES && rawPort + i <= 65535; i++)
     candidates.push(rawPort + i);
 
-  // Attach-if-already-Chrome only applies to the EXACT requested port — the
-  // original, deliberate, single-port risk ("don't silently take over an
-  // unrelated real browser that happens to be on this port"). Scanning past
-  // an occupied default must not let that same shortcut attach to a
-  // DIFFERENT Chrome instance the caller never named; forward candidates are
-  // launch-only (skip if anything is there, Chrome or not).
-  if (await isTcpPortOpen(rawPort)) {
-    if (await isChromeIdentity(rawPort)) return rawPort;
-  } else {
-    return launchOnFreePort(config, rawPort);
-  }
-
-  for (const candidate of candidates.slice(1)) {
+  for (const candidate of candidates) {
     // TCP-level check for "is anything at all listening" — isPortOpen()
     // does a full CDP /json fetch, which returns false BOTH for a genuinely
     // free port and for one occupied by a non-CDP process (that ambiguity is
@@ -179,10 +177,39 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
     // socket first tells free and occupied apart up front, so the scan can
     // skip an occupied candidate instead of trying to spawn Chrome on top of
     // it and only discovering the conflict after a timeout.
-    if (!(await isTcpPortOpen(candidate))) return launchOnFreePort(config, candidate);
-    // Occupied (by anything — not just non-Chrome, per the note above) —
-    // try the next candidate instead of failing outright, same as a normal
-    // EADDRINUSE retry would.
+    if (await isTcpPortOpen(candidate)) {
+      // Attach-if-already-Chrome only applies to the EXACT requested port —
+      // the original, deliberate, single-port risk ("don't silently take
+      // over an unrelated real browser that happens to be on this port").
+      // Scanning past an occupied default must not let that same shortcut
+      // attach to a DIFFERENT Chrome instance the caller never named;
+      // forward candidates are launch-only (skip if anything is there,
+      // Chrome or not).
+      if (candidate === rawPort && (await isChromeIdentity(candidate))) return candidate;
+      // Occupied (by anything — not just non-Chrome, per the note above) —
+      // try the next candidate instead of failing outright, same as a
+      // normal EADDRINUSE retry would.
+      continue;
+    }
+    try {
+      return await launchOnFreePort(config, candidate);
+    } catch (err) {
+      const isLastCandidate = candidate === candidates[candidates.length - 1];
+      // isTcpPortOpen() above is a connect() probe, not an atomic claim: two
+      // concurrent launchBrowser() calls with no explicit --port can both
+      // observe the same candidate as free and both spawn Chrome on it
+      // before either binds. One wins; the other's Chrome exits before its
+      // CDP endpoint opens ("Chrome exited before the CDP endpoint opened
+      // ... code=21"). Something is listening on the candidate NOW that
+      // was not a moment ago — a losing race, not a broken Chrome install —
+      // so try the next candidate exactly like an already-occupied one,
+      // instead of failing the whole launch outright. A candidate that
+      // fails with nothing now listening (a real launch failure — bad
+      // executable, sandbox refusal, etc.) is not a race: retrying the
+      // next candidate would only fail the same way, so surface it as-is.
+      if (!isLastCandidate && (await isTcpPortOpen(candidate))) continue;
+      throw err;
+    }
   }
   throw new Error(
     `Ports ${candidates[0]}-${candidates[candidates.length - 1]} are all occupied and port ${candidates[0]} ` +
@@ -190,9 +217,50 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
   );
 }
 
+/** The port Chrome wrote to `<userDataDir>/DevToolsActivePort` once its
+ *  DevTools server was listening, or null if it has not (yet). */
+function readDevToolsActivePort(file: string): number | null {
+  try {
+    const port = Number.parseInt(readFileSync(file, 'utf8').split('\n')[0], 10);
+    return Number.isInteger(port) && port > 0 && port <= 65535 ? port : null;
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Spawn Chrome and wait for its CDP endpoint.
+ *
+ * With a fixed `port`, "our Chrome is up" is inferred from *some* Chrome
+ * answering on 127.0.0.1:<port> — which is not necessarily ours. When the port
+ * is already bound on 127.0.0.1 (a concurrent launch picked the same "free"
+ * port between its probe and Chrome's bind), Chrome does not fail: it logs
+ * `bind() failed: Address already in use` and listens on [::1]:<port>
+ * instead. The poll then accepts the OTHER launcher's browser, both callers
+ * drive one Chrome, and whichever closes first kills the other's connections
+ * ("CDP connection closed") while this launch's own Chrome is orphaned.
+ *
+ * `port: 0` removes the race instead of narrowing it: Chrome asks the kernel
+ * 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.
+ */
 async function launchOnFreePort(config: BrowserConfig, port: number): Promise<number> {
   const chromePath = findChrome(config.executablePath);
-  const userDataDir = config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}`);
+  // 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.
+  const userDataDir =
+    config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}-${process.pid}`);
+  const activePortFile = join(userDataDir, 'DevToolsActivePort');
+  // A reused profile dir may hold a previous run's file naming a port some
+  // other process now owns.
+  if (port === 0) rmSync(activePortFile, { force: true });
 
   const defaultArgs = [
     `--remote-debugging-port=${port}`,
@@ -264,10 +332,21 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
   });
 
   child.unref();
-  if (child.pid) {
-    launchedPids.set(port, child.pid);
-    launchedUserDataDirs.set(port, userDataDir);
-  }
+  const track = (boundPort: number) => {
+    if (!child.pid) return;
+    launchedPids.set(boundPort, child.pid);
+    launchedUserDataDirs.set(boundPort, userDataDir);
+  };
+  // Tracked only once Chrome is CONFIRMED up on `boundPort`, not right after
+  // spawn(). For port !== 0 this used to track(port) unconditionally the
+  // moment the child was spawned, before knowing whether it would actually
+  // win the port — when a racing launchBrowser() call retries a candidate
+  // that a concurrent process also spawned Chrome on (see the retry loop in
+  // launchBrowser), BOTH child processes called track() for the SAME
+  // candidate, and whichever call's spawn happened to run last clobbered the
+  // map entry with its own pid — including the LOSING, about-to-exit
+  // process's pid overwriting the real winner's, corrupting the very map
+  // closeBrowser()'s kill fallback depends on.
 
   const launchTimeout = config.launchTimeoutMs ?? LAUNCH_TIMEOUT;
   const deadline = Date.now() + launchTimeout;
@@ -275,17 +354,34 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     if (earlyFailure) throw earlyFailure;
     await sleep(POLL_INTERVAL);
     if (earlyFailure) throw earlyFailure;
-    if (await isPortOpen(port)) {
-      if (await isChromeIdentity(port)) return port;
+    const boundPort = port === 0 ? readDevToolsActivePort(activePortFile) : port;
+    if (boundPort !== null && (await isPortOpen(boundPort))) {
+      if (await isChromeIdentity(boundPort)) {
+        track(boundPort);
+        return boundPort;
+      }
       throw new Error(
-        `Port ${port} is occupied by a CDP-speaking process that does not identify as Chrome/Chromium. ` +
-          `Refusing to attach — pass a different port or free port ${port}.`,
+        `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}.`,
       );
     }
   }
 
   if (earlyFailure) throw earlyFailure;
 
+  if (port === 0) {
+    // Not tracked under any port yet, so no closeBrowser() could ever reach
+    // it — stop it here rather than leave it running.
+    try {
+      if (child.pid) process.kill(child.pid, 'SIGKILL');
+    } catch {
+      /* already gone */
+    }
+    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
   // "nothing is listening" (real launch failure) from "something non-CDP is
   // squatting the port" (confusing generic timeout otherwise) via a raw TCP probe.

package/src/browser/types.ts

@@ -1,4 +1,6 @@
 export interface BrowserConfig {
+  /** CDP port. 0 lets Chrome bind a free one (requires `userDataDir`); the
+   *  port it bound is launchBrowser's return value. */
   port?: number;
   /** Fail fast if `port` is occupied by anything other than an attachable
    *  Chrome, instead of scanning forward to the next free port. Default false