browser-commander 0.27.0 → 0.28.0

package/src/browser/persistent-session.js

@@ -0,0 +1,360 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { randomUUID } from 'node:crypto';
+import { fileURLToPath } from 'node:url';
+import { connectBrowser, pickForegroundPage } from './connector.js';
+import { launchAndConnectRealBrowserWithDependencies } from './real-browser.js';
+import { assertDedicatedUserDataDir } from './system-browser.js';
+import { startDetachedProcess } from '../utilities/subprocess.js';
+
+export const SESSION_METADATA = '.browser-commander-session.json';
+const activity = new WeakMap();
+export function touchSessionPage(page) {
+  activity.get(page)?.();
+}
+const read = (file) =>
+  fs
+    .readFile(file, 'utf8')
+    .then(JSON.parse)
+    .catch(() => null);
+export async function writeSessionMetadata(file, value) {
+  const temporary = `${file}.${randomUUID()}.tmp`;
+  try {
+    await fs.writeFile(temporary, JSON.stringify(value), { mode: 0o600 });
+    await fs.rename(temporary, file);
+  } finally {
+    await fs.rm(temporary, { force: true });
+  }
+}
+export function probeSession(endpoint) {
+  return fetch(`${endpoint}/json/version`, {
+    signal: AbortSignal.timeout(1000),
+  })
+    .then((r) => (r.ok ? r.json() : null))
+    .catch(() => null);
+}
+export async function acquireLease(file, retries = 50) {
+  let lease;
+  try {
+    lease = await fs.open(file, 'wx', 0o600);
+  } catch (error) {
+    if (error.code !== 'EEXIST') {
+      throw error;
+    }
+    const owner = await read(file);
+    if (retries > 0) {
+      let alive = !owner?.pid;
+      if (owner?.pid) {
+        try {
+          process.kill(owner.pid, 0);
+          alive = true;
+        } catch (error) {
+          alive = error.code !== 'ESRCH';
+        }
+      }
+      if (alive) {
+        await new Promise((resolve) => setTimeout(resolve, 20));
+        return acquireLease(file, retries - 1);
+      }
+    }
+    if (!owner?.pid) {
+      throw new Error('Persistent session launch is already in progress', {
+        cause: error,
+      });
+    }
+    let alive = true;
+    try {
+      process.kill(owner.pid, 0);
+    } catch (error) {
+      alive = error.code !== 'ESRCH';
+    }
+    if (alive) {
+      throw new Error('Persistent session launch is already in progress', {
+        cause: error,
+      });
+    }
+    await fs.rm(file);
+    lease = await fs.open(file, 'wx', 0o600);
+  }
+  const token = randomUUID();
+  await lease.writeFile(JSON.stringify({ pid: process.pid, token }));
+  return async () => {
+    await lease.close();
+    if ((await read(file))?.token === token) {
+      await fs.rm(file, { force: true });
+    }
+  };
+}
+function validate(options) {
+  if (
+    !options.userDataDir ||
+    !Number.isInteger(options.remoteDebuggingPort) ||
+    options.remoteDebuggingPort < 1 ||
+    options.remoteDebuggingPort > 65535
+  ) {
+    throw new TypeError(
+      'connectOrLaunch requires a dedicated userDataDir and fixed remoteDebuggingPort'
+    );
+  }
+  if (!Number.isFinite(options.idleTimeoutMs) || options.idleTimeoutMs <= 0) {
+    throw new RangeError('idleTimeoutMs must be positive');
+  }
+  if (!['playwright', 'puppeteer'].includes(options.engine)) {
+    throw new TypeError('Persistent sessions require a Chromium CDP engine');
+  }
+  assertDedicatedUserDataDir(options.userDataDir);
+}
+async function open(options, file, endpoint) {
+  let metadata = await read(file);
+  const version = await probeSession(endpoint);
+  if (version) {
+    if (
+      !metadata ||
+      metadata.remoteDebuggingPort !== options.remoteDebuggingPort ||
+      metadata.webSocketDebuggerUrl !== version.webSocketDebuggerUrl
+    ) {
+      throw new Error('Debugging port belongs to another browser/profile');
+    }
+    const session = await connectBrowser({
+      ...options,
+      cdpEndpoint: endpoint,
+      targetId:
+        options.targetId ?? (!options.url ? metadata.targetId : undefined),
+    });
+    return { session, metadata, reused: true };
+  }
+  const session = await launchAndConnectRealBrowserWithDependencies(
+    { ...options, keepOpen: false },
+    {
+      spawnBrowser: (file, args, settings) =>
+        startDetachedProcess(file, args, settings),
+    }
+  );
+  try {
+    const version = await probeSession(endpoint);
+    if (!version) {
+      throw new Error('Persistent browser endpoint disappeared after launch');
+    }
+    metadata = {
+      token: randomUUID(),
+      pid: session.browserProcess.pid,
+      userDataDir: path.resolve(options.userDataDir),
+      remoteDebuggingPort: options.remoteDebuggingPort,
+      webSocketDebuggerUrl: version.webSocketDebuggerUrl,
+    };
+    return { session, metadata, reused: false };
+  } catch (error) {
+    await session.close();
+    throw error;
+  }
+}
+async function remember(page, engine, file, metadata, idleTimeoutMs) {
+  const cdp =
+    engine === 'playwright'
+      ? await page.context().newCDPSession(page)
+      : await page.target().createCDPSession();
+  try {
+    metadata.targetId = (
+      await cdp.send('Target.getTargetInfo')
+    ).targetInfo.targetId;
+  } finally {
+    await cdp.detach();
+  }
+  metadata.lastActive = Date.now();
+  metadata.idleTimeoutMs = idleTimeoutMs;
+  await writeSessionMetadata(file, metadata);
+}
+export async function closeOwnedSession(file, metadata) {
+  if ((await read(file))?.token !== metadata.token) {
+    return;
+  }
+  const version = await probeSession(
+    `http://127.0.0.1:${metadata.remoteDebuggingPort}`
+  );
+  if (version?.webSocketDebuggerUrl === metadata.webSocketDebuggerUrl) {
+    await closeRemoteBrowser(version.webSocketDebuggerUrl);
+  }
+  await fs.rm(file, { force: true });
+}
+async function lifecycle(
+  { session, metadata, reused },
+  options,
+  file,
+  endpoint
+) {
+  const { engine, idleTimeoutMs } = options;
+  let page = session.page,
+    disconnected = false,
+    closed = false,
+    activityQueue = Promise.resolve();
+  const touch = () => {
+    activityQueue = activityQueue
+      .then(async () => {
+        const release = await acquireLease(`${file}.lock`);
+        try {
+          const current = await read(file);
+          if (current?.token === metadata.token) {
+            current.lastActive = Date.now();
+            await writeSessionMetadata(file, current);
+          }
+        } finally {
+          await release();
+        }
+      })
+      .catch(() => {});
+  };
+  const bind = (value) => {
+    activity.set(value, touch);
+    value.on?.('framenavigated', touch);
+  };
+  const unbind = (value) => {
+    activity.delete(value);
+    value.off?.('framenavigated', touch);
+  };
+  await remember(page, engine, file, metadata, idleTimeoutMs);
+  bind(page);
+  const detach = async () => {
+    if (disconnected) {
+      return;
+    }
+    touch();
+    await activityQueue;
+    unbind(page);
+    disconnected = true;
+    try {
+      await session.downloads?.dispose();
+    } finally {
+      await session.detach();
+    }
+  };
+  const close = async () => {
+    if (closed) {
+      return;
+    }
+    if (!disconnected) {
+      await detach().catch(() => {});
+    }
+    const release = await acquireLease(`${file}.lock`);
+    try {
+      await closeOwnedSession(file, metadata);
+    } finally {
+      await release();
+    }
+    closed = true;
+  };
+  const result = {
+    ...session,
+    detach,
+    close,
+    touch,
+    reused,
+    cdpEndpoint: endpoint,
+    userDataDir: path.resolve(options.userDataDir),
+    remoteDebuggingPort: options.remoteDebuggingPort,
+    temporaryProfile: false,
+  };
+  result.reusePage = async (selection = {}) => {
+    if (disconnected) {
+      throw new Error('Persistent controller is detached');
+    }
+    const release = await acquireLease(`${file}.lock`);
+    try {
+      const current = await read(file);
+      if (current?.token !== metadata.token) {
+        throw new Error('Persistent session ownership changed');
+      }
+      const pages =
+        engine === 'playwright'
+          ? page.context().pages()
+          : await session.browser.pages();
+      const selected = await pickForegroundPage(pages, {
+        targetId:
+          selection.targetId ??
+          (!selection.url ? metadata.targetId : undefined),
+        ...selection,
+      });
+      if (!selected) {
+        throw new Error('No reusable browser page');
+      }
+      unbind(page);
+      page = selected;
+      bind(page);
+      result.page = page;
+      await remember(page, engine, file, metadata, idleTimeoutMs);
+    } finally {
+      await release();
+    }
+    return page;
+  };
+  if (!reused) {
+    await startDetachedProcess(process.execPath, [
+      fileURLToPath(new URL('./session-watchdog.js', import.meta.url)),
+      file,
+      metadata.token,
+    ]);
+  }
+  return result;
+}
+export async function closeRemoteBrowser(endpoint) {
+  await new Promise((resolve, reject) => {
+    const socket = new globalThis.WebSocket(endpoint);
+    let acknowledged = false;
+    const timer = setTimeout(() => {
+      socket.close();
+      reject(new Error('Browser.close timed out'));
+    }, 3000);
+    socket.onopen = () =>
+      socket.send(JSON.stringify({ id: 1, method: 'Browser.close' }));
+    socket.onclose = () => {
+      clearTimeout(timer);
+      resolve();
+    };
+    socket.onerror = () => {
+      // Chrome can close the TCP connection without a WebSocket close frame
+      // after acknowledging Browser.close. Its ensuing close event completes
+      // shutdown; a pre-acknowledgement connection error remains a failure.
+      if (!acknowledged) {
+        clearTimeout(timer);
+        reject(new Error('Browser.close connection failed'));
+      }
+    };
+    socket.onmessage = ({ data }) => {
+      const response = JSON.parse(data);
+      if (response.id !== 1) {
+        return;
+      }
+      if (response.error) {
+        clearTimeout(timer);
+        reject(new Error(response.error.message ?? 'Browser.close failed'));
+        socket.close();
+      } else {
+        acknowledged = true;
+      }
+    };
+  });
+}
+/** Reuse an owned profile/port; detach survives the controller; close terminates it. */
+export async function connectOrLaunch(settings = {}) {
+  const options = {
+    engine: 'playwright',
+    idleTimeoutMs: 30 * 60 * 1000,
+    ...settings,
+  };
+  validate(options);
+  await fs.mkdir(options.userDataDir, { recursive: true, mode: 0o700 });
+  const file = path.join(path.resolve(options.userDataDir), SESSION_METADATA);
+  const release = await acquireLease(`${file}.lock`);
+  const endpoint = `http://127.0.0.1:${options.remoteDebuggingPort}`;
+  let owned;
+  try {
+    owned = await open(options, file, endpoint);
+    return await lifecycle(owned, options, file, endpoint);
+  } catch (error) {
+    if (owned && !owned.reused) {
+      await owned.session.close().catch(() => {});
+    }
+    throw error;
+  } finally {
+    await release();
+  }
+}

package/src/browser/profile-directory.js

@@ -106,6 +106,26 @@ export async function configureUserDataDir(
 ) {
   assertObject(preferences, 'preferences');
   assertObject(localState, 'localState');
+  for (const key of [
+    'session.restore_on_startup',
+    'session.startup_urls',
+    'homepage',
+    'homepage_is_newtabpage',
+    'browser.show_home_button',
+    'extensions.settings',
+    'default_search_provider_data',
+  ]) {
+    let value = preferences;
+    for (const part of key.split('.')) {
+      value = value?.[part];
+    }
+    if (value !== undefined || Object.hasOwn(preferences, key)) {
+      process.emitWarning(
+        `Chrome protects ${key} in Secure Preferences and may reset this value. Use browser settings or managed policy to set it.`,
+        { code: 'PROTECTED_CHROME_PREFERENCE' }
+      );
+    }
+  }
   if (
     defaultBrowserCheck !== undefined &&
     typeof defaultBrowserCheck !== 'boolean'

package/src/browser/real-browser.js

@@ -103,6 +103,7 @@ export function buildRealBrowserArgs({
   remoteDebuggingPort,
   headless = false,
   restrictions = [],
+  disableFeatures = [],
   args = [],
   extraArgs = [],
   automationParity = true,
@@ -127,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 (
@@ -642,6 +643,7 @@ export async function launchAndConnectRealBrowserWithDependencies(
   const argOptions = {
     headless,
     restrictions,
+    disableFeatures: options.disableFeatures,
     args,
     extraArgs,
     automationParity,
@@ -700,7 +702,10 @@ export async function launchAndConnectRealBrowserWithDependencies(
   await removingTemporaryProfileOnError(profile, () =>
     configureUserDataDir(userDataDir, {
       defaultBrowserCheck,
-      preferences,
+      preferences: {
+        ...resolveRestrictions(restrictions).preferences,
+        ...preferences,
+      },
       localState,
       profileDirectory: attach?.profile ?? 'Default',
     })

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-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,
+    })
+  );
+}

package/src/browser/webdriver.js

@@ -326,6 +326,7 @@ export function buildBrowserOptions({
   remoteDebuggingPort,
   headless,
   restrictions,
+  disableFeatures,
   args,
   automationParity,
   bidi,
@@ -358,6 +359,7 @@ export function buildBrowserOptions({
       remoteDebuggingPort,
       headless,
       restrictions,
+      disableFeatures,
       args,
       automationParity,
     });
@@ -556,6 +558,7 @@ async function launchWebDriverOnce(options, dependencies) {
     bidi = false,
     args = [],
     restrictions = [],
+    disableFeatures = [],
     automationParity = true,
     env,
     startupTimeout = 30_000,
@@ -627,6 +630,7 @@ async function launchWebDriverOnce(options, dependencies) {
         browser === 'chrome' ? await reservePort() : undefined,
       headless,
       restrictions,
+      disableFeatures,
       args,
       automationParity,
       bidi,