browser-debugger-cli 0.14.0 → 0.16.0

package/dist/daemon/launcher.d.ts

@@ -11,11 +11,18 @@ export interface SpawnedDaemon {
     pid: number | undefined;
     /** Whether it has exited (from the child process's exit event) */
     hasExited: () => boolean;
+    /**
+     * Tell it to shut down (SIGTERM, unless it has exited): it ends what it
+     * hosts and exits. For a start interrupted before its request was sent.
+     */
+    stop: () => void;
 }
 /**
  * Ensure a daemon is running, spawning one if needed.
  *
  * @returns The daemon it spawned, or undefined when one was already running
+ * @throws SessionDirError if the session directory is unusable or untrusted
+ *   (checked first, so a socket planted there is never taken for a daemon)
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
@@ -24,9 +31,21 @@ export declare function launchDaemon(): Promise<SpawnedDaemon | undefined>;
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file or a path that cannot hold a
- *   directory (a pseudo-filesystem like `/proc`), (81) for a too-long path
- *   like a named session's, (82) when not writable
+ * @throws SessionDirError (103) for a file, a path that cannot hold a
+ *   directory (a pseudo-filesystem like `/proc`) or an untrusted directory
+ *   (see {@link secureSessionDir}, which also tightens the user's own 0755
+ *   directories to 0700), (81) for a too-long path like a named session's,
+ *   (82) when not writable
  */
 export declare function assertUsableSessionDir(): void;
+/**
+ * Open the daemon log for the daemon's output, creating it 0600. A symlink in
+ * its place is refused, not followed: it would append the log to the file it
+ * points to.
+ *
+ * @param logPath - Daemon log path
+ * @returns File descriptor
+ * @throws SessionDirError (103) when it cannot be opened (`ELOOP` for a symlink)
+ */
+export declare function openDaemonLog(logPath: string): number;
 //# sourceMappingURL=launcher.d.ts.map

package/dist/daemon/launcher.js

@@ -10,10 +10,10 @@ import { spawn } from 'child_process';
 import fs from 'fs';
 import { join } from 'path';
 import { DaemonStartupError, SessionDirError } from './errors.js';
-import { sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, } from '../errors/messages.js';
+import { daemonLogNotOpenedError, sessionDirIsFileError, sessionDirNotWritableError, socketPathTooLongError, untrustedSessionDirError, } from '../errors/messages.js';
 import { killSessionChromes, readLiveDaemonPid } from '../session/cleanup/staleSession.js';
 import { isDaemonAlive, isDaemonSocketGone } from '../session/daemonSocket.js';
-import { MAX_DAEMON_SOCKET_PATH_BYTES, ensureSessionDir, getSessionDir, getSessionFilePath, } from '../session/paths.js';
+import { MAX_DAEMON_SOCKET_PATH_BYTES, ensureSessionDir, getSessionDir, getSessionFilePath, secureSessionDir, } from '../session/paths.js';
 import { createLogger } from '../ui/logging/index.js';
 import { delay } from '../utils/async.js';
 import { directoryProblem } from '../utils/directories.js';
@@ -28,10 +28,13 @@ const DAEMON_READY_POLL_MS = 20;
  * Ensure a daemon is running, spawning one if needed.
  *
  * @returns The daemon it spawned, or undefined when one was already running
+ * @throws SessionDirError if the session directory is unusable or untrusted
+ *   (checked first, so a socket planted there is never taken for a daemon)
  * @throws DaemonStartupError if the daemon script is missing or the daemon
  *   does not accept connections in time
  */
 export async function launchDaemon() {
+    assertUsableSessionDir();
     if (await isDaemonAlive()) {
         log.debug('Daemon already running');
         return undefined;
@@ -39,11 +42,10 @@ export async function launchDaemon() {
     if (!fs.existsSync(DAEMON_SCRIPT_PATH)) {
         throw new DaemonStartupError(`Daemon script not found at ${DAEMON_SCRIPT_PATH}. Did you run 'npm run build'?`, 'DAEMON_SCRIPT_NOT_FOUND');
     }
-    assertUsableSessionDir();
     await stopUnreachableDaemon();
     const logPath = join(getSessionDir(), 'daemon.log');
     rotateLog(logPath);
-    const logFd = fs.openSync(logPath, 'a');
+    const logFd = openDaemonLog(logPath);
     log.debug(`Starting daemon: ${DAEMON_SCRIPT_PATH}`);
     const daemon = spawn(process.execPath, [DAEMON_SCRIPT_PATH], {
         detached: true,
@@ -56,7 +58,14 @@ export async function launchDaemon() {
     });
     daemon.unref();
     await waitForDaemonReady(() => exited);
-    return { pid: daemon.pid, hasExited: () => exited };
+    return {
+        pid: daemon.pid,
+        hasExited: () => exited,
+        stop: () => {
+            if (!exited)
+                daemon.kill('SIGTERM');
+        },
+    };
 }
 /** How long a daemon that lost its socket gets to end its session before it is killed */
 const UNREACHABLE_DAEMON_EXIT_MS = 8000;
@@ -97,9 +106,11 @@ async function stopUnreachableDaemon() {
  * Check that the session directory can hold the daemon's files before
  * spawning it (otherwise the daemon dies and only its log says why).
  *
- * @throws SessionDirError (103) for a file or a path that cannot hold a
- *   directory (a pseudo-filesystem like `/proc`), (81) for a too-long path
- *   like a named session's, (82) when not writable
+ * @throws SessionDirError (103) for a file, a path that cannot hold a
+ *   directory (a pseudo-filesystem like `/proc`) or an untrusted directory
+ *   (see {@link secureSessionDir}, which also tightens the user's own 0755
+ *   directories to 0700), (81) for a too-long path like a named session's,
+ *   (82) when not writable
  */
 export function assertUsableSessionDir() {
     const dir = getSessionDir();
@@ -116,6 +127,9 @@ export function assertUsableSessionDir() {
     if (problem) {
         fail(sessionDirNotWritableError(dir, problem.reason), problem.denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR);
     }
+    const untrusted = secureSessionDir(dir);
+    if (untrusted)
+        fail(untrustedSessionDirError(untrusted));
     try {
         ensureSessionDir();
         fs.accessSync(dir, fs.constants.W_OK);
@@ -126,6 +140,29 @@ export function assertUsableSessionDir() {
         fail(sessionDirNotWritableError(dir, code ?? getErrorMessage(error)), denied ? EXIT_CODES.PERMISSION_DENIED : EXIT_CODES.SESSION_FILE_ERROR);
     }
 }
+/** Flags opening the daemon log for appending, refusing (not following) a symlink */
+const DAEMON_LOG_FLAGS = fs.constants.O_WRONLY |
+    fs.constants.O_APPEND |
+    fs.constants.O_CREAT |
+    (fs.constants.O_NOFOLLOW ?? 0);
+/**
+ * Open the daemon log for the daemon's output, creating it 0600. A symlink in
+ * its place is refused, not followed: it would append the log to the file it
+ * points to.
+ *
+ * @param logPath - Daemon log path
+ * @returns File descriptor
+ * @throws SessionDirError (103) when it cannot be opened (`ELOOP` for a symlink)
+ */
+export function openDaemonLog(logPath) {
+    try {
+        return fs.openSync(logPath, DAEMON_LOG_FLAGS, 0o600);
+    }
+    catch (error) {
+        const err = daemonLogNotOpenedError(logPath, error.code ?? getErrorMessage(error));
+        throw new SessionDirError(err.message, err.suggestion);
+    }
+}
 /** Size above which the daemon log is rotated when a daemon starts */
 const MAX_LOG_BYTES = 5 * 1024 * 1024;
 /**

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

@@ -39,6 +39,7 @@ export declare class Session {
     private readonly onEnded;
     private readonly store;
     private readonly registry;
+    private readonly captures;
     private readonly notify;
     private chrome;
     private cdp;
@@ -85,12 +86,15 @@ export declare class Session {
      * {@link CRASH_SAFE_CDP} methods); others fail with exit 107 instead of
      * waiting for a page that cannot answer. Commands that may change the page
      * drop `dom inspect`'s kept matched rules ({@link withMatchedStylesReset}).
+     * Page commands run once a screenshot running before them has put the
+     * page's emulation back ({@link CaptureGate}).
      *
      * @param name - Command name
      * @param params - Command parameters
+     * @param abandoned - Aborted when the requesting client disconnects
      * @returns Command result
      */
-    execute<K extends CommandName>(name: K, params: CommandSchemas[K]['requestSchema']): Promise<CommandSchemas[K]['responseSchema']>;
+    execute<K extends CommandName>(name: K, params: CommandSchemas[K]['requestSchema'], abandoned?: AbortSignal): Promise<CommandSchemas[K]['responseSchema']>;
     /**
      * Summary of this session for start responses.
      *

package/dist/daemon/session/Session.js

@@ -7,6 +7,7 @@
  */
 import { ChromeLaunchError } from '../../connection/errors.js';
 import { TelemetryStore } from './TelemetryStore.js';
+import { CaptureGate, TELEMETRY_READS } from './captureGate.js';
 import { connectCDP, navigateToTarget } from './cdpSetup.js';
 import { externalChromePort, findPageTarget, setupChromeConnection, } from './chromeConnection.js';
 import { startTelemetryCollectors } from './collectors.js';
@@ -40,11 +41,7 @@ const PORT_ATTEMPTS = 3;
  * send raw CDP. Every other command needs the page and fails at once.
  */
 const RUN_ON_CRASHED_PAGE = new Set([
-    'session_peek',
-    'session_details',
-    'session_status',
-    'session_har_data',
-    'session_network_headers',
+    ...TELEMETRY_READS,
     'page_navigate',
     'cdp_call',
 ]);
@@ -83,6 +80,7 @@ export class Session {
         get: () => filterDefined({ viewport: this.config.viewport, colorScheme: this.config.colorScheme }),
         set: (emulation) => this.setEmulation(emulation),
     });
+    captures = new CaptureGate();
     notify = (notice) => log.info(formatChromeNotice(notice));
     chrome = null;
     cdp = null;
@@ -155,12 +153,15 @@ export class Session {
      * {@link CRASH_SAFE_CDP} methods); others fail with exit 107 instead of
      * waiting for a page that cannot answer. Commands that may change the page
      * drop `dom inspect`'s kept matched rules ({@link withMatchedStylesReset}).
+     * Page commands run once a screenshot running before them has put the
+     * page's emulation back ({@link CaptureGate}).
      *
      * @param name - Command name
      * @param params - Command parameters
+     * @param abandoned - Aborted when the requesting client disconnects
      * @returns Command result
      */
-    execute(name, params) {
+    execute(name, params, abandoned) {
         if (!this.cdp || !this.started || this.stopping) {
             return Promise.reject(new Error('No active session'));
         }
@@ -176,7 +177,7 @@ export class Session {
         }
         const handler = this.registry[name];
         const cdp = this.cdp;
-        return withMatchedStylesReset(cdp, name, () => handler(cdp, params));
+        return this.captures.run(name, () => withMatchedStylesReset(cdp, name, () => handler(cdp, params, abandoned)));
     }
     /**
      * Summary of this session for start responses.
@@ -315,7 +316,7 @@ export class Session {
             this.config = { ...this.config, port: await getSessionPort(explicitPort) };
             this.throwIfStopping();
             try {
-                this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify);
+                this.chrome = await setupChromeConnection(this.config, this.store, log, this.notify, this.launchAbort.signal);
                 return;
             }
             catch (error) {

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

@@ -1,4 +1,5 @@
 import type { DialogInfo } from '../../ipc/protocol/domTypes.js';
+import type { TrackedDownload } from '../../telemetry/downloads.js';
 import type { NavigationEvent } from '../../telemetry/navigation.js';
 import type { PendingRequest } from '../../telemetry/network.js';
 import type { NetworkEvictions } from '../../telemetry/networkRetention.js';
@@ -23,6 +24,10 @@ export declare class TelemetryStore {
     readonly websocketConnections: WebSocketConnection[];
     /** JavaScript dialogs accepted during the session */
     readonly dialogs: DialogInfo[];
+    /** Downloads that began during the session, oldest first, updated as they progress */
+    readonly downloads: TrackedDownload[];
+    /** Set while downloads do not go where bdg meant them to (refused, or not redirected) */
+    downloadsWarning: string | undefined;
     activeTelemetry: TelemetryType[];
     /** When the page's renderer crashed (epoch ms); undefined while the page is alive */
     pageCrashedAt: number | undefined;

package/dist/daemon/session/TelemetryStore.js

@@ -20,6 +20,10 @@ export class TelemetryStore {
     websocketConnections = [];
     /** JavaScript dialogs accepted during the session */
     dialogs = [];
+    /** Downloads that began during the session, oldest first, updated as they progress */
+    downloads = [];
+    /** Set while downloads do not go where bdg meant them to (refused, or not redirected) */
+    downloadsWarning = undefined;
     activeTelemetry = [];
     /** When the page's renderer crashed (epoch ms); undefined while the page is alive */
     pageCrashedAt;

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

@@ -0,0 +1,59 @@
+/**
+ * A screenshot changes the page's emulation for its capture (pixel ratio,
+ * touch, viewport, scrollbars) and puts it back once the capture ended. Its
+ * client may be gone long before that: interrupted (Ctrl-C), killed, or timed
+ * out by the daemon's command timeout. Page commands therefore run only once
+ * the captures before them are done, restore included, so no command, from
+ * any client, sees the capture's emulation. Commands that read only the
+ * telemetry run at once. The wait counts toward the command's own timeout
+ * (30 s), like any time the command takes.
+ */
+import type { CommandName } from '../../ipc/index.js';
+/** Commands that read only what the session collected, never the page */
+export declare const TELEMETRY_READS: readonly CommandName[];
+/**
+ * How long a page command waits for a capture before it runs anyway. A
+ * capture of a very tall page takes a few seconds; one that never ends (CDP
+ * calls have no timeout) must not stall the session. A capture waits for the
+ * one before it without this limit (bounded by its command timeout): run
+ * during it, it would record that capture's emulation as the page's own and
+ * put that back.
+ */
+export declare const CAPTURE_WAIT_MS = 15000;
+/**
+ * Orders page commands after the captures before them.
+ */
+export declare class CaptureGate {
+    private readonly waitMs;
+    private capture;
+    /**
+     * @param waitMs - How long a command waits for a capture at most
+     */
+    constructor(waitMs?: number);
+    /**
+     * Run a command: at once when it reads only the telemetry, else once the
+     * capture running before it has ended (or, unless it is a capture itself,
+     * {@link waitMs} passed). A
+     * capture is waited for by the commands after it until it ends, however it
+     * ends.
+     *
+     * @param name - Command name
+     * @param command - The command
+     * @returns Its result
+     */
+    run<T>(name: CommandName, command: () => Promise<T>): Promise<T>;
+    /**
+     * Wait for the running capture, if any: until it ends for a capture, else
+     * at most {@link waitMs}.
+     *
+     * @param isCapture - Whether the waiting command is a capture
+     */
+    private captureEnded;
+    /**
+     * Make a capture the one later commands wait for.
+     *
+     * @param result - The capture's result
+     */
+    private track;
+}
+//# sourceMappingURL=captureGate.d.ts.map

package/dist/daemon/session/captureGate.js

@@ -0,0 +1,96 @@
+/**
+ * A screenshot changes the page's emulation for its capture (pixel ratio,
+ * touch, viewport, scrollbars) and puts it back once the capture ended. Its
+ * client may be gone long before that: interrupted (Ctrl-C), killed, or timed
+ * out by the daemon's command timeout. Page commands therefore run only once
+ * the captures before them are done, restore included, so no command, from
+ * any client, sees the capture's emulation. Commands that read only the
+ * telemetry run at once. The wait counts toward the command's own timeout
+ * (30 s), like any time the command takes.
+ */
+import { settledWithin } from '../../runtime/dom/evalHelpers.js';
+import { createLogger } from '../../ui/logging/index.js';
+const log = createLogger('session');
+/** Commands that read only what the session collected, never the page */
+export const TELEMETRY_READS = [
+    'session_peek',
+    'session_details',
+    'session_status',
+    'session_har_data',
+    'session_network_headers',
+];
+const IGNORES_CAPTURE = new Set(TELEMETRY_READS);
+/**
+ * How long a page command waits for a capture before it runs anyway. A
+ * capture of a very tall page takes a few seconds; one that never ends (CDP
+ * calls have no timeout) must not stall the session. A capture waits for the
+ * one before it without this limit (bounded by its command timeout): run
+ * during it, it would record that capture's emulation as the page's own and
+ * put that back.
+ */
+export const CAPTURE_WAIT_MS = 15_000;
+/** Command that changes the page's emulation until it ends */
+const CAPTURE_COMMAND = 'dom_screenshot';
+/**
+ * Orders page commands after the captures before them.
+ */
+export class CaptureGate {
+    waitMs;
+    capture;
+    /**
+     * @param waitMs - How long a command waits for a capture at most
+     */
+    constructor(waitMs = CAPTURE_WAIT_MS) {
+        this.waitMs = waitMs;
+    }
+    /**
+     * Run a command: at once when it reads only the telemetry, else once the
+     * capture running before it has ended (or, unless it is a capture itself,
+     * {@link waitMs} passed). A
+     * capture is waited for by the commands after it until it ends, however it
+     * ends.
+     *
+     * @param name - Command name
+     * @param command - The command
+     * @returns Its result
+     */
+    run(name, command) {
+        if (IGNORES_CAPTURE.has(name))
+            return command();
+        const isCapture = name === CAPTURE_COMMAND;
+        const result = this.captureEnded(isCapture).then(command);
+        if (isCapture)
+            this.track(result);
+        return result;
+    }
+    /**
+     * Wait for the running capture, if any: until it ends for a capture, else
+     * at most {@link waitMs}.
+     *
+     * @param isCapture - Whether the waiting command is a capture
+     */
+    async captureEnded(isCapture) {
+        const capture = this.capture;
+        if (!capture)
+            return;
+        if (isCapture)
+            return capture;
+        const ended = await settledWithin(capture, this.waitMs);
+        if (!ended.settled)
+            log.info(`Capture still running after ${this.waitMs} ms; not waiting`);
+    }
+    /**
+     * Make a capture the one later commands wait for.
+     *
+     * @param result - The capture's result
+     */
+    track(result) {
+        const ended = result.then(() => undefined, () => undefined);
+        this.capture = ended;
+        void ended.then(() => {
+            if (this.capture === ended)
+                this.capture = undefined;
+        });
+    }
+}
+//# sourceMappingURL=captureGate.js.map

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

@@ -12,9 +12,24 @@ import type { Logger } from '../../ui/logging/index.js';
 /**
  * Setup Chrome connection - either launch new instance or connect to existing.
  *
+ * @param config - Session configuration
+ * @param telemetryStore - Store receiving the target info
+ * @param log - Logger
+ * @param notify - Receives notices about an external Chrome
+ * @param signal - Ends a launch at once when aborted (the session was stopped)
  * @returns Launched Chrome instance (null if connecting to external Chrome)
  */
-export declare function setupChromeConnection(config: SessionConfig, telemetryStore: TelemetryStore, log: Logger, notify: NoticeSink<ChromeNoticeCode>): Promise<LaunchedChrome | null>;
+export declare function setupChromeConnection(config: SessionConfig, telemetryStore: TelemetryStore, log: Logger, notify: NoticeSink<ChromeNoticeCode>, signal?: AbortSignal): Promise<LaunchedChrome | null>;
+/**
+ * Browser-level DevTools WebSocket URL of the session's Chrome: a launched
+ * Chrome's, or for `--chrome-ws-url` the URL itself when it is browser-level,
+ * else the one Chrome reports, reached the way the user's URL is.
+ *
+ * @param config - Session configuration (port resolved)
+ * @param log - Logger
+ * @returns The URL, or null when Chrome does not answer `/json/version`
+ */
+export declare function browserWebSocketUrl(config: SessionConfig, log: Logger): Promise<string | null>;
 /**
  * Debugging port of an external Chrome, taken from its WebSocket URL.
  *

package/dist/daemon/session/chromeConnection.js

@@ -14,23 +14,47 @@ import { writeChromePid } from '../../session/chrome.js';
 import { findConflictingOwner } from '../../session/chromeOwners.js';
 import { getSessionDir } from '../../session/paths.js';
 import { EXIT_CODES } from '../../utils/exitCodes.js';
-import { createPageTarget, fetchCDPTargets, probeDevToolsEndpoint } from '../../utils/http.js';
+import { createPageTarget, fetchBrowserWsUrl, fetchCDPTargets, probeDevToolsEndpoint, } from '../../utils/http.js';
 import { filterDefined } from '../../utils/objects.js';
 /**
  * Setup Chrome connection - either launch new instance or connect to existing.
  *
+ * @param config - Session configuration
+ * @param telemetryStore - Store receiving the target info
+ * @param log - Logger
+ * @param notify - Receives notices about an external Chrome
+ * @param signal - Ends a launch at once when aborted (the session was stopped)
  * @returns Launched Chrome instance (null if connecting to external Chrome)
  */
-export async function setupChromeConnection(config, telemetryStore, log, notify) {
+export async function setupChromeConnection(config, telemetryStore, log, notify, signal) {
     if (config.chromeWsUrl) {
         return setupExternalChrome(config, telemetryStore, log, notify);
     }
     else {
-        return setupLaunchedChrome(config, log);
+        return setupLaunchedChrome(config, log, signal);
     }
 }
 /** Path of browser-level DevTools WebSocket URLs (`/devtools/browser/<uuid>`) */
 const BROWSER_WS_PATH = '/devtools/browser/';
+/**
+ * Browser-level DevTools WebSocket URL of the session's Chrome: a launched
+ * Chrome's, or for `--chrome-ws-url` the URL itself when it is browser-level,
+ * else the one Chrome reports, reached the way the user's URL is.
+ *
+ * @param config - Session configuration (port resolved)
+ * @param log - Logger
+ * @returns The URL, or null when Chrome does not answer `/json/version`
+ */
+export async function browserWebSocketUrl(config, log) {
+    if (!config.chromeWsUrl)
+        return fetchBrowserWsUrl(config.port, log);
+    const { hostname, pathname, protocol, port } = new URL(config.chromeWsUrl);
+    if (pathname.startsWith(BROWSER_WS_PATH))
+        return config.chromeWsUrl;
+    const http = { host: hostname, secure: protocol === 'wss:' };
+    const reported = await fetchBrowserWsUrl(config.port, log, http);
+    return reported && withEndpoint(reported, protocol, hostname, port);
+}
 /**
  * Debugging port of an external Chrome, taken from its WebSocket URL.
  *
@@ -162,12 +186,18 @@ export function windowSizeFlags(config) {
 }
 /**
  * Launch a new Chrome instance and record its PID for crash cleanup.
+ *
+ * @param config - Session configuration
+ * @param log - Logger
+ * @param signal - Ends the launch at once when aborted
+ * @returns Launched Chrome
  */
-async function setupLaunchedChrome(config, log) {
+async function setupLaunchedChrome(config, log, signal) {
     const chrome = await launchChrome({
         port: config.port,
         logger: log,
         sessionDir: getSessionDir(),
+        signal,
         ...filterDefined({
             userDataDir: config.userDataDir,
             headless: config.headless,

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

@@ -4,5 +4,20 @@ import type { SessionConfig } from './types.js';
 import type { CDPConnection } from '../../connection/cdp.js';
 import type { CleanupFunction } from '../../types.js';
 import type { Logger } from '../../ui/logging/index.js';
+/**
+ * Start the session's collectors (telemetry plugins) in order.
+ *
+ * When one fails to start, the ones already started are cleaned up (their
+ * failures logged) before the error is rethrown, so nothing they opened (a
+ * browser-level connection, event handlers) outlives the failed start.
+ *
+ * @param cdp - Page connection
+ * @param config - Session configuration
+ * @param store - Telemetry store
+ * @param logger - Logger
+ * @param plugins - Plugins to start (default: the registered ones)
+ * @returns Cleanup functions of the started collectors
+ * @throws The error of the collector that failed to start
+ */
 export declare function startTelemetryCollectors(cdp: CDPConnection, config: SessionConfig, store: TelemetryStore, logger: Logger, plugins?: TelemetryPlugin[]): Promise<CleanupFunction[]>;
 //# sourceMappingURL=collectors.d.ts.map

package/dist/daemon/session/collectors.js

@@ -1,6 +1,22 @@
 import { sessionActivatingCollector, sessionCollectorsActivated } from '../messages.js';
+import { getErrorMessage } from '../../utils/errors.js';
 import { getRegisteredTelemetryPlugins, shouldActivatePlugin } from './plugins.js';
 const DEFAULT_TELEMETRY = ['network', 'console', 'dom'];
+/**
+ * Start the session's collectors (telemetry plugins) in order.
+ *
+ * When one fails to start, the ones already started are cleaned up (their
+ * failures logged) before the error is rethrown, so nothing they opened (a
+ * browser-level connection, event handlers) outlives the failed start.
+ *
+ * @param cdp - Page connection
+ * @param config - Session configuration
+ * @param store - Telemetry store
+ * @param logger - Logger
+ * @param plugins - Plugins to start (default: the registered ones)
+ * @returns Cleanup functions of the started collectors
+ * @throws The error of the collector that failed to start
+ */
 export async function startTelemetryCollectors(cdp, config, store, logger, plugins) {
     const cleanupFunctions = [];
     store.activeTelemetry = config.telemetry ?? DEFAULT_TELEMETRY;
@@ -10,10 +26,31 @@ export async function startTelemetryCollectors(cdp, config, store, logger, plugi
             continue;
         }
         logger.debug(sessionActivatingCollector(plugin.name));
-        const cleanup = await plugin.start({ cdp, config, store, logger });
-        cleanupFunctions.push(cleanup);
+        try {
+            cleanupFunctions.push(await plugin.start({ cdp, config, store, logger }));
+        }
+        catch (error) {
+            await runCleanups(cleanupFunctions, logger);
+            throw error;
+        }
     }
     logger.debug(sessionCollectorsActivated(store.activeTelemetry));
     return cleanupFunctions;
 }
+/**
+ * Run cleanup functions, logging (not throwing) their failures.
+ *
+ * @param cleanups - Cleanup functions
+ * @param logger - Logger
+ */
+async function runCleanups(cleanups, logger) {
+    for (const cleanup of cleanups) {
+        try {
+            await cleanup();
+        }
+        catch (error) {
+            logger.debug(`Collector cleanup error: ${getErrorMessage(error)}`);
+        }
+    }
+}
 //# sourceMappingURL=collectors.js.map

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

@@ -1,11 +1,24 @@
 import type { TelemetryStore } from './TelemetryStore.js';
 import type { CDPConnection } from '../../connection/cdp.js';
+import { CommandError } from '../../errors/index.js';
 import type { CommandName, CommandSchemas } from '../../ipc/index.js';
 import { type SessionEmulation } from '../../runtime/page/emulation.js';
-type Handler<K extends CommandName> = (cdp: CDPConnection, params: CommandSchemas[K]['requestSchema']) => Promise<CommandSchemas[K]['responseSchema']>;
+/** A command's handler; `abandoned` aborts when its client disconnects */
+type Handler<K extends CommandName> = (cdp: CDPConnection, params: CommandSchemas[K]['requestSchema'], abandoned?: AbortSignal) => Promise<CommandSchemas[K]['responseSchema']>;
 export type CommandRegistry = {
     [K in CommandName]: Handler<K>;
 };
+/**
+ * A `bdg cdp` failure that is the caller's: a method this Chrome doesn't
+ * implement (83), wrong parameters (81), or an id of a node, target or frame
+ * that does not exist (83). Other failures (internal errors, a detached
+ * page) stay software errors.
+ *
+ * @param method - CDP method
+ * @param error - What the call threw
+ * @returns The error to report, or undefined to keep the original
+ */
+export declare function callerError(method: string, error: unknown): CommandError | undefined;
 /** The session's page emulation, which `page emulate` reads and changes */
 export interface EmulationState {
     get: () => SessionEmulation;