@monoes/monobrowse 1.0.28 → 2.24.0

package/package.json

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

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

@@ -0,0 +1,128 @@
+/**
+ * #491: two launches that call listen() on the same free port at the same
+ * instant can BOTH lose it on Linux (each socket is marked LISTEN before the
+ * port conflict check, so each sees the other and gets EADDRINUSE). Both
+ * Chromes exit before their CDP endpoint opens and the port is free again
+ * afterwards, so the lost race looks exactly like a Chrome that cannot start.
+ *
+ * The double loss is a kernel timing window (about 1 in 600 races locally),
+ * so these tests reproduce its outcome deterministically instead: a fake
+ * Chrome that exits early without binding on its first start.
+ *
+ * Fixed ports 23440-23449, clear of browser-launch.test.ts (23460-23489) and
+ * reap-idle-browser.test.ts (23490-23499), which run in parallel workers.
+ */
+
+import { execFileSync } from 'node:child_process';
+import { chmodSync, existsSync, mkdtempSync, readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+import { afterEach, describe, expect, it } from 'vitest';
+import { getLaunchedPid, launchBrowser } from '../browser/browser.js';
+
+const BASE = 23440;
+const dirs: string[] = [];
+
+afterEach(() => {
+  for (const dir of dirs.splice(0)) {
+    try {
+      execFileSync('pkill', ['-KILL', '-f', dir]);
+    } catch {
+      /* nothing left running */
+    }
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+/**
+ * A fixed-port fake Chrome. It exits with code 21 before binding anything
+ * on each of its first `lostStarts` starts (counted in a file next to it),
+ * and on every start for `lostPort`, which is what a Chrome that lost the
+ * double-EADDRINUSE race looks like. Otherwise it binds the port and
+ * announces itself like real Chrome.
+ */
+function fakeChrome(lostStarts: number, lostPort = 0): string {
+  const dir = mkdtempSync(join(tmpdir(), 'monobrowse-491-'));
+  dirs.push(dir);
+  const exe = join(dir, 'fake-chrome.cjs');
+  writeFileSync(
+    exe,
+    `#!/usr/bin/env node
+const { createServer } = require('node:http');
+const { existsSync, readFileSync, writeFileSync } = require('node:fs');
+const port = Number(
+  process.argv.find((a) => a.startsWith('--remote-debugging-port=')).slice('--remote-debugging-port='.length),
+);
+const counter = ${JSON.stringify(join(dir, 'starts'))};
+const starts = existsSync(counter) ? Number(readFileSync(counter, 'utf8')) : 0;
+writeFileSync(counter, String(starts + 1));
+if (starts < ${lostStarts} || port === ${lostPort}) process.exit(21);
+setTimeout(() => process.exit(0), 30000).unref();
+const ws = 'ws://127.0.0.1:' + port + '/devtools/browser/fake-' + process.pid;
+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', webSocketDebuggerUrl: ws })
+      : '[]',
+  );
+});
+server.listen(port, '127.0.0.1', () => {
+  process.stderr.write('\\nDevTools listening on ' + ws + '\\n');
+});
+`,
+  );
+  chmodSync(exe, 0o755);
+  return exe;
+}
+
+function startsOf(exe: string): number {
+  const counter = join(exe, '..', 'starts');
+  return existsSync(counter) ? Number(readFileSync(counter, 'utf8')) : 0;
+}
+
+describe.skipIf(process.platform === 'win32')(
+  'launchBrowser — a Chrome that lost the port race with nothing left listening (#491)',
+  () => {
+    it('moves on to the next candidate instead of failing the launch', async () => {
+      const exe = fakeChrome(1);
+      const port = await launchBrowser({ port: BASE, executablePath: exe, launchTimeoutMs: 5000 });
+      try {
+        expect(port).toBe(BASE + 1);
+        expect(startsOf(exe)).toBe(2);
+      } finally {
+        process.kill(getLaunchedPid(port)!, 'SIGKILL');
+      }
+    }, 15000);
+
+    it('two concurrent launches that both lost the same candidate both succeed, on different ports', async () => {
+      // The CI failure's shape: both racers' Chromes exited early on the
+      // first candidate and neither found anything listening there.
+      const exe = fakeChrome(0, BASE + 2);
+      let results: PromiseSettledResult<number>[] = [];
+      try {
+        results = await Promise.allSettled([
+          launchBrowser({ port: BASE + 2, executablePath: exe, launchTimeoutMs: 5000 }),
+          launchBrowser({ port: BASE + 2, executablePath: exe, launchTimeoutMs: 5000 }),
+        ]);
+      } finally {
+        for (const r of results) {
+          const pid = r.status === 'fulfilled' ? getLaunchedPid(r.value) : undefined;
+          if (pid) process.kill(pid, 'SIGKILL');
+        }
+      }
+      for (const r of results) if (r.status === 'rejected') throw r.reason;
+      const ports = results.map((r) => (r as PromiseFulfilledResult<number>).value);
+      expect(ports[0]).not.toBe(ports[1]);
+      expect(ports).not.toContain(BASE + 2);
+    }, 15000);
+
+    it('still surfaces a Chrome that cannot start, after one more attempt', async () => {
+      const exe = fakeChrome(Number.POSITIVE_INFINITY);
+      await expect(
+        launchBrowser({ port: BASE + 5, executablePath: exe, launchTimeoutMs: 5000 }),
+      ).rejects.toThrow(/exited before the CDP endpoint opened on port 23445 \(code=21/);
+      expect(startsOf(exe)).toBe(2);
+    }, 15000);
+  },
+);

package/src/__tests__/chrome-fallback.test.ts

@@ -0,0 +1,74 @@
+/**
+ * #428: an installed browser always wins; monomind's downloaded Chrome (the
+ * registered fallback, or MONOBROWSE_CHROME_PATH for a child process) is used
+ * only when there is none.
+ */
+import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
+
+const present = new Set<string>();
+vi.mock('node:fs', async (orig) => ({
+  ...(await orig<typeof import('node:fs')>()),
+  existsSync: (p: string) => present.has(p),
+}));
+vi.mock('node:child_process', async (orig) => ({
+  ...(await orig<typeof import('node:child_process')>()),
+  execSync: () => {
+    throw new Error('which: nothing found');
+  },
+}));
+
+const { findChrome, resolveChrome, setChromeFallback } = await import(
+  '../browser/browser-discovery.js'
+);
+const { CHROME_EXECUTABLES } = await import('../browser/types.js');
+
+const SYSTEM = CHROME_EXECUTABLES.find((p) => p.startsWith('/usr/bin/')) as string;
+
+beforeEach(() => {
+  present.clear();
+  delete process.env.MONOBROWSE_CHROME_PATH;
+});
+afterEach(() => {
+  setChromeFallback(undefined);
+  delete process.env.MONOBROWSE_CHROME_PATH;
+});
+
+describe('resolveChrome', () => {
+  it('throws the usual error when there is no browser and no fallback', async () => {
+    await expect(resolveChrome()).rejects.toThrow('No supported browser found');
+  });
+
+  it('asks the fallback only when no browser is installed', async () => {
+    const fallback = vi.fn(async () => '/deps/chrome');
+    setChromeFallback(fallback);
+    await expect(resolveChrome()).resolves.toBe('/deps/chrome');
+    expect(fallback).toHaveBeenCalledOnce();
+
+    present.add(SYSTEM);
+    fallback.mockClear();
+    await expect(resolveChrome()).resolves.toBe(SYSTEM);
+    expect(fallback).not.toHaveBeenCalled();
+  });
+
+  it('never falls back for an explicit executablePath', async () => {
+    const fallback = vi.fn(async () => '/deps/chrome');
+    setChromeFallback(fallback);
+    await expect(resolveChrome('/nope/chrome')).rejects.toThrow('Chrome executable not found');
+    expect(fallback).not.toHaveBeenCalled();
+  });
+});
+
+describe('findChrome and MONOBROWSE_CHROME_PATH', () => {
+  it('uses the variable only when no browser is installed', () => {
+    process.env.MONOBROWSE_CHROME_PATH = '/deps/chrome';
+    present.add('/deps/chrome');
+    expect(findChrome()).toBe('/deps/chrome');
+    present.add(SYSTEM);
+    expect(findChrome()).toBe(SYSTEM);
+  });
+
+  it('ignores a variable that points at nothing', () => {
+    process.env.MONOBROWSE_CHROME_PATH = '/deps/missing';
+    expect(() => findChrome()).toThrow('No supported browser found');
+  });
+});

package/src/browser/browser-discovery.ts

@@ -25,11 +25,36 @@ export function findChrome(executablePath?: string): string {
   } catch {
     // ignore
   }
+  // A browser some other tool fetched for us (monomind sets this for its own
+  // child processes). Last, so an installed browser always wins.
+  const fromEnv = process.env.MONOBROWSE_CHROME_PATH;
+  if (fromEnv && existsSync(fromEnv)) return fromEnv;
   throw new Error(
     'No supported browser found. Install Google Chrome, Microsoft Edge, or Chromium — or pass executablePath in BrowserConfig.',
   );
 }
 
+let chromeFallback: (() => Promise<string>) | undefined;
+
+/**
+ * Registers where launchBrowser() gets a browser when findChrome() finds none
+ * (monomind downloads one on first use). Pass undefined to clear it.
+ */
+export function setChromeFallback(fallback: (() => Promise<string>) | undefined): void {
+  chromeFallback = fallback;
+}
+
+/** findChrome(), then the registered fallback when no browser is installed.
+ *  An explicit executablePath never falls back. */
+export async function resolveChrome(executablePath?: string): Promise<string> {
+  try {
+    return findChrome(executablePath);
+  } catch (err) {
+    if (executablePath || !chromeFallback) throw err;
+    return chromeFallback();
+  }
+}
+
 export async function isPortOpen(port: number): Promise<boolean> {
   try {
     await fetchTargets(port);

package/src/browser/browser-launch.ts

@@ -8,11 +8,11 @@ import {
   browserIdOf,
   chromeIdentity,
   fetchBrowserWebSocketUrl,
-  findChrome,
   isChromeIdentity,
   isPortOpen,
   isTcpPortOpen,
   readDevToolsActivePort,
+  resolveChrome,
 } from './browser-discovery.js';
 import { reapIdleLaunchedBrowser } from './browser-lifecycle.js';
 import { launchedPids, launchedUserDataDirs, ownedUserDataDirPorts } from './browser-state.js';
@@ -36,6 +36,9 @@ const POLL_INTERVAL = 200;
  *  behavior). */
 const LAUNCH_PORT_SCAN_TRIES = 10;
 
+/** Chrome's process exited before its CDP endpoint opened. */
+class ChromeExitedEarlyError extends Error {}
+
 export async function launchBrowser(config: BrowserConfig = {}): Promise<number> {
   const rawPort = config.port ?? DEFAULT_PORT;
   // Port 0 means "let Chrome bind a free port and tell us which" — see
@@ -82,6 +85,9 @@ 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);
 
+  // See the catch below: one early Chrome exit on a candidate nobody holds
+  // afterwards is read as a lost port race, not a broken Chrome.
+  let toleratedEarlyExit: ChromeExitedEarlyError | null = null;
   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
@@ -118,10 +124,25 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
       // 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.
+      // fails with nothing now listening is usually a real launch failure
+      // (bad executable, sandbox refusal, etc.) that the next candidate would
+      // only repeat, so it is surfaced as-is.
       if (!isLastCandidate && (await isTcpPortOpen(candidate))) continue;
+      // Usually, but not always (#491): two launches that call listen() on
+      // the same port at the same instant can BOTH lose it on Linux — each
+      // socket is marked LISTEN before the kernel checks the port for
+      // conflicts, so each sees the other and gets EADDRINUSE. Both Chromes
+      // exit early and the port is free again, which is indistinguishable
+      // from a Chrome that cannot start. Move on once; a Chrome that really
+      // cannot start exits the same way on the next candidate, and the first
+      // of the two identical failures is surfaced.
+      if (err instanceof ChromeExitedEarlyError) {
+        if (!isLastCandidate && !toleratedEarlyExit) {
+          toleratedEarlyExit = err;
+          continue;
+        }
+        throw toleratedEarlyExit ?? err;
+      }
       throw err;
     }
   }
@@ -158,7 +179,7 @@ export async function launchBrowser(config: BrowserConfig = {}): Promise<number>
  * 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);
+  const chromePath = await resolveChrome(config.executablePath);
   // 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
@@ -255,7 +276,7 @@ async function launchOnFreePort(config: BrowserConfig, port: number): Promise<nu
     earlyFailure ??= new Error(`Chrome failed to start on port ${port}: ${err.message}`);
   });
   child.on('exit', (code, signal) => {
-    earlyFailure ??= new Error(
+    earlyFailure ??= new ChromeExitedEarlyError(
       `Chrome exited before the CDP endpoint opened on port ${port} ` +
         `(code=${code ?? 'null'}, signal=${signal ?? 'null'})`,
     );

package/src/browser/browser.ts

@@ -3,7 +3,7 @@
 // re-exports everything it used to define, so every existing import path
 // keeps working.
 
-export { isPortOpen } from './browser-discovery.js';
+export { findChrome, isPortOpen, setChromeFallback } from './browser-discovery.js';
 export { launchBrowser } from './browser-launch.js';
 export { closeBrowser, reapIdleLaunchedBrowser } from './browser-lifecycle.js';
 export {