browser-debugger-cli 0.7.1 → 0.8.0

package/dist/daemon/server/SocketServer.js

@@ -1,66 +1,167 @@
-import { unlinkSync } from 'fs';
+import { linkSync, lstatSync, unlinkSync } from 'fs';
 import { createServer } from 'net';
+import { DaemonError } from '../errors.js';
+import { probeDaemonSocket } from '../../session/daemonSocket.js';
 import { createLogger } from '../../ui/logging/index.js';
+import { getErrorMessage } from '../../utils/errors.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+/** Unix socket path limit (sun_path is 104 bytes on macOS incl. NUL; 108 on Linux). */
+const MAX_SOCKET_PATH_BYTES = 103;
+/** Error code thrown when another daemon already owns the socket path. */
+export const DAEMON_ALREADY_RUNNING_CODE = 'DAEMON_ALREADY_RUNNING';
 /**
  * Thin wrapper around Node's net.Server that centralizes socket lifecycle
  * management (setup, connection tracking, teardown).
+ *
+ * Claims the socket path exclusively: the server listens on a private
+ * temporary path and then hard-links it to the public path. `link()` fails
+ * with EEXIST if the path exists, so two daemons can never both own it.
+ * On shutdown the public path is removed only if it still refers to our
+ * socket inode.
  */
 export class SocketServer {
     server = null;
     sockets = new Set();
     socketPath = null;
+    socketInode = null;
     log = createLogger('daemon');
     /**
      * Start listening on the provided Unix domain socket path.
+     *
+     * @param socketPath - Public socket path to claim
+     * @param handler - Connection handler
+     * @throws DaemonError with code DAEMON_ALREADY_RUNNING if a live daemon owns the path
      */
     async start(socketPath, handler) {
+        const privatePath = `${socketPath}.${process.pid}`;
+        if (Buffer.byteLength(privatePath) > MAX_SOCKET_PATH_BYTES) {
+            throw new DaemonError(`Socket path too long (${Buffer.byteLength(privatePath)} bytes, max ${MAX_SOCKET_PATH_BYTES}): ${privatePath}`, 'SOCKET_PATH_TOO_LONG', EXIT_CODES.INVALID_ARGUMENTS);
+        }
+        this.removeFile(privatePath);
+        await this.listen(privatePath, handler);
+        try {
+            await this.claim(privatePath, socketPath);
+            this.socketInode = lstatSync(privatePath).ino;
+        }
+        catch (error) {
+            await this.closeServer();
+            throw error;
+        }
+        finally {
+            this.removeFile(privatePath);
+        }
         this.socketPath = socketPath;
-        this.cleanupStaleSocket();
-        await new Promise((resolve, reject) => {
+        this.log.info(`IPC server listening on ${socketPath}`);
+    }
+    /**
+     * Remove the public socket file so no new clients can connect, while
+     * keeping existing connections open to flush their final responses.
+     */
+    unpublish() {
+        if (!this.socketPath)
+            return;
+        if (this.ownsPath(this.socketPath)) {
+            this.removeFile(this.socketPath);
+        }
+        this.socketPath = null;
+        this.socketInode = null;
+    }
+    /**
+     * Check that a path still refers to the socket this server claimed.
+     *
+     * Guards against removing another daemon's socket if ours was replaced
+     * (e.g. two daemons racing to replace the same stale socket file).
+     *
+     * @param path - Public socket path
+     * @returns True if the path is our socket inode
+     */
+    ownsPath(path) {
+        try {
+            return lstatSync(path).ino === this.socketInode;
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Unpublish the socket, drop all connections and close the server.
+     */
+    async stop() {
+        this.unpublish();
+        for (const socket of this.sockets) {
+            socket.destroy();
+        }
+        this.sockets.clear();
+        await this.closeServer();
+    }
+    /**
+     * Listen on a socket path.
+     *
+     * @param path - Socket path
+     * @param handler - Connection handler
+     */
+    listen(path, handler) {
+        return new Promise((resolve, reject) => {
             this.server = createServer((socket) => {
                 this.sockets.add(socket);
                 socket.on('close', () => this.sockets.delete(socket));
                 handler(socket);
             });
-            this.server.on('error', (error) => {
-                console.error(`[daemon] Socket server error: ${error.message}`);
-                reject(error);
-            });
-            this.server.listen(socketPath, () => {
-                this.log.info(`[daemon] IPC server listening on ${socketPath}`);
+            this.server.once('error', reject);
+            this.server.listen(path, () => {
+                this.server?.off('error', reject);
+                this.server?.on('error', (error) => this.log.info(`Socket server error: ${error.message}`));
                 resolve();
             });
         });
     }
     /**
-     * Stop the server and clean up the socket file.
+     * Atomically publish the listening socket at the public path.
+     *
+     * A stale socket file (nothing listening) is removed and the claim retried once.
+     *
+     * @param privatePath - Path the server is listening on
+     * @param socketPath - Public path to claim
+     * @throws DaemonError if a live daemon already owns the public path
      */
-    async stop() {
-        for (const socket of this.sockets) {
-            socket.destroy();
+    async claim(privatePath, socketPath) {
+        for (let attempt = 0; attempt < 2; attempt++) {
+            try {
+                linkSync(privatePath, socketPath);
+                return;
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST')
+                    throw error;
+            }
+            if ((await probeDaemonSocket(socketPath)) === 'alive')
+                break;
+            this.log.info('Removing stale daemon socket');
+            this.removeFile(socketPath);
         }
-        this.sockets.clear();
-        if (this.server) {
-            await new Promise((resolve) => {
-                this.server?.close(() => {
-                    this.log.info('[daemon] IPC server stopped');
-                    resolve();
-                });
-            });
-            this.server = null;
-        }
-        this.cleanupStaleSocket();
-        this.socketPath = null;
+        throw new DaemonError('Another bdg daemon is already running', DAEMON_ALREADY_RUNNING_CODE, EXIT_CODES.DAEMON_ALREADY_RUNNING);
     }
-    cleanupStaleSocket() {
-        if (!this.socketPath) {
+    /**
+     * Close the underlying server if it is open.
+     */
+    async closeServer() {
+        const server = this.server;
+        if (!server)
             return;
-        }
+        this.server = null;
+        await new Promise((resolve) => server.close(() => resolve()));
+    }
+    /**
+     * Remove a file, ignoring errors.
+     *
+     * @param path - File path
+     */
+    removeFile(path) {
         try {
-            unlinkSync(this.socketPath);
+            unlinkSync(path);
         }
         catch (error) {
-            this.log.debug(`Failed to remove socket file: ${error instanceof Error ? error.message : String(error)}`);
+            this.log.debug(`Failed to remove ${path}: ${getErrorMessage(error)}`);
         }
     }
 }

package/dist/daemon/session/Session.d.ts

@@ -0,0 +1,137 @@
+/**
+ * In-process browser session owned by the daemon.
+ *
+ * A Session launches (or attaches to) Chrome, connects over CDP, runs the
+ * telemetry collectors and executes session commands directly. There is no
+ * separate worker process: the daemon process *is* the session.
+ */
+import type { CommandName, CommandSchemas } from '../../ipc/index.js';
+import type { SessionOptions } from '../../ipc/session/lifecycle.js';
+import type { StatusResponseData } from '../../ipc/session/queries.js';
+/** Why a session ended. */
+export type SessionEndReason = 'normal' | 'crash' | 'timeout' | 'closed';
+/** Summary of a running session, as reported to the CLI on start. */
+export interface SessionInfo {
+    chromePid: number;
+    port: number;
+    targetUrl: string;
+    targetTitle?: string;
+    /** HTTP status of the page's main document, when known */
+    documentStatus?: number;
+}
+/** Session metadata as reported in status responses. */
+export type SessionStatusMetadata = NonNullable<StatusResponseData['sessionMetadata']>;
+/**
+ * A launch that failed because the session was stopped while starting.
+ */
+export declare class StartCancelledError extends Error {
+    readonly name = "StartCancelledError";
+    constructor();
+}
+/**
+ * A running browser session.
+ */
+export declare class Session {
+    private config;
+    private readonly onEnded;
+    private readonly store;
+    private readonly registry;
+    private readonly notify;
+    private chrome;
+    private cdp;
+    private cleanupFunctions;
+    private timeoutTimer;
+    /** When `--timeout` stops the session (epoch ms) */
+    private autoStopAt;
+    private stopping;
+    /** Why the session was first asked to stop ('normal' = user, signal or abandoned start) */
+    private stopReason;
+    /** Aborted by stop(), so launch steps that wait or retry end at once */
+    private readonly launchAbort;
+    private started;
+    private documentRequestId;
+    private constructor();
+    /**
+     * Validate the request and create a session that has not been launched yet.
+     *
+     * Synchronous so the caller can register the session (and stop it) before
+     * any asynchronous work starts; the CDP port is resolved in {@link launch}.
+     *
+     * @param url - Target URL
+     * @param options - Session options from the start request
+     * @param onEnded - Called once when a launched session ends for any reason
+     * @returns Unlaunched session
+     * @throws CommandError for an invalid URL
+     */
+    static create(url: string, options: SessionOptions, onEnded: (reason: SessionEndReason) => void): Session;
+    /**
+     * Launch: start Chrome (or attach), connect CDP, start collectors, navigate.
+     *
+     * Every resource is owned by the session as soon as it is acquired, so a
+     * concurrent {@link stop} (signal, disconnect) can always release it. On
+     * failure or abort, whatever was acquired is released before rethrowing;
+     * `onEnded` is only called for sessions that finished launching.
+     *
+     * @throws Launch/connection errors, or an abort error if stopped meanwhile
+     */
+    launch(): Promise<void>;
+    /**
+     * Execute a registered command against this session.
+     *
+     * @param name - Command name
+     * @param params - Command parameters
+     * @returns Command result
+     */
+    execute<K extends CommandName>(name: K, params: CommandSchemas[K]['requestSchema']): Promise<CommandSchemas[K]['responseSchema']>;
+    /**
+     * Summary of this session for start responses.
+     *
+     * @returns Session info
+     */
+    info(): SessionInfo;
+    /**
+     * Metadata for status responses and session-conflict checks.
+     *
+     * @returns Session metadata
+     */
+    metadata(): SessionStatusMetadata;
+    /**
+     * Whether stop() has been called.
+     *
+     * @returns True once the session is stopping
+     */
+    stopRequested(): boolean;
+    /**
+     * Stop the session: stop collectors, close CDP, terminate Chrome.
+     *
+     * Idempotent: concurrent and repeated calls share one stop. Safe to call
+     * while launching; the launch then aborts and releases what it acquired.
+     *
+     * @param reason - Why the session is ending
+     * @returns Promise resolved when teardown is complete
+     */
+    stop(reason: SessionEndReason): Promise<void>;
+    /**
+     * Acquire Chrome, CDP and collectors, checking for a concurrent stop after each step.
+     */
+    private acquireResources;
+    /**
+     * End the session after its page connection was lost. A launched Chrome
+     * still running a moment later means the tab was closed (e.g.
+     * `Target.closeTarget`), a normal end; otherwise Chrome went away (a
+     * crashing Chrome can drop the connection just before it exits).
+     */
+    private endAfterDisconnect;
+    /**
+     * Abort a launch that was stopped while in progress.
+     *
+     * @throws Error if the session is stopping
+     */
+    private throwIfStopping;
+    /**
+     * Release every resource currently held. Each resource is released once:
+     * later calls only release what was acquired since.
+     */
+    private releaseResources;
+}
+//# sourceMappingURL=Session.d.ts.map

package/dist/daemon/session/Session.js

@@ -0,0 +1,288 @@
+/**
+ * In-process browser session owned by the daemon.
+ *
+ * A Session launches (or attaches to) Chrome, connects over CDP, runs the
+ * telemetry collectors and executes session commands directly. There is no
+ * separate worker process: the daemon process *is* the session.
+ */
+import { TelemetryStore } from './TelemetryStore.js';
+import { connectCDP, navigateToTarget } from './cdpSetup.js';
+import { externalChromePort, findPageTarget, setupChromeConnection, } from './chromeConnection.js';
+import { startTelemetryCollectors } from './collectors.js';
+import { createCommandRegistry } from './commandRegistry.js';
+import { teardownSession } from './teardown.js';
+import { CommandError } from '../../errors/index.js';
+import { reapOrphanedChrome, removeSessionFiles } from '../../session/cleanup/staleSession.js';
+import { writeSessionMetadata } from '../../session/metadata.js';
+import { getSessionPort } from '../../session/port.js';
+import { createLogger } from '../../ui/logging/index.js';
+import { formatChromeNotice } from '../../ui/messages/chrome.js';
+import { delay } from '../../utils/async.js';
+import { EXIT_CODES } from '../../utils/exitCodes.js';
+import { filterDefined } from '../../utils/objects.js';
+import { isProcessAlive } from '../../utils/process.js';
+import { validateUrl } from '../../utils/url.js';
+const log = createLogger('session');
+/** How long Chrome gets to exit after the page connection drops, before the end is called a closed tab */
+const CRASH_SETTLE_MS = 500;
+/**
+ * A launch that failed because the session was stopped while starting.
+ */
+export class StartCancelledError extends Error {
+    name = 'StartCancelledError';
+    constructor() {
+        super('The start was cancelled: the session was stopped while it was starting');
+    }
+}
+/**
+ * A running browser session.
+ */
+export class Session {
+    config;
+    onEnded;
+    store = new TelemetryStore();
+    registry = createCommandRegistry(this.store);
+    notify = (notice) => log.info(formatChromeNotice(notice));
+    chrome = null;
+    cdp = null;
+    cleanupFunctions = [];
+    timeoutTimer = null;
+    /** When `--timeout` stops the session (epoch ms) */
+    autoStopAt;
+    stopping = null;
+    /** Why the session was first asked to stop ('normal' = user, signal or abandoned start) */
+    stopReason = null;
+    /** Aborted by stop(), so launch steps that wait or retry end at once */
+    launchAbort = new AbortController();
+    started = false;
+    documentRequestId;
+    constructor(config, onEnded) {
+        this.config = config;
+        this.onEnded = onEnded;
+    }
+    /**
+     * Validate the request and create a session that has not been launched yet.
+     *
+     * Synchronous so the caller can register the session (and stop it) before
+     * any asynchronous work starts; the CDP port is resolved in {@link launch}.
+     *
+     * @param url - Target URL
+     * @param options - Session options from the start request
+     * @param onEnded - Called once when a launched session ends for any reason
+     * @returns Unlaunched session
+     * @throws CommandError for an invalid URL
+     */
+    static create(url, options, onEnded) {
+        const validation = validateUrl(url);
+        if (!validation.valid) {
+            throw new CommandError(validation.error, filterDefined({ suggestion: validation.suggestion }), EXIT_CODES.INVALID_URL);
+        }
+        return new Session(buildConfig(url, options.port ?? 0, options), onEnded);
+    }
+    /**
+     * Launch: start Chrome (or attach), connect CDP, start collectors, navigate.
+     *
+     * Every resource is owned by the session as soon as it is acquired, so a
+     * concurrent {@link stop} (signal, disconnect) can always release it. On
+     * failure or abort, whatever was acquired is released before rethrowing;
+     * `onEnded` is only called for sessions that finished launching.
+     *
+     * @throws Launch/connection errors, or an abort error if stopped meanwhile
+     */
+    async launch() {
+        try {
+            await this.acquireResources();
+        }
+        catch (error) {
+            const cancelled = this.stopReason === 'normal';
+            await this.releaseResources();
+            throw cancelled ? new StartCancelledError() : error;
+        }
+        this.started = true;
+        if (this.config.timeout)
+            this.autoStopAt = Date.now() + this.config.timeout * 1000;
+        writeSessionMetadata(this.metadata());
+        if (this.config.timeout) {
+            log.info(`Auto-stop after ${this.config.timeout}s`);
+            this.timeoutTimer = setTimeout(() => void this.stop('timeout'), this.config.timeout * 1000);
+        }
+    }
+    /**
+     * Execute a registered command against this session.
+     *
+     * @param name - Command name
+     * @param params - Command parameters
+     * @returns Command result
+     */
+    execute(name, params) {
+        if (!this.cdp || !this.started || this.stopping) {
+            return Promise.reject(new Error('No active session'));
+        }
+        return this.registry[name](this.cdp, params);
+    }
+    /**
+     * Summary of this session for start responses.
+     *
+     * @returns Session info
+     */
+    info() {
+        const target = this.store.targetInfo;
+        const documentStatus = this.store.networkRequests.find((request) => request.requestId === this.documentRequestId && request.status)?.status;
+        return {
+            chromePid: this.chrome?.pid ?? 0,
+            port: this.config.port,
+            targetUrl: target?.url ?? this.config.url,
+            ...(target?.title && { targetTitle: target.title }),
+            ...(documentStatus !== undefined && { documentStatus }),
+        };
+    }
+    /**
+     * Metadata for status responses and session-conflict checks.
+     *
+     * @returns Session metadata
+     */
+    metadata() {
+        const target = this.store.targetInfo;
+        return {
+            bdgPid: process.pid,
+            chromePid: this.chrome?.pid ?? 0,
+            startTime: this.store.sessionStartTime,
+            port: this.config.port,
+            activeTelemetry: this.store.activeTelemetry,
+            ...filterDefined({
+                autoStopAt: this.autoStopAt,
+                targetId: target?.id,
+                webSocketDebuggerUrl: target?.webSocketDebuggerUrl,
+            }),
+        };
+    }
+    /**
+     * Whether stop() has been called.
+     *
+     * @returns True once the session is stopping
+     */
+    stopRequested() {
+        return this.stopping !== null;
+    }
+    /**
+     * Stop the session: stop collectors, close CDP, terminate Chrome.
+     *
+     * Idempotent: concurrent and repeated calls share one stop. Safe to call
+     * while launching; the launch then aborts and releases what it acquired.
+     *
+     * @param reason - Why the session is ending
+     * @returns Promise resolved when teardown is complete
+     */
+    stop(reason) {
+        this.stopReason ??= reason;
+        this.launchAbort.abort();
+        this.stopping ??= (async () => {
+            if (this.timeoutTimer)
+                clearTimeout(this.timeoutTimer);
+            log.info(`Stopping session (reason: ${reason})`);
+            await this.releaseResources();
+            if (!this.started)
+                return;
+            removeSessionFiles();
+            this.onEnded(reason);
+        })();
+        return this.stopping;
+    }
+    /**
+     * Acquire Chrome, CDP and collectors, checking for a concurrent stop after each step.
+     */
+    async acquireResources() {
+        this.store.resetSessionStart();
+        const { chromeWsUrl } = this.config;
+        const port = chromeWsUrl
+            ? externalChromePort(chromeWsUrl)
+            : await getSessionPort(this.config.port || undefined);
+        this.config = { ...this.config, port };
+        this.throwIfStopping();
+        if (!this.config.chromeWsUrl) {
+            await reapOrphanedChrome();
+        }
+        this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify);
+        this.throwIfStopping();
+        if (this.chrome) {
+            await findPageTarget(this.config, this.store, log);
+            this.throwIfStopping();
+        }
+        this.cdp = await connectCDP(this.store, log, () => void this.endAfterDisconnect(), {
+            external: Boolean(chromeWsUrl),
+            signal: this.launchAbort.signal,
+        });
+        this.throwIfStopping();
+        this.cleanupFunctions = await startTelemetryCollectors(this.cdp, this.config, this.store, log);
+        this.throwIfStopping();
+        this.documentRequestId = await navigateToTarget(this.cdp, this.config, this.store, this.chrome, log);
+        this.throwIfStopping();
+    }
+    /**
+     * End the session after its page connection was lost. A launched Chrome
+     * still running a moment later means the tab was closed (e.g.
+     * `Target.closeTarget`), a normal end; otherwise Chrome went away (a
+     * crashing Chrome can drop the connection just before it exits).
+     */
+    async endAfterDisconnect() {
+        if (this.chrome)
+            await delay(CRASH_SETTLE_MS);
+        const tabClosed = this.chrome !== null && isProcessAlive(this.chrome.pid);
+        if (tabClosed)
+            log.info('The page was closed; ending the session');
+        await this.stop(tabClosed ? 'closed' : 'crash');
+    }
+    /**
+     * Abort a launch that was stopped while in progress.
+     *
+     * @throws Error if the session is stopping
+     */
+    throwIfStopping() {
+        if (this.stopping) {
+            throw new Error('Session was stopped during startup');
+        }
+    }
+    /**
+     * Release every resource currently held. Each resource is released once:
+     * later calls only release what was acquired since.
+     */
+    async releaseResources() {
+        const context = {
+            chrome: this.chrome,
+            cdp: this.cdp,
+            cleanupFunctions: this.cleanupFunctions,
+            external: Boolean(this.config.chromeWsUrl),
+            log,
+            notify: this.notify,
+        };
+        this.chrome = null;
+        this.cdp = null;
+        this.cleanupFunctions = [];
+        await teardownSession(context);
+    }
+}
+/**
+ * Build the session configuration from a start request.
+ *
+ * @param url - Target URL
+ * @param port - Resolved CDP port
+ * @param options - Session options from the start request
+ * @returns Session configuration
+ */
+function buildConfig(url, port, options) {
+    return {
+        url,
+        port,
+        telemetry: options.telemetry ?? ['network', 'console', 'dom'],
+        includeAll: options.includeAll ?? false,
+        headless: options.headless ?? false,
+        ...filterDefined({
+            timeout: options.timeout,
+            userDataDir: options.userDataDir,
+            maxBodySize: options.maxBodySize,
+            chromeWsUrl: options.chromeWsUrl,
+            chromeFlags: options.chromeFlags,
+        }),
+    };
+}
+//# sourceMappingURL=Session.js.map

package/dist/daemon/session/TelemetryStore.d.ts

@@ -0,0 +1,30 @@
+import type { DialogInfo } from '../../ipc/protocol/domTypes.js';
+import type { NavigationEvent } from '../../telemetry/navigation.js';
+import type { PendingRequest } from '../../telemetry/network.js';
+import type { CDPTarget, ConsoleMessage, NetworkRequest, TelemetryType, WebSocketConnection } from '../../types.js';
+export declare class TelemetryStore {
+    readonly networkRequests: NetworkRequest[];
+    /** Requests still in flight, keyed by CDP requestId */
+    readonly pendingNetworkRequests: Map<string, PendingRequest>;
+    readonly consoleMessages: ConsoleMessage[];
+    readonly navigationEvents: NavigationEvent[];
+    readonly websocketConnections: WebSocketConnection[];
+    /** JavaScript dialogs accepted during the session */
+    readonly dialogs: DialogInfo[];
+    activeTelemetry: TelemetryType[];
+    getCurrentNavigationId: (() => number) | null;
+    sessionStartTime: number;
+    targetInfo: CDPTarget | null;
+    resetSessionStart(): void;
+    setTargetInfo(target: CDPTarget | null): void;
+    setNavigationResolver(navigationId: (() => number) | null): void;
+    /**
+     * Record an accepted dialog, and show it among the console messages when
+     * console telemetry is collected (it is otherwise invisible: bdg accepts it
+     * before anyone could see it).
+     *
+     * @param dialog - Dialog type and text
+     */
+    recordDialog(dialog: DialogInfo): void;
+}
+//# sourceMappingURL=TelemetryStore.d.ts.map