@monoes/monobrowse 1.0.4 → 1.0.5

package/package.json

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

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

@@ -0,0 +1,102 @@
+/**
+ * Unit tests for launchBrowser's port-scan/attach decisions (browser.ts).
+ * Deliberately scoped to branches reachable WITHOUT spawning a real Chrome —
+ * each scenario below resolves via attach or a thrown error before
+ * 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.
+ */
+import { describe, it, expect, afterEach } from 'vitest';
+import { createServer as createTcpServer, type Server as TcpServer, type Socket } from 'net';
+import { createServer as createHttpServer, type Server as HttpServer } from 'http';
+import { launchBrowser } from '../browser/browser.js';
+
+const BASE = 23470;
+
+let servers: Array<TcpServer | HttpServer> = [];
+let sockets: Socket[] = [];
+
+afterEach(async () => {
+  // server.close() only stops accepting NEW connections — it waits for
+  // already-open ones (the fetches that hung until their AbortSignal fired)
+  // to close on their own, which can outlast the test. Destroy explicitly.
+  for (const sock of sockets) sock.destroy();
+  sockets = [];
+  await Promise.all(servers.map(s => new Promise<void>(resolve => s.close(() => resolve()))));
+  servers = [];
+}, 5000);
+
+/** Bind a bare TCP listener — accepts connections but speaks no HTTP/CDP. */
+function occupyNonChrome(port: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const s = createTcpServer(sock => { sockets.push(sock); /* accept and do nothing — no CDP response */ });
+    s.once('error', reject);
+    s.listen(port, '127.0.0.1', () => { servers.push(s); resolve(); });
+  });
+}
+
+/** Bind an HTTP server that answers /json/version like a real Chrome would. */
+function occupyChrome(port: number): Promise<void> {
+  return new Promise((resolve, reject) => {
+    const s = createHttpServer((req, res) => {
+      if (req.url === '/json/version') {
+        res.writeHead(200, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ Browser: 'Chrome/999.0.0.0' }));
+      } else {
+        res.writeHead(404); res.end();
+      }
+    });
+    s.on('connection', sock => sockets.push(sock));
+    s.once('error', reject);
+    s.listen(port, '127.0.0.1', () => { servers.push(s); resolve(); });
+  });
+}
+
+describe('launchBrowser — port scan/attach decisions', () => {
+  it('attaches immediately when the EXACT requested port already identifies as Chrome', async () => {
+    const port = BASE + 0;
+    await occupyChrome(port);
+    await expect(launchBrowser({ port })).resolves.toBe(port);
+  });
+
+  it('strictPort: throws immediately on an occupied non-Chrome requested port, never scans', async () => {
+    const port = BASE + 1;
+    await occupyNonChrome(port);
+    await occupyChrome(port + 1); // would succeed if scanning happened — must not be reached
+    await expect(launchBrowser({ port, strictPort: true }))
+      .rejects.toThrow(/does not identify as Chrome/);
+  });
+
+  it('strictPort: attaches on an occupied Chrome requested port (identical to non-strict)', async () => {
+    const port = BASE + 2;
+    await occupyChrome(port);
+    await expect(launchBrowser({ port, strictPort: true })).resolves.toBe(port);
+  });
+
+  it('all candidates occupied by non-Chrome processes: throws a clear range error', async () => {
+    const port = BASE + 3;
+    // Occupy the full 10-port scan window with non-Chrome listeners.
+    for (let i = 0; i < 10; i++) await occupyNonChrome(port + i);
+    await expect(launchBrowser({ port })).rejects.toThrow(
+      new RegExp(`Ports ${port}-${port + 9} are all occupied`)
+    );
+  }, 15000); // generous margin — 10 candidates, each a fast isTcpPortOpen check
+
+  it('a Chrome instance on a SCANNED (not the originally requested) port is skipped, not attached to', async () => {
+    // Security-relevant case: the attach-if-Chrome shortcut must apply only
+    // to the exact port the caller asked for. A Chrome instance sitting on a
+    // later candidate the caller never named must not be silently attached
+    // to — occupied candidates (Chrome or not) beyond the first are simply
+    // skipped, so if every candidate is occupied the call still fails even
+    // though one of them is an attachable Chrome.
+    const port = BASE + 4;
+    await occupyNonChrome(port);       // requested port: occupied, not Chrome
+    await occupyChrome(port + 1);      // scanned candidate: IS Chrome — must be skipped, not attached
+    for (let i = 2; i < 10; i++) await occupyNonChrome(port + i); // remaining candidates: occupied
+    await expect(launchBrowser({ port })).rejects.toThrow(
+      new RegExp(`Ports ${port}-${port + 9} are all occupied`)
+    );
+  }, 15000); // generous margin — 10 candidates, each a fast isTcpPortOpen check
+});

package/src/browser/browser.ts

@@ -59,7 +59,7 @@ export async function isPortOpen(port: number): Promise<boolean> {
  */
 async function isChromeIdentity(port: number): Promise<boolean> {
   try {
-    const res = await fetch(`http://127.0.0.1:${port}/json/version`);
+    const res = await fetch(`http://127.0.0.1:${port}/json/version`, { signal: AbortSignal.timeout(1000) });
     if (!res.ok) return false;
     const info = (await res.json()) as { Browser?: string };
     return typeof info.Browser === 'string' && /chrom(e|ium)/i.test(info.Browser);
@@ -83,27 +83,73 @@ function isTcpPortOpen(port: number, timeoutMs = 1000): Promise<boolean> {
   });
 }
 
+/** Ports scanned when the requested one is occupied by a non-Chrome process
+ *  (e.g. another local tool that happens to reuse Chrome's conventional CDP
+ *  default, 9222 — mirrors the auto-increment convention this monorepo's own
+ *  dashboard server uses in bindServer/server.mjs). Only occupied-by-a-
+ *  DIFFERENT-process is worked around; an already-attachable Chrome on the
+ *  requested port is still returned as-is (existing "attach, don't relaunch"
+ *  behavior). */
+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.`);
   }
-  const port = rawPort;
-
-  if (await isPortOpen(port)) {
-    // Something CDP-speaking is already there — verify it's actually Chrome/Chromium
-    // before attaching, so we don't silently take over an unrelated real browser
-    // (e.g. the user's own personal Chrome) that happens to be on this port.
-    if (await isChromeIdentity(port)) {
-      return port;
+
+  // 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
+  // something else, bail") rather than consuming the returned port.
+  if (config.strictPort) {
+    if (await isTcpPortOpen(rawPort)) {
+      if (await isChromeIdentity(rawPort)) return rawPort;
+      throw new Error(
+        `Port ${rawPort} is occupied by a process that does not identify as Chrome/Chromium. ` +
+        `Refusing to attach — pass a different port or free port ${rawPort}.`
+      );
     }
-    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}.`
-    );
+    return launchOnFreePort(config, rawPort);
+  }
+
+  const candidates: 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)) {
+    // 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
+    // exactly what the post-spawn isTcpPortOpen fallback below exists to
+    // resolve, the hard way, after a 10s launch timeout). Checking the raw
+    // 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.
   }
+  throw new Error(
+    `Ports ${candidates[0]}-${candidates[candidates.length - 1]} are all occupied and port ${candidates[0]} ` +
+    `isn't a Chrome/Chromium instance to attach to. Pass a different --port.`
+  );
+}
 
+async function launchOnFreePort(config: BrowserConfig, port: number): Promise<number> {
   const chromePath = findChrome(config.executablePath);
   const userDataDir = config.userDataDir ?? join(tmpdir(), `monomind-browser-${port}`);
 

package/src/browser/types.ts

@@ -1,5 +1,10 @@
 export interface BrowserConfig {
   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
+   *  (scan) — set true for callers that treat the occupied-port error as a
+   *  signal rather than consuming launchBrowser's returned port. */
+  strictPort?: boolean;
   headless?: boolean;
   executablePath?: string;
   userDataDir?: string;