@monoes/monobrowse 1.0.26 → 1.0.28

package/dist/src/browser/browser-launch.js

@@ -0,0 +1,341 @@
+// Split out of browser.ts (file-size sweep). Pure move: no behaviour change.
+import { spawn } from 'node:child_process';
+import { randomUUID } from 'node:crypto';
+import { rmSync } from 'node:fs';
+import { join } from 'node:path';
+import { browserIdOf, chromeIdentity, fetchBrowserWebSocketUrl, findChrome, isChromeIdentity, isPortOpen, isTcpPortOpen, readDevToolsActivePort, } from './browser-discovery.js';
+import { reapIdleLaunchedBrowser } from './browser-lifecycle.js';
+import { launchedPids, launchedUserDataDirs, ownedUserDataDirPorts } from './browser-state.js';
+import { launchProfileDirPath, removeOwnedProfileDir, sweepStaleProfileDirs, } from './profile-dir.js';
+const DEFAULT_PORT = 9222;
+const LAUNCH_TIMEOUT = 10_000;
+const POLL_INTERVAL = 200;
+/** 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 = {}) {
+    const rawPort = config.port ?? DEFAULT_PORT;
+    // 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
+    // session abandoned a browser on a CDP port and never gave it back — there
+    // is no daemon to do it on a timer. Bounded and non-throwing; a stale
+    // instance on the port we are about to use is freed before we probe it.
+    await reapIdleLaunchedBrowser();
+    // Same reasoning for temp profile dirs (#395): a process that crashed or
+    // was killed never deleted the one its browser used. Only dead, idle,
+    // unused dirs of our own naming go — see sweepStaleProfileDirs.
+    await sweepStaleProfileDirs();
+    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
+    // 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}.`);
+        }
+        return launchOnFreePort(config, rawPort);
+    }
+    const candidates = [];
+    for (let i = 0; i < LAUNCH_PORT_SCAN_TRIES && rawPort + i <= 65535; i++)
+        candidates.push(rawPort + i);
+    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
+        // 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)) {
+            // 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]} ` +
+        `isn't a Chrome/Chromium instance to attach to. Pass a different --port.`);
+}
+/**
+ * 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.
+ *
+ * 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, port) {
+    const chromePath = findChrome(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
+    // 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 ?? launchProfileDirPath(port, randomUUID().slice(0, 8));
+    // A dir we created is deleted once its browser is gone (#395); a
+    // caller-supplied one only when the caller says it made it for us.
+    const ownsUserDataDir = config.userDataDir === undefined || config.ownsUserDataDir === true;
+    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}`,
+        `--user-data-dir=${userDataDir}`,
+        '--no-first-run',
+        '--no-default-browser-check',
+        '--disable-background-networking',
+        '--disable-client-side-phishing-detection',
+        '--disable-default-apps',
+        '--disable-extensions',
+        '--disable-hang-monitor',
+        '--disable-popup-blocking',
+        '--disable-prompt-on-repost',
+        '--disable-sync',
+        '--disable-translate',
+        '--metrics-recording-only',
+        '--safebrowsing-disable-auto-update',
+        '--password-store=basic',
+        '--use-mock-keychain',
+    ];
+    if (config.headless !== false) {
+        defaultArgs.push('--headless=new');
+    }
+    // Chrome's setuid sandbox cannot initialise on most CI runners and
+    // containers, so the process dies during startup and the CDP endpoint never
+    // opens. The launch below then burns its whole timeout before reporting a
+    // generic failure, which reads as a hang rather than "Chrome could not
+    // start". Disabling the sandbox is the standard remedy and is scoped to CI
+    // so a real user's browser keeps it. --disable-dev-shm-usage goes with it:
+    // a container's default /dev/shm is 64MB, which Chrome exhausts and then
+    // crashes the same way.
+    if (process.env.CI) {
+        defaultArgs.push('--no-sandbox', '--disable-dev-shm-usage');
+    }
+    // Cap caller-supplied args to prevent memory exhaustion via huge argument arrays
+    const callerArgs = (config.args ?? []).slice(0, 50);
+    const args = [...defaultArgs, ...callerArgs];
+    const child = spawn(chromePath, args, {
+        detached: true,
+        // 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 = null;
+    if (child.stderr) {
+        let stderrTail = '';
+        child.stderr.setEncoding('utf8');
+        child.stderr.on('data', (chunk) => {
+            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
+    // removed between the check and exec) fires Node's 'error' event on the
+    // next tick. With no listener, Node throws it as an uncaught exception and
+    // the whole process goes down — which strands this function's promise
+    // forever pending rather than rejecting it (issue #314: node:test reports
+    // that as "cancelledByParent" / "still pending" because nothing here ever
+    // got the chance to settle it). Recording the failure and having the poll
+    // loop below notice it turns that crash into a normal rejection. 'exit'
+    // covers the twin case: Chrome execs fine but the process itself dies
+    // immediately (missing shared libraries, a container's sandbox refusing
+    // it, etc.) — that fires 'exit', not 'error', and without this the poll
+    // loop would just burn its whole timeout probing a port nothing will ever
+    // open on.
+    let earlyFailure = null;
+    child.on('error', (err) => {
+        earlyFailure ??= new Error(`Chrome failed to start on port ${port}: ${err.message}`);
+    });
+    child.on('exit', (code, signal) => {
+        earlyFailure ??= new Error(`Chrome exited before the CDP endpoint opened on port ${port} ` +
+            `(code=${code ?? 'null'}, signal=${signal ?? 'null'})`);
+    });
+    child.unref();
+    const track = (boundPort) => {
+        if (!child.pid)
+            return;
+        launchedPids.set(boundPort, child.pid);
+        launchedUserDataDirs.set(boundPort, userDataDir);
+        if (ownsUserDataDir)
+            ownedUserDataDirPorts.add(boundPort);
+        else
+            ownedUserDataDirPorts.delete(boundPort);
+    };
+    // 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.
+    // 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 {
+            if (child.pid)
+                process.kill(child.pid, 'SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    };
+    // 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) => {
+        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;
+    let launched = false;
+    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);
+                        launched = true;
+                        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}.`);
+            }
+        }
+        if (earlyFailure)
+            throw earlyFailure;
+        killUntracked();
+        if (port === 0) {
+            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.`);
+        }
+        throw new Error(`Chrome failed to start on port ${port} within ${launchTimeout}ms`);
+    }
+    finally {
+        child.stderr?.destroy();
+        // A failed launch (lost port race, refusal, timeout) is never tracked,
+        // so no close will ever clean its profile — and the port-scan retry in
+        // launchBrowser can make several of these per call.
+        if (!launched && ownsUserDataDir)
+            await removeOwnedProfileDir(userDataDir, { pid: child.pid });
+    }
+}
+function sleep(ms) {
+    return new Promise((r) => setTimeout(r, ms));
+}
+//# sourceMappingURL=browser-launch.js.map

package/dist/src/browser/browser-launch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-launch.js","sourceRoot":"","sources":["../../../src/browser/browser-launch.ts"],"names":[],"mappings":"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"}

package/dist/src/browser/browser-lifecycle.d.ts

@@ -0,0 +1,57 @@
+import { CdpClient } from './cdp.js';
+/**
+ * Cleanly terminate a Chrome/Chromium instance we launched on `port`.
+ * Sends the `Browser.close` CDP command (the correct graceful shutdown —
+ * closes all tabs and exits the process cleanly) over `client`'s connection.
+ * If that command fails, times out, or the connection is already gone,
+ * falls back to killing the tracked PID directly so a headed/interactive
+ * browser window (e.g. one spawned for a login/CAPTCHA flow) never lingers
+ * as a visible, authenticated, still-debuggable orphan process.
+ *
+ * On the graceful path this resolves only once the process is actually gone,
+ * or after force-killing it when it outlasts PROCESS_EXIT_TIMEOUT_MS. Chrome
+ * acknowledges `Browser.close` well before it exits, and this used to return
+ * on the ack with an unref'd 1s timer as the only force-kill — so it resolved
+ * while Chrome was still running and holding its port and its profile's
+ * singleton lock, and if the caller's process exited first the kill never
+ * happened at all. Callers reasonably read a resolved close() as "that
+ * browser is gone"; on the graceful path it now means that.
+ *
+ * A profile directory monobrowse created for that browser (the default temp
+ * profile, or a CLI session's — never a caller-supplied one) is deleted once
+ * the process is gone, on both paths (#395). In a fresh process the dir and
+ * its ownership come from the persisted session record.
+ */
+export declare function closeBrowser(client: CdpClient, port: number): Promise<void>;
+/**
+ * Give back the CDP port of a browser we launched that nothing is using any
+ * more. A launched Chrome is deliberately detached and unref'd so it outlives
+ * the command that spawned it and later commands can reattach — but nothing
+ * reaped it afterwards, so an abandoned session kept listening on its port
+ * (9222 by convention, which other local tools want) indefinitely. A foreign
+ * CDP server *answers* there rather than refusing the connection, so those
+ * tools retry the wrong port and report misleading errors instead of moving on.
+ *
+ * Nothing long-lived exists to run this on a timer — every CLI command is its
+ * own short-lived process — so it runs at the next launch/attach instead
+ * (see launchBrowser). A browser is reaped only when ALL of these hold:
+ *   - the persisted session says WE launched it — `connect` records
+ *     launched:false for a browser that belongs to the user, never touched;
+ *   - that session is older than IDLE_REAP_AFTER_MS;
+ *   - the CDP endpoint still answers and reports ZERO targets. An open tab,
+ *     or a client attached to one (Chrome drops webSocketDebuggerUrl from an
+ *     attached target but still lists it), means the session is live and
+ *     reattach-across-commands must keep working.
+ *
+ * Shutdown goes through closeBrowser() on the browser-level websocket — the
+ * only connection left once every target is gone — so a recycled PID can
+ * never be signaled by mistake: graceful `Browser.close` reaches whatever is
+ * actually listening on that port, at any age, and the persisted PID is only
+ * ever used for closeBrowser's own age-bounded force-kill.
+ *
+ * Never throws: a failed reap must not stop a launch. Returns the reaped
+ * port, or null when there was nothing to reap. Sessions are per-port
+ * (#318), so every recorded one is considered, not just the newest.
+ */
+export declare function reapIdleLaunchedBrowser(): Promise<number | null>;
+//# sourceMappingURL=browser-lifecycle.d.ts.map

package/dist/src/browser/browser-lifecycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-lifecycle.d.ts","sourceRoot":"","sources":["../../../src/browser/browser-lifecycle.ts"],"names":[],"mappings":"AAIA,OAAO,EAAE,SAAS,EAAgB,MAAM,UAAU,CAAC;AAuBnD;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,wBAAsB,YAAY,CAAC,MAAM,EAAE,SAAS,EAAE,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAkFjF;AAgCD;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6BG;AACH,wBAAsB,uBAAuB,IAAI,OAAO,CAAC,MAAM,GAAG,IAAI,CAAC,CAOtE"}