browser-debugger-cli 0.8.0 → 0.9.0

package/dist/session/port.js

@@ -3,14 +3,15 @@
  *
  * Handles automatic port selection and persistence for session isolation.
  * Each session directory can have its own persistent port, enabling multiple
- * concurrent bdg sessions with different BDG_SESSION_DIR values.
+ * concurrent bdg sessions (named sessions or different BDG_SESSION_DIR values).
  */
 import * as fs from 'fs';
 import * as net from 'net';
 import { isPortAnswering } from '../connection/portReservation.js';
 import { DEFAULT_CDP_PORT } from '../constants.js';
 import { CommandError } from '../errors/index.js';
-import { ensureSessionDir, getSessionFilePath } from './paths.js';
+import { ensureSessionDir, getSessionFilePath, getSessionName } from './paths.js';
+import { portsClaimedByOtherSessions, readPortFile, withPortLock } from './portClaims.js';
 import { EXIT_CODES } from '../utils/exitCodes.js';
 /**
  * Port range for automatic selection.
@@ -20,7 +21,7 @@ const PORT_RANGE_START = DEFAULT_CDP_PORT;
 const PORT_RANGE_END = 9322; // Allow 100 ports for concurrent sessions
 /**
  * Check if a port is available (not in use by any process, including one
- * listening on all interfaces).
+ * listening on all interfaces or on ::1 only).
  *
  * @param port - Port number to check
  * @returns Promise resolving to true if port is available
@@ -40,20 +41,31 @@ async function isPortAvailable(port) {
         });
     });
 }
+/**
+ * First port tried for this session: the default session starts at
+ * DEFAULT_CDP_PORT, named sessions one above so they leave it to the default
+ * session.
+ *
+ * @returns First candidate port
+ */
+export function firstCandidatePort() {
+    return getSessionName() === null ? PORT_RANGE_START : PORT_RANGE_START + 1;
+}
 /**
  * Find an available port starting from a given port.
  *
  * @param startPort - Port to start scanning from
+ * @param claimed - Ports to skip (claimed by other sessions)
  * @returns Promise resolving to an available port
- * @throws Error if no available port found in range
+ * @throws CommandError if no available port found in range
  */
-async function findAvailablePort(startPort = PORT_RANGE_START) {
+export async function findAvailablePort(startPort = PORT_RANGE_START, claimed = new Set()) {
     for (let port = startPort; port <= PORT_RANGE_END; port++) {
-        if (await isPortAvailable(port)) {
+        if (!claimed.has(port) && (await isPortAvailable(port))) {
             return port;
         }
     }
-    throw new CommandError(`No available port found in range ${PORT_RANGE_START}-${PORT_RANGE_END}.`, { suggestion: 'Stop some bdg sessions or Chrome instances and retry.' }, EXIT_CODES.SOFTWARE_ERROR);
+    throw new CommandError(`No available port found in range ${startPort}-${PORT_RANGE_END}.`, { suggestion: 'Stop some bdg sessions or Chrome instances and retry.' }, EXIT_CODES.SOFTWARE_ERROR);
 }
 /**
  * Read the saved port from the session directory.
@@ -61,21 +73,8 @@ async function findAvailablePort(startPort = PORT_RANGE_START) {
  * @returns Saved port number or null if not found/invalid
  */
 export function readSessionPort() {
-    try {
-        const portPath = getSessionFilePath('PORT');
-        if (!fs.existsSync(portPath)) {
-            return null;
-        }
-        const content = fs.readFileSync(portPath, 'utf-8').trim();
-        const port = parseInt(content, 10);
-        if (isNaN(port) || port < 1 || port > 65535) {
-            return null;
-        }
-        return port;
-    }
-    catch {
-        return null;
-    }
+    const portPath = getSessionFilePath('PORT');
+    return fs.existsSync(portPath) ? readPortFile(portPath) : null;
 }
 /**
  * Save the port to the session directory.
@@ -91,34 +90,42 @@ export function writeSessionPort(port) {
  * Get or allocate a port for this session.
  *
  * Logic:
- * 1. If a port is explicitly provided, use it (user override)
- * 2. Check if there's a saved port in the session directory
- * 3. If saved port exists and is available, reuse it (session stability)
- * 4. Otherwise, find a new available port and save it
+ * 1. If a port is explicitly provided, use it (user override; a named session
+ *    saves and claims it under the lock so other sessions skip it)
+ * 2. Otherwise, under a lock shared by all sessions on the machine (any
+ *    BDG_SESSION_DIR), reuse the saved port if it is free and no other
+ *    running session claims it (session stability)
+ * 3. Otherwise, take the first free, unclaimed port from
+ *    {@link firstCandidatePort} upwards and save it (the claim)
  *
- * This provides session isolation: different BDG_SESSION_DIR values
- * will automatically use different ports.
+ * The claim is also recorded in the machine-wide registry (under the lock),
+ * so sessions of other base directories skip it too.
+ *
+ * This provides session isolation: named sessions and different
+ * BDG_SESSION_DIR values automatically use different ports, even when they
+ * start at the same time.
  *
  * @param explicitPort - User-provided port (takes precedence)
  * @returns Promise resolving to the port to use
  */
 export async function getSessionPort(explicitPort) {
-    // User explicitly specified a port - use it directly
     if (explicitPort !== undefined && explicitPort !== null) {
-        return explicitPort;
-    }
-    // Check for saved session port
-    const savedPort = readSessionPort();
-    if (savedPort !== null) {
-        // Verify the saved port is still available
-        if (await isPortAvailable(savedPort)) {
-            return savedPort;
-        }
-        // Saved port is in use by another process, need to find a new one
+        if (getSessionName() === null)
+            return explicitPort;
+        return withPortLock((recordClaim) => {
+            writeSessionPort(explicitPort);
+            recordClaim(explicitPort);
+            return Promise.resolve(explicitPort);
+        });
     }
-    // Find a new available port
-    const newPort = await findAvailablePort();
-    writeSessionPort(newPort);
-    return newPort;
+    return withPortLock(async (recordClaim) => {
+        const claimed = portsClaimedByOtherSessions();
+        const savedPort = readSessionPort();
+        const reuse = savedPort !== null && !claimed.has(savedPort) && (await isPortAvailable(savedPort));
+        const port = reuse ? savedPort : await findAvailablePort(firstCandidatePort(), claimed);
+        writeSessionPort(port);
+        recordClaim(port);
+        return port;
+    });
 }
 //# sourceMappingURL=port.js.map

package/dist/session/portClaims.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Port claims across concurrent sessions.
+ *
+ * Sessions started at the same time must not pick the same CDP port: Chrome
+ * binds it only after the choice is made. A session claims its port by
+ * writing `port.txt` while holding a lock; a running session's claim is
+ * skipped by the others.
+ *
+ * Ports belong to the machine, not to a session directory, so the lock and a
+ * registry of claiming session directories live in one directory per user
+ * under the OS temp directory: sessions of different `BDG_SESSION_DIR`s see
+ * each other's claims too. That directory is used only if it is a real
+ * directory owned by the user that nobody else can write to; otherwise the
+ * lock falls back to the base session directory and only that directory's
+ * claims are seen (the launched Chrome's identity is still checked).
+ */
+/** Records a port claim; a no-op when the registry cannot be used safely */
+export type RecordPortClaim = (port: number) => void;
+/**
+ * Read a port number from a `port.txt` file.
+ *
+ * @param portPath - File path
+ * @returns Port, or null if missing or invalid
+ */
+export declare function readPortFile(portPath: string): number | null;
+/**
+ * Directory holding the port lock and the claims registry, shared by every
+ * session of the user on this machine.
+ *
+ * @returns `$BDG_PORT_REGISTRY_DIR`, else `<os temp dir>/bdg-ports-<uid>`
+ */
+export declare function getPortRegistryDir(): string;
+/**
+ * Whether a path is a directory the current user can trust: a real directory
+ * (not a symlink), owned by the user, not writable by group or others.
+ *
+ * @param dir - Directory
+ * @returns Why it cannot be trusted, or null if it can
+ */
+export declare function untrustedDirReason(dir: string): string | null;
+/**
+ * Session directories other than the selected one that bdg knows of: those of
+ * this base directory, and those of any base directory found in the
+ * machine-wide registry. They need not hold a running session.
+ *
+ * @returns Session directories
+ */
+export declare function otherSessionDirs(): string[];
+/**
+ * Ports claimed by other sessions that are running or starting (their daemon
+ * socket exists), see {@link otherSessionDirs}.
+ *
+ * @returns Claimed ports
+ */
+export declare function portsClaimedByOtherSessions(): Set<number>;
+/**
+ * Run port selection under the lock shared by all sessions of the user on
+ * this machine (in the trusted registry directory; else in the base session
+ * directory). If the lock cannot be taken in time, the selection runs anyway.
+ *
+ * @param select - Chooses the port; gets a function recording the claim in
+ *   the registry, a no-op without the registry lock
+ * @returns The chosen port
+ */
+export declare function withPortLock(select: (recordClaim: RecordPortClaim) => Promise<number>): Promise<number>;
+//# sourceMappingURL=portClaims.d.ts.map

package/dist/session/portClaims.js

@@ -0,0 +1,284 @@
+/**
+ * Port claims across concurrent sessions.
+ *
+ * Sessions started at the same time must not pick the same CDP port: Chrome
+ * binds it only after the choice is made. A session claims its port by
+ * writing `port.txt` while holding a lock; a running session's claim is
+ * skipped by the others.
+ *
+ * Ports belong to the machine, not to a session directory, so the lock and a
+ * registry of claiming session directories live in one directory per user
+ * under the OS temp directory: sessions of different `BDG_SESSION_DIR`s see
+ * each other's claims too. That directory is used only if it is a real
+ * directory owned by the user that nobody else can write to; otherwise the
+ * lock falls back to the base session directory and only that directory's
+ * claims are seen (the launched Chrome's identity is still checked).
+ */
+import * as fs from 'fs';
+import * as os from 'os';
+import * as path from 'path';
+import { getSessionBaseDir, getSessionDir, listSessionDirs, sessionFilePathIn, } from './paths.js';
+import { createLogger, logDebugError } from '../ui/logging/index.js';
+import { delay } from '../utils/async.js';
+const log = createLogger('session');
+/** Lock file guarding port selection, in the port registry (or base session) directory */
+const PORT_LOCK_FILE = 'port.lock';
+/** Subdirectory of the port registry: one file per claimed port, holding the claiming session directory */
+const CLAIMS_DIR = 'claims';
+/** Overrides the port registry directory (tests) */
+const PORT_REGISTRY_DIR_ENV = 'BDG_PORT_REGISTRY_DIR';
+/** How long to wait for the lock before choosing a port without it */
+const LOCK_WAIT_MS = 5000;
+/** Lock age after which its holder is assumed dead */
+const STALE_LOCK_MS = 10000;
+const LOCK_POLL_MS = 25;
+/** Permission bits that let other users write */
+const GROUP_OTHER_WRITE = 0o022;
+/**
+ * Read a port number from a `port.txt` file.
+ *
+ * @param portPath - File path
+ * @returns Port, or null if missing or invalid
+ */
+export function readPortFile(portPath) {
+    try {
+        const port = parseInt(fs.readFileSync(portPath, 'utf-8').trim(), 10);
+        return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
+    }
+    catch (error) {
+        logDebugError(log, `read ${portPath}`, error);
+        return null;
+    }
+}
+/**
+ * Directory holding the port lock and the claims registry, shared by every
+ * session of the user on this machine.
+ *
+ * @returns `$BDG_PORT_REGISTRY_DIR`, else `<os temp dir>/bdg-ports-<uid>`
+ */
+export function getPortRegistryDir() {
+    const override = process.env[PORT_REGISTRY_DIR_ENV]?.trim();
+    if (override)
+        return path.resolve(override);
+    const uid = process.getuid?.();
+    return path.join(os.tmpdir(), uid === undefined ? 'bdg-ports' : `bdg-ports-${uid}`);
+}
+/**
+ * Whether a path is a directory the current user can trust: a real directory
+ * (not a symlink), owned by the user, not writable by group or others.
+ *
+ * @param dir - Directory
+ * @returns Why it cannot be trusted, or null if it can
+ */
+export function untrustedDirReason(dir) {
+    const stat = fs.lstatSync(dir);
+    if (!stat.isDirectory())
+        return 'not a directory';
+    const uid = process.getuid?.();
+    if (uid !== undefined && stat.uid !== uid)
+        return `owned by uid ${stat.uid}`;
+    if (process.platform !== 'win32' && (stat.mode & GROUP_OTHER_WRITE) !== 0) {
+        return `writable by others (mode ${(stat.mode & 0o777).toString(8)})`;
+    }
+    return null;
+}
+/**
+ * The port registry directory, created (mode 0700) if missing, if it can be
+ * trusted (see {@link untrustedDirReason}).
+ *
+ * @param create - Create the directory (and its claims subdirectory) if missing
+ * @returns The directory, or null if it is missing or untrusted
+ */
+function trustedRegistryDir(create) {
+    const dir = getPortRegistryDir();
+    try {
+        if (create) {
+            fs.mkdirSync(path.dirname(dir), { recursive: true });
+            fs.mkdirSync(path.join(dir, CLAIMS_DIR), { recursive: true, mode: 0o700 });
+        }
+        if (!fs.existsSync(dir))
+            return null;
+        const reason = untrustedDirReason(dir) ?? untrustedDirReason(path.join(dir, CLAIMS_DIR));
+        if (reason === null)
+            return dir;
+        log.info(`Not using the port registry ${dir} (${reason}); port claims are per directory`);
+    }
+    catch (error) {
+        logDebugError(log, `use the port registry ${dir}`, error);
+    }
+    return null;
+}
+/**
+ * Record in the registry that this session directory claims a port. Written
+ * to a new temporary file that is renamed into place, so no symlink is
+ * followed. The claim holds while that session runs and its `port.txt` names
+ * the port; it needs no removal.
+ *
+ * @param registryDir - Trusted registry directory
+ * @param port - Claimed port
+ */
+function writePortClaim(registryDir, port) {
+    const claimPath = path.join(registryDir, CLAIMS_DIR, String(port));
+    const tempPath = `${claimPath}.${process.pid}.tmp`;
+    try {
+        fs.writeFileSync(tempPath, getSessionDir(), { encoding: 'utf8', flag: 'wx', mode: 0o600 });
+        fs.renameSync(tempPath, claimPath);
+    }
+    catch (error) {
+        logDebugError(log, `record the claim of port ${port}`, error);
+        fs.rmSync(tempPath, { force: true });
+    }
+}
+/**
+ * Session directories in the registry (any base directory).
+ *
+ * @returns Claiming session directories; none if the registry is untrusted
+ */
+function registeredSessionDirs() {
+    const registryDir = trustedRegistryDir(false);
+    if (registryDir === null)
+        return [];
+    const claimsDir = path.join(registryDir, CLAIMS_DIR);
+    try {
+        return fs
+            .readdirSync(claimsDir)
+            .filter((file) => /^\d+$/.test(file))
+            .map((file) => readClaim(path.join(claimsDir, file)))
+            .filter((dir) => dir !== null);
+    }
+    catch (error) {
+        logDebugError(log, `list ${claimsDir}`, error);
+        return [];
+    }
+}
+/**
+ * Read the session directory of one claim.
+ *
+ * @param claimPath - Claim file
+ * @returns Absolute session directory, or null if unreadable or partly written
+ */
+function readClaim(claimPath) {
+    try {
+        const dir = fs.readFileSync(claimPath, 'utf8').trim();
+        return path.isAbsolute(dir) ? dir : null;
+    }
+    catch (error) {
+        logDebugError(log, `read ${claimPath}`, error);
+        return null;
+    }
+}
+/**
+ * Session directories other than the selected one that bdg knows of: those of
+ * this base directory, and those of any base directory found in the
+ * machine-wide registry. They need not hold a running session.
+ *
+ * @returns Session directories
+ */
+export function otherSessionDirs() {
+    const ownDir = getSessionDir();
+    const dirs = new Set([...listSessionDirs().map(({ dir }) => dir), ...registeredSessionDirs()]);
+    return [...dirs].filter((dir) => dir !== ownDir);
+}
+/**
+ * Ports claimed by other sessions that are running or starting (their daemon
+ * socket exists), see {@link otherSessionDirs}.
+ *
+ * @returns Claimed ports
+ */
+export function portsClaimedByOtherSessions() {
+    const ports = otherSessionDirs()
+        .filter((dir) => fs.existsSync(sessionFilePathIn(dir, 'DAEMON_SOCKET')))
+        .map((dir) => readPortFile(sessionFilePathIn(dir, 'PORT')));
+    return new Set(ports.filter((port) => port !== null));
+}
+/**
+ * Take the port-selection lock.
+ *
+ * @param lockPath - Lock file path
+ * @param token - Written into the lock so only its owner removes it
+ * @returns True if the lock was taken; false after {@link LOCK_WAIT_MS} or
+ *   when the lock file cannot be created
+ */
+async function acquireLock(lockPath, token) {
+    const deadline = Date.now() + LOCK_WAIT_MS;
+    while (Date.now() < deadline) {
+        try {
+            fs.writeFileSync(lockPath, token, { flag: 'wx' });
+            return true;
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST') {
+                logDebugError(log, 'take the port lock', error);
+                return false;
+            }
+            removeStaleLock(lockPath);
+            await delay(LOCK_POLL_MS);
+        }
+    }
+    return false;
+}
+/**
+ * Remove a lock left by a process that died while holding it. The lock is
+ * moved aside first (only one waiter's rename succeeds); if another process
+ * took a fresh lock in the meantime, that one is put back.
+ *
+ * @param lockPath - Lock file path
+ */
+function removeStaleLock(lockPath) {
+    try {
+        if (Date.now() - fs.statSync(lockPath).mtimeMs <= STALE_LOCK_MS)
+            return;
+        const staleOwner = fs.readFileSync(lockPath, 'utf8');
+        const moved = `${lockPath}.${process.pid}.stale`;
+        fs.renameSync(lockPath, moved);
+        if (fs.readFileSync(moved, 'utf8') !== staleOwner)
+            fs.linkSync(moved, lockPath);
+        fs.rmSync(moved, { force: true });
+    }
+    catch (error) {
+        logDebugError(log, 'check the port lock', error);
+    }
+}
+/**
+ * Release the lock if it is still ours (it may have been taken over as stale).
+ *
+ * @param lockPath - Lock file path
+ * @param token - The token written when the lock was taken
+ */
+function releaseLock(lockPath, token) {
+    try {
+        if (fs.readFileSync(lockPath, 'utf8') === token)
+            fs.rmSync(lockPath, { force: true });
+    }
+    catch (error) {
+        logDebugError(log, 'release the port lock', error);
+    }
+}
+/**
+ * Run port selection under the lock shared by all sessions of the user on
+ * this machine (in the trusted registry directory; else in the base session
+ * directory). If the lock cannot be taken in time, the selection runs anyway.
+ *
+ * @param select - Chooses the port; gets a function recording the claim in
+ *   the registry, a no-op without the registry lock
+ * @returns The chosen port
+ */
+export async function withPortLock(select) {
+    const registryDir = trustedRegistryDir(true);
+    const lockDir = registryDir ?? getSessionBaseDir();
+    fs.mkdirSync(lockDir, { recursive: true });
+    const lockPath = path.join(lockDir, PORT_LOCK_FILE);
+    const token = `${process.pid}-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+    const locked = await acquireLock(lockPath, token);
+    if (!locked)
+        log.debug('Port lock busy; choosing a port without it');
+    const recordClaim = locked && registryDir !== null ? (port) => writePortClaim(registryDir, port) : () => { };
+    try {
+        return await select(recordClaim);
+    }
+    finally {
+        if (locked)
+            releaseLock(lockPath, token);
+    }
+}
+//# sourceMappingURL=portClaims.js.map

package/dist/session/sessionList.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Sessions across the default and named session directories (`bdg sessions`):
+ * running ones, and ones whose daemon died and left a Chrome or files behind.
+ */
+import type { StatusResponseData } from '../ipc/session/queries.js';
+import { type SocketProbeResult } from './daemonSocket.js';
+import { type SessionDirEntry } from './paths.js';
+/**
+ * State of a session: its daemon runs (`active`, `starting`, `ending`,
+ * `unresponsive`), or died and left its Chrome running (`crashed`) or only
+ * files (`stale`).
+ */
+export type RunningSessionState = 'active' | 'starting' | 'ending' | 'unresponsive' | 'crashed' | 'stale';
+/**
+ * One session in the list.
+ */
+export interface RunningSessionInfo {
+    /** Session name, or null for the default session */
+    name: string | null;
+    state: RunningSessionState;
+    /** Current page URL (or the URL being opened while starting) */
+    url?: string;
+    /** CDP port */
+    port?: number;
+    daemonPid?: number;
+    /** Chrome launched by bdg (absent for an attached Chrome) */
+    chromePid?: number;
+    /** Command that cleans up a crashed or stale session */
+    cleanup?: string;
+}
+/**
+ * Summarize a daemon's status response.
+ *
+ * @param name - Session name
+ * @param data - Status data
+ * @returns Session info
+ */
+export declare function toRunningSession(name: string | null, data: StatusResponseData): RunningSessionInfo;
+/**
+ * A session whose daemon is gone: `crashed` while the Chrome bdg launched for
+ * it still runs, `stale` when only its files are left. Nothing is changed on
+ * disk; `cleanup` names the command that removes them.
+ *
+ * @param entry - Session directory
+ * @param probe - Result of probing its daemon socket
+ * @returns Session info, or null when the directory holds no session state
+ */
+export declare function describeLeftovers({ name, dir }: SessionDirEntry, probe: SocketProbeResult): RunningSessionInfo | null;
+/**
+ * Every session: the default one first, then named sessions by name. Includes
+ * crashed and stale sessions, and directories `--session` cannot reach, so
+ * their leftovers can be cleaned up. A directory differing only in case
+ * (`ALPHA`) that `--session alpha` reaches is listed once, as `alpha`.
+ *
+ * @returns Sessions
+ */
+export declare function listRunningSessions(): Promise<RunningSessionInfo[]>;
+//# sourceMappingURL=sessionList.d.ts.map