browser-commander 0.26.3 → 0.28.0

package/src/browser/real-browser.js

@@ -1,3 +1,8 @@
+import { launchFailure, redactLaunchEvidence } from './launch-diagnostics.js';
+import {
+  installSessionPersistence,
+  sessionPersistencePath,
+} from './session-persistence.js';
 import { readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { findBrowserSource } from './browser-sources.js';
@@ -98,6 +103,7 @@ export function buildRealBrowserArgs({
   remoteDebuggingPort,
   headless = false,
   restrictions = [],
+  disableFeatures = [],
   args = [],
   extraArgs = [],
   automationParity = true,
@@ -122,7 +128,7 @@ export function buildRealBrowserArgs({
     `--user-data-dir=${userDataDir}`,
     `--remote-debugging-port=${remoteDebuggingPort}`,
     ...(headless ? ['--headless=new'] : []),
-    ...resolveRestrictions(restrictions).args,
+    ...resolveRestrictions(restrictions, { disableFeatures }).args,
     ...customArgs,
   ]);
   if (
@@ -187,56 +193,66 @@ export async function waitForCdpEndpoint({
   timeout = 30_000,
   fetchImplementation = globalThis.fetch,
 }) {
-  const port = assertFixedDebuggingPort(remoteDebuggingPort);
-  const endpoint = `http://${LOOPBACK_HOST}:${port}`;
-  const deadline = Date.now() + timeout;
-  while (Date.now() < deadline) {
-    const output = devToolsOutput.state();
-    let ownership = devToolsOutput.available
-      ? classifyDevToolsOwnership(output, port)
-      : 'unknown';
-    if (ownership === 'race') {
-      throw new PortRaceError(port, output.listening?.url ?? 'bind failed');
-    }
-    if (browserProcess.exitCode !== null) {
-      throw new Error(
-        `Browser exited before its DevTools endpoint was ready (exit ${browserProcess.exitCode})`
-      );
-    }
-    if (ownership !== 'owned') {
-      const activePort = await readDevToolsActivePort(userDataDir);
-      if (activePort?.port === port) {
-        ownership = 'owned';
+  try {
+    const port = assertFixedDebuggingPort(remoteDebuggingPort);
+    const endpoint = `http://${LOOPBACK_HOST}:${port}`;
+    const deadline = Date.now() + timeout;
+    while (Date.now() < deadline) {
+      const output = devToolsOutput.state();
+      let ownership = devToolsOutput.available
+        ? classifyDevToolsOwnership(output, port)
+        : 'unknown';
+      if (ownership === 'race') {
+        throw new PortRaceError(port, output.listening?.url ?? 'bind failed');
       }
-    }
-
-    if (ownership === 'owned') {
-      let version = null;
-      try {
-        version = await fetchCdpVersion(
-          endpoint,
-          fetchImplementation,
-          Math.max(1, deadline - Date.now())
+      if (browserProcess.exitCode !== null) {
+        throw (
+          browserProcess.spawnError ??
+          Object.assign(
+            new Error(
+              `Browser exited before its DevTools endpoint was ready (exit ${browserProcess.exitCode})`
+            ),
+            { stderrTail: browserProcess.stderrTail }
+          )
         );
-      } catch {
-        // The HTTP handler can lag the listening line by a moment.
       }
-      if (version) {
-        const expected = output.listening?.url;
-        if (expected && version.webSocketDebuggerUrl !== expected) {
-          throw new PortRaceError(
-            port,
-            `port serves ${version.webSocketDebuggerUrl}, browser announced ${expected}`
+      if (ownership !== 'owned') {
+        const activePort = await readDevToolsActivePort(userDataDir);
+        if (activePort?.port === port) {
+          ownership = 'owned';
+        }
+      }
+
+      if (ownership === 'owned') {
+        let version = null;
+        try {
+          version = await fetchCdpVersion(
+            endpoint,
+            fetchImplementation,
+            Math.max(1, deadline - Date.now())
           );
+        } catch {
+          // The HTTP handler can lag the listening line by a moment.
+        }
+        if (version) {
+          const expected = output.listening?.url;
+          if (expected && version.webSocketDebuggerUrl !== expected) {
+            throw new PortRaceError(
+              port,
+              `port serves ${version.webSocketDebuggerUrl}, browser announced ${expected}`
+            );
+          }
+          return endpoint;
         }
-        return endpoint;
       }
+      await new Promise((resolve) => setTimeout(resolve, 100));
     }
-    await new Promise((resolve) => setTimeout(resolve, 100));
+    throw new Error(
+      `Timed out after ${timeout}ms waiting for the DevTools endpoint on port ${port}`
+    );
+  } finally {
+    devToolsOutput.dispose?.();
   }
-  throw new Error(
-    `Timed out after ${timeout}ms waiting for the DevTools endpoint on port ${port}`
-  );
 }
 
 function spawnWithStartProcess(executablePath, args, { env, verbose }) {
@@ -251,13 +267,19 @@ async function waitForExit(browserProcess, timeout) {
     return false;
   }
   let timer;
+  const onExit = () => resolveExit(true);
+  let resolveExit;
   const exited = await Promise.race([
-    new Promise((resolve) => browserProcess.once('exit', () => resolve(true))),
+    new Promise((resolve) => {
+      resolveExit = resolve;
+      browserProcess.once('exit', onExit);
+    }),
     new Promise((resolve) => {
       timer = setTimeout(() => resolve(false), timeout);
     }),
   ]);
   clearTimeout(timer);
+  browserProcess.removeListener?.('exit', onExit);
   return exited;
 }
 
@@ -369,6 +391,7 @@ async function spawnOnFreePort({
   userDataDir,
   startupTimeout,
   dependencies,
+  diagnostics,
 }) {
   const reservePort = dependencies.reservePort ?? reserveLoopbackPort;
   const spawnBrowser = dependencies.spawnBrowser ?? spawnWithStartProcess;
@@ -381,10 +404,20 @@ async function spawnOnFreePort({
       userDataDir,
       remoteDebuggingPort: port,
     });
-    const browserProcess = spawnBrowser(executablePath, browserArgs, {
-      env,
-      verbose,
-    });
+    let browserProcess;
+    try {
+      browserProcess = await spawnBrowser(executablePath, browserArgs, {
+        env,
+        verbose: false,
+      });
+    } catch (error) {
+      throw launchFailure(error, {
+        ...diagnostics,
+        phase: 'spawn',
+        executablePath,
+        userDataDir,
+      });
+    }
     try {
       const cdpEndpoint = await waitForEndpoint({
         remoteDebuggingPort: port,
@@ -397,13 +430,24 @@ async function spawnOnFreePort({
       if (browserProcess.exitCode === null) {
         browserProcess.kill();
       }
+      await waitForExit(browserProcess, 5_000);
       if (!(error instanceof PortRaceError) || attempt >= attempts) {
-        throw error;
+        throw launchFailure(error, {
+          ...diagnostics,
+          phase: 'endpoint',
+          browserProcess,
+          executablePath,
+          userDataDir,
+        });
       }
       if (verbose) {
-        console.log(`${error.message}; retrying with a new port`);
+        console.log(
+          redactLaunchEvidence(
+            `${error.message}; retrying with a new port`,
+            diagnostics?.diagnosticRedactor
+          )
+        );
       }
-      await waitForExit(browserProcess, 5_000);
     }
   }
 }
@@ -565,6 +609,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
   options = {},
   dependencies = {}
 ) {
+  sessionPersistencePath(options);
   if (isSafariChannel(options.channel ?? options.browser)) {
     return launchSafari(options, dependencies);
   }
@@ -598,6 +643,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
   const argOptions = {
     headless,
     restrictions,
+    disableFeatures: options.disableFeatures,
     args,
     extraArgs,
     automationParity,
@@ -614,10 +660,22 @@ export async function launchAndConnectRealBrowserWithDependencies(
 
   const resolveExecutable =
     dependencies.resolveExecutable ?? resolveSystemBrowserExecutable;
-  const executablePath = await resolveExecutable({
-    channel,
-    executablePath: requestedExecutablePath,
-  });
+  const launchChannel = attach?.browser ?? channel;
+  const executablePath = await Promise.resolve()
+    .then(() =>
+      resolveExecutable({
+        channel: launchChannel,
+        executablePath: requestedExecutablePath,
+      })
+    )
+    .catch((error) => {
+      throw launchFailure(error, {
+        ...options,
+        phase: 'discovery',
+        engine,
+        executablePath: requestedExecutablePath,
+      });
+    });
 
   const temporaryProfile = !requestedUserDataDir;
   const { userDataDir, snapshotLaunch } = await prepareProfile({
@@ -644,7 +702,10 @@ export async function launchAndConnectRealBrowserWithDependencies(
   await removingTemporaryProfileOnError(profile, () =>
     configureUserDataDir(userDataDir, {
       defaultBrowserCheck,
-      preferences,
+      preferences: {
+        ...resolveRestrictions(restrictions).preferences,
+        ...preferences,
+      },
       localState,
       profileDirectory: attach?.profile ?? 'Default',
     })
@@ -661,6 +722,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
       userDataDir,
       startupTimeout,
       dependencies,
+      diagnostics: { engine, diagnosticRedactor: options.diagnosticRedactor },
     })
   );
   const { browserProcess, cdpEndpoint: resolvedCdpEndpoint } = launched;
@@ -694,19 +756,22 @@ export async function launchAndConnectRealBrowserWithDependencies(
       closeTimeout,
       closeConnection: engine === 'selenium' ? connection.close : undefined,
     });
-    return {
-      ...connection,
-      close,
-      browserProcess,
-      cdpEndpoint: resolvedCdpEndpoint,
-      remoteDebuggingPort: launched.port,
-      executablePath,
-      userDataDir,
-      temporaryProfile,
-      args: launched.browserArgs,
-      ...(migration ? { migration } : {}),
-      ...(snapshotLaunch ? { attach: snapshotLaunch.attach } : {}),
-    };
+    return await installSessionPersistence(
+      {
+        ...connection,
+        close,
+        browserProcess,
+        cdpEndpoint: resolvedCdpEndpoint,
+        remoteDebuggingPort: launched.port,
+        executablePath,
+        userDataDir,
+        temporaryProfile,
+        args: launched.browserArgs,
+        ...(migration ? { migration } : {}),
+        ...(snapshotLaunch ? { attach: snapshotLaunch.attach } : {}),
+      },
+      options
+    );
   } catch (error) {
     if (browserProcess.exitCode === null) {
       browserProcess.kill();
@@ -715,7 +780,14 @@ export async function launchAndConnectRealBrowserWithDependencies(
     if (temporaryProfile) {
       await removeUserDataDir(userDataDir);
     }
-    throw error;
+    throw launchFailure(error, {
+      ...options,
+      phase: 'connect',
+      engine,
+      browserProcess,
+      executablePath,
+      userDataDir,
+    });
   }
 }
 

package/src/browser/restrictions.js

@@ -73,11 +73,14 @@ function expand(names) {
  * @param {string[]} [names]
  * @returns {{ids: string[], args: string[], env: Object<string,string>}}
  */
-export function resolveRestrictions(names = []) {
+export function resolveRestrictions(names = [], options = {}) {
   const ids = expand(names);
   const args = [];
-  const disableFeatures = [];
+  const disableFeatures = [
+    ...assertStringArray(options.disableFeatures ?? [], 'disableFeatures'),
+  ];
   const env = {};
+  const preferences = {};
   for (const id of ids) {
     const restriction = LAUNCH_RESTRICTIONS.find((entry) => entry.id === id);
     if (!restriction) {
@@ -91,11 +94,17 @@ export function resolveRestrictions(names = []) {
     args.push(...(restriction.args ?? []));
     disableFeatures.push(...(restriction.disableFeatures ?? []));
     Object.assign(env, restriction.env ?? {});
+    for (const [key, value] of Object.entries(restriction.preferences ?? {})) {
+      preferences[key] =
+        value && typeof value === 'object'
+          ? { ...preferences[key], ...value }
+          : value;
+    }
   }
   if (disableFeatures.length > 0) {
-    args.push(`--disable-features=${disableFeatures.join(',')}`);
+    args.push(`--disable-features=${[...new Set(disableFeatures)].join(',')}`);
   }
-  return { ids, args, env };
+  return { ids, args, env, preferences };
 }
 
 const LIST_SWITCHES = [

package/src/browser/session-cookies.js

@@ -0,0 +1,78 @@
+import { matchesDomains } from './migration/domains.js';
+import { restoreWebDriverStorageState } from './storage-state.js';
+
+/** Normalize cookie shape without turning session cookies into expired cookies. */
+export function normalizeSessionCookies(cookies, engine) {
+  if (!Array.isArray(cookies)) {
+    throw new TypeError('cookies must be an array');
+  }
+  return cookies.map(({ expires, ...cookie }) => ({
+    ...cookie,
+    ...(cookie.sameSite
+      ? {
+          sameSite:
+            cookie.sameSite[0].toUpperCase() +
+            cookie.sameSite.slice(1).toLowerCase(),
+        }
+      : {}),
+    ...(Number.isFinite(expires) && expires > 0
+      ? { expires }
+      : engine === 'playwright' && expires !== undefined
+        ? { expires: -1 }
+        : {}),
+  }));
+}
+
+/** Add cookies to the current context, including cookies for other origins. */
+export async function setCookies({ page, engine, cookies } = {}) {
+  const normalized = normalizeSessionCookies(cookies, engine);
+  if (engine === 'playwright') {
+    return page.context().addCookies(normalized);
+  }
+  if (engine === 'selenium' && !(await page.bidi?.())) {
+    return restoreWebDriverStorageState({
+      page,
+      storageState: { cookies: normalized, origins: [] },
+    });
+  }
+  const context = page.browserContext?.();
+  if (typeof context?.setCookie === 'function') {
+    return context.setCookie(...normalized);
+  }
+  if (typeof page.browser?.().setCookie === 'function') {
+    return page.browser().setCookie(...normalized);
+  }
+  return page.setCookie(...normalized);
+}
+
+/** Clear the context or only cookies whose domain matches the requested site. */
+export async function clearCookies({ page, engine, domain } = {}) {
+  if (engine === 'playwright' && !domain) {
+    return page.context().clearCookies();
+  }
+  const context =
+    engine === 'playwright' ? page.context() : page.browserContext?.();
+  const cookies =
+    engine === 'playwright'
+      ? await context.cookies()
+      : typeof context?.cookies === 'function'
+        ? await context.cookies()
+        : await page.cookies();
+  const selected = cookies.filter(
+    (cookie) => !domain || matchesDomains(cookie.domain, [domain])
+  );
+  if (engine === 'playwright') {
+    for (const cookie of selected) {
+      await context.clearCookies({
+        name: cookie.name,
+        domain: cookie.domain,
+        path: cookie.path,
+      });
+    }
+  } else if (typeof context?.deleteCookie === 'function') {
+    await context.deleteCookie(...selected);
+  } else {
+    await page.deleteCookie(...selected);
+  }
+  return selected.length;
+}

package/src/browser/session-persistence.js

@@ -0,0 +1,72 @@
+import path from 'node:path';
+import { access } from 'node:fs/promises';
+import { assertDedicatedUserDataDir } from './system-browser.js';
+import {
+  saveStorageState,
+  writeRestrictedState,
+  loadStorageState,
+  restorePlaywrightStorageState,
+  restorePuppeteerStorageState,
+  restoreWebDriverStorageState,
+} from './storage-state.js';
+
+const installed = Symbol('sessionPersistence');
+export function sessionPersistencePath(options) {
+  if (!options.persistSessionCookies) {
+    return null;
+  }
+  if (!options.userDataDir || options.attach) {
+    throw new TypeError(
+      'persistSessionCookies requires an explicit dedicated userDataDir'
+    );
+  }
+  assertDedicatedUserDataDir(options.userDataDir);
+  return typeof options.persistSessionCookies === 'string'
+    ? options.persistSessionCookies
+    : path.join(options.userDataDir, 'browser-commander-session.json');
+}
+export async function installSessionPersistence(result, options) {
+  const file = sessionPersistencePath(options);
+  if (!file || result[installed]) {
+    return result;
+  }
+  const engine = options.engine ?? 'playwright';
+  if (
+    await access(file).then(
+      () => true,
+      () => false
+    )
+  ) {
+    const storageState = await loadStorageState(file);
+    if (engine === 'playwright') {
+      await restorePlaywrightStorageState({
+        context: result.page.context(),
+        storageState,
+      });
+    } else if (engine === 'puppeteer') {
+      await restorePuppeteerStorageState({ page: result.page, storageState });
+    } else {
+      await restoreWebDriverStorageState({ page: result.page, storageState });
+    }
+  }
+  const close = result.close;
+  let closing;
+  const persistAndClose = () =>
+    (closing ??= (async () => {
+      try {
+        const state = await saveStorageState(result.page);
+        await writeRestrictedState(file, {
+          cookies: state.cookies.filter((cookie) => !(cookie.expires > 0)),
+          origins: [],
+        });
+      } finally {
+        await close();
+      }
+    })());
+  result.close = persistAndClose;
+  if (typeof result.browser?.close === 'function') {
+    result.browser.close = persistAndClose;
+  }
+  result[installed] = true;
+  return result;
+}

package/src/browser/session-watchdog.js

@@ -0,0 +1,71 @@
+import fs from 'node:fs/promises';
+import {
+  probeSession,
+  closeRemoteBrowser,
+  acquireLease,
+} from './persistent-session.js';
+const [, , file, token] = process.argv;
+const read = () =>
+  fs
+    .readFile(file, 'utf8')
+    .then(JSON.parse)
+    .catch(() => null);
+while (true) {
+  const session = await read();
+  if (session?.token !== token) {
+    break;
+  }
+  await new Promise((resolve) =>
+    setTimeout(
+      resolve,
+      Math.min(30_000, Math.max(100, session.idleTimeoutMs / 10))
+    )
+  );
+  const current = await read();
+  if (current?.token !== token) {
+    break;
+  }
+  if (Date.now() - current.lastActive < current.idleTimeoutMs) {
+    continue;
+  }
+  let release;
+  try {
+    release = await acquireLease(`${file}.lock`);
+  } catch {
+    continue;
+  }
+  try {
+    const version = await probeSession(
+      `http://127.0.0.1:${current.remoteDebuggingPort}`
+    );
+    const latest = await read();
+    if (latest?.token !== token) {
+      break;
+    }
+    if (Date.now() - latest.lastActive < latest.idleTimeoutMs) {
+      continue;
+    }
+    if (!version) {
+      try {
+        process.kill(current.pid, 0);
+        continue;
+      } catch (error) {
+        if (error.code !== 'ESRCH') {
+          continue;
+        }
+      }
+    } else if (version.webSocketDebuggerUrl === current.webSocketDebuggerUrl) {
+      try {
+        await closeRemoteBrowser(version.webSocketDebuggerUrl);
+      } catch {
+        continue;
+      }
+    }
+    if ((await read())?.token === token) {
+      await fs.rm(file, { force: true });
+    }
+    break;
+  } finally {
+    await release();
+  }
+}

package/src/browser/session-worker.js

@@ -0,0 +1,70 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import {
+  connectOrLaunch,
+  SESSION_METADATA,
+  closeOwnedSession,
+  writeSessionMetadata,
+  acquireLease,
+} from './persistent-session.js';
+let input = '';
+for await (const chunk of process.stdin) {
+  input += chunk;
+  if (input.length > 1024 * 1024) {
+    throw new RangeError('session options exceed 1 MiB');
+  }
+}
+const options = JSON.parse(input);
+const file = path.join(path.resolve(options.userDataDir), SESSION_METADATA);
+if (options.operation) {
+  const release = await acquireLease(`${file}.lock`);
+  try {
+    let metadata;
+    try {
+      metadata = JSON.parse(await fs.readFile(file, 'utf8'));
+    } catch (error) {
+      if (
+        error.code === 'ENOENT' &&
+        ['close', 'touch'].includes(options.operation)
+      ) {
+        process.stdout.write('{}');
+        process.exitCode = 0;
+      } else {
+        throw error;
+      }
+    }
+    if (metadata) {
+      if (metadata.token !== options.token) {
+        throw new Error('Persistent session ownership changed');
+      }
+      if (options.operation === 'close') {
+        await closeOwnedSession(file, metadata);
+      } else if (options.operation === 'touch') {
+        metadata.lastActive = Date.now();
+        if (options.targetId) {
+          metadata.targetId = options.targetId;
+        }
+        await writeSessionMetadata(file, metadata);
+      } else {
+        throw new TypeError('Unknown session operation');
+      }
+      process.stdout.write('{}');
+    }
+  } finally {
+    await release();
+  }
+} else {
+  const session = await connectOrLaunch(options);
+  await session.detach();
+  const metadata = JSON.parse(await fs.readFile(file, 'utf8'));
+  process.stdout.write(
+    JSON.stringify({
+      cdpEndpoint: session.cdpEndpoint,
+      userDataDir: session.userDataDir,
+      remoteDebuggingPort: session.remoteDebuggingPort,
+      reused: session.reused,
+      token: metadata.token,
+      targetId: metadata.targetId,
+    })
+  );
+}