barebrowse 0.13.0 → 0.15.0

package/src/bidi.js

@@ -0,0 +1,143 @@
+/**
+ * bidi.js — Minimal WebDriver BiDi client over WebSocket (Firefox transport).
+ *
+ * The W3C-standard successor to CDP. CDP was deprecated in Firefox, so Firefox
+ * is driven over BiDi instead. This is the BiDi analogue of cdp.js: same
+ * JSON-RPC-over-WebSocket shape (id/method/params → result), same `ws`
+ * dependency and 256 MB maxPayload (a full AX snapshot of a large page is
+ * returned as one big string from script.evaluate — see ax-snapshot.js — and
+ * would blow the built-in WebSocket cap exactly as getFullAXTree did on CDP).
+ *
+ * Differences from CDP that shape this client:
+ *   - A session must be created explicitly (`session.new`) before any command.
+ *   - Events must be subscribed to (`session.subscribe`); we lean on
+ *     command results (navigate's `wait:'complete'`) instead where possible.
+ *   - Errors arrive as `{ type:'error', error, message }`, not `{ error:{} }`.
+ *   - Everything is scoped by `context` (a browsing-context id), not sessionId.
+ */
+
+import WebSocket from 'ws';
+
+/** Lift the message ceiling well past any realistic AX/DOM payload. */
+const MAX_PAYLOAD = 256 * 1024 * 1024; // 256 MB
+
+/**
+ * Create a BiDi client connected to the given /session WebSocket URL and open
+ * a session. Firefox prints its BiDi endpoint to stderr as
+ * "WebDriver BiDi listening on ws://HOST:PORT"; the direct-connection socket
+ * (no WebDriver-classic handshake) lives at that URL + "/session".
+ *
+ * @param {string} wsUrl - BiDi session WebSocket URL (ws://HOST:PORT/session)
+ * @returns {Promise<object>} BiDi client ({ send, evaluate, on, once, subscribe, sessionId, close })
+ */
+export async function createBiDi(wsUrl) {
+  const ws = new WebSocket(wsUrl, { maxPayload: MAX_PAYLOAD, perMessageDeflate: false });
+  let nextId = 1;
+  const pending = new Map();   // id → { resolve, reject }
+  const listeners = new Map(); // "method" → Set<callback>
+
+  /** @type {Promise<void>} */
+  const connected = new Promise((resolve, reject) => {
+    const timeout = setTimeout(() => reject(new Error('BiDi connection timeout (5s)')), 5000);
+    ws.onopen = () => { clearTimeout(timeout); resolve(); };
+    ws.onerror = (e) => {
+      clearTimeout(timeout);
+      reject(new Error(`BiDi WebSocket connection failed: ${e.message || 'unknown error'}`));
+    };
+  });
+  await connected;
+
+  ws.onmessage = (event) => {
+    const msg = JSON.parse(typeof event.data === 'string' ? event.data : event.data.toString());
+
+    // Command response (has id + type 'success' | 'error')
+    if (msg.id !== undefined && pending.has(msg.id)) {
+      const handler = pending.get(msg.id);
+      pending.delete(msg.id);
+      if (msg.type === 'error') {
+        handler.reject(new Error(`BiDi error: ${msg.error} — ${msg.message || ''}`.trim()));
+      } else {
+        handler.resolve(msg.result);
+      }
+      return;
+    }
+
+    // Event (type 'event', has method + params)
+    if (msg.type === 'event' && msg.method) {
+      const set = listeners.get(msg.method);
+      if (set) for (const cb of set) cb(msg.params);
+    }
+  };
+
+  ws.onclose = () => {
+    for (const [id, handler] of pending) {
+      handler.reject(new Error('BiDi WebSocket closed'));
+      pending.delete(id);
+    }
+  };
+
+  const client = {
+    /**
+     * Send a BiDi command and wait for its result.
+     * @param {string} method - e.g. 'browsingContext.navigate'
+     * @param {object} [params]
+     * @returns {Promise<object>} result
+     */
+    send(method, params = {}) {
+      const id = nextId++;
+      return new Promise((resolve, reject) => {
+        pending.set(id, { resolve, reject });
+        ws.send(JSON.stringify({ id, method, params }));
+      });
+    },
+
+    /**
+     * Evaluate an expression in a browsing context and return its value.
+     * Throws on an in-page exception (BiDi reports these as a `success`
+     * envelope with `type:'exception'`, unlike a protocol error).
+     * @param {string} context - browsing-context id
+     * @param {string} expression - JS source to evaluate
+     * @param {boolean} [awaitPromise=true]
+     * @returns {Promise<*>} the deserialized primitive value (result.value)
+     */
+    async evaluate(context, expression, awaitPromise = true) {
+      const res = await client.send('script.evaluate', {
+        expression, target: { context }, awaitPromise,
+      });
+      if (res.type === 'exception') {
+        const d = res.exceptionDetails;
+        throw new Error(`BiDi script exception: ${d?.text || d?.exception?.value || 'unknown'}`);
+      }
+      return res.result?.value;
+    },
+
+    /** Subscribe to BiDi events by method name (required before events fire). */
+    async subscribe(events) {
+      await client.send('session.subscribe', { events });
+    },
+
+    /** Register an event listener. Returns an unsubscribe function. */
+    on(method, callback) {
+      if (!listeners.has(method)) listeners.set(method, new Set());
+      listeners.get(method).add(callback);
+      return () => listeners.get(method)?.delete(callback);
+    },
+
+    /** Resolve once a named event fires (or reject on timeout). */
+    once(method, timeout = 30000) {
+      return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => { unsub(); reject(new Error(`Timeout waiting for BiDi event: ${method}`)); }, timeout);
+        const unsub = client.on(method, (params) => { clearTimeout(timer); unsub(); resolve(params); });
+      });
+    },
+
+    sessionId: null,
+    close() { ws.close(); },
+  };
+
+  // Open the session. capabilities:{} accepts Firefox's defaults.
+  const session = await client.send('session.new', { capabilities: {} });
+  client.sessionId = session.sessionId;
+  client.capabilities = session.capabilities;
+  return client;
+}

package/src/daemon.js

@@ -31,24 +31,25 @@ function tokenMatches(expected, got) {
 const SESSION_FILE = 'session.json';
 
 /**
- * Spawn a detached child process that runs the daemon.
- * Parent polls for session.json, then exits.
+ * Build the argv for the detached daemon child. Pure + exported so the
+ * flag-forwarding contract is unit-testable: a forward that's silently
+ * dropped here (as `--incognito` was in v0.15.0, turning `open --incognito`
+ * into a fully-authenticated session) becomes a failing test, not a leak.
+ * @param {object} opts - the session options parsed in cli.js cmdOpen
+ * @param {string} absDir - resolved output directory
+ * @param {string|undefined} initialUrl - URL to navigate on start (may be undefined)
+ * @param {string} cliPath - path to cli.js for the child to run
+ * @returns {string[]}
  */
-export async function startDaemon(opts, outputDir, initialUrl) {
-  const absDir = resolve(outputDir);
-  mkdirSync(absDir, { recursive: true, mode: 0o700 });
-
-  // Clean stale session
-  const sessionPath = join(absDir, SESSION_FILE);
-  if (existsSync(sessionPath)) unlinkSync(sessionPath);
-
-  // Build child args
-  const args = [join(import.meta.dirname, '..', 'cli.js'), '--daemon-internal'];
+export function buildDaemonArgs(opts, absDir, initialUrl, cliPath) {
+  const args = [cliPath, '--daemon-internal'];
   args.push('--output-dir', absDir);
   if (initialUrl) args.push('--url', initialUrl);
+  if (opts.engine) args.push('--engine', opts.engine);
   if (opts.mode) args.push('--mode', opts.mode);
   if (opts.port) args.push('--port', String(opts.port));
   if (opts.cookies === false) args.push('--no-cookies');
+  if (opts.incognito) args.push('--incognito');
   if (opts.browser) args.push('--browser', opts.browser);
   if (opts.timeout) args.push('--timeout', String(opts.timeout));
   if (opts.pruneMode) args.push('--prune-mode', opts.pruneMode);
@@ -63,6 +64,23 @@ export async function startDaemon(opts, outputDir, initialUrl) {
   }
   if (opts.blockPrivateNetwork) args.push('--block-private-network');
   if (opts.uploadDir) args.push('--upload-dir', opts.uploadDir);
+  return args;
+}
+
+/**
+ * Spawn a detached child process that runs the daemon.
+ * Parent polls for session.json, then exits.
+ */
+export async function startDaemon(opts, outputDir, initialUrl) {
+  const absDir = resolve(outputDir);
+  mkdirSync(absDir, { recursive: true, mode: 0o700 });
+
+  // Clean stale session
+  const sessionPath = join(absDir, SESSION_FILE);
+  if (existsSync(sessionPath)) unlinkSync(sessionPath);
+
+  // Build child args (pure + testable — see buildDaemonArgs).
+  const args = buildDaemonArgs(opts, absDir, initialUrl, join(import.meta.dirname, '..', 'cli.js'));
 
   const child = spawn(process.execPath, args, {
     detached: true,
@@ -104,6 +122,7 @@ export async function runDaemon(opts, outputDir, initialUrl) {
 
   // Connect to browser
   const page = await connect({
+    engine: opts.engine,
     mode: opts.mode || 'headless',
     port: opts.port ? Number(opts.port) : undefined,
     consent: opts.consent,
@@ -115,55 +134,63 @@ export async function runDaemon(opts, outputDir, initialUrl) {
     blockUrls: opts.blockUrls,
     blockPrivateNetwork: opts.blockPrivateNetwork,
     uploadDir: opts.uploadDir,
+    // incognito neuters injectCookies() session-wide; cookies:false (below)
+    // is the legacy per-open equivalent. Either yields a logged-out session.
+    incognito: opts.incognito || opts.cookies === false,
   });
 
-  // Console log capture
+  // Console + network log capture is CDP-specific (page.cdp). The Firefox/BiDi
+  // engine exposes page.bidi instead, so these captures are skipped there —
+  // console-logs / network-log commands return empty for a Firefox session.
+  // (BiDi log.entryAdded / network.* events could back these later.)
   const consoleLogs = [];
-  await page.cdp.send('Runtime.enable');
-  page.cdp.on('Runtime.consoleAPICalled', (params) => {
-    consoleLogs.push({
-      type: params.type,
-      timestamp: new Date().toISOString(),
-      args: params.args.map((a) => a.value ?? a.description ?? a.type),
-    });
-  });
-
-  // Network log capture (Network.enable already called by connect)
   const networkLogs = [];
   const pendingRequests = new Map();
 
-  page.cdp.on('Network.requestWillBeSent', (params) => {
-    pendingRequests.set(params.requestId, {
-      url: params.request.url,
-      method: params.request.method,
-      timestamp: new Date().toISOString(),
+  if (page.cdp) {
+    await page.cdp.send('Runtime.enable');
+    page.cdp.on('Runtime.consoleAPICalled', (params) => {
+      consoleLogs.push({
+        type: params.type,
+        timestamp: new Date().toISOString(),
+        args: params.args.map((a) => a.value ?? a.description ?? a.type),
+      });
     });
-  });
 
-  page.cdp.on('Network.responseReceived', (params) => {
-    const req = pendingRequests.get(params.requestId);
-    if (req) {
-      networkLogs.push({
-        ...req,
-        status: params.response.status,
-        statusText: params.response.statusText,
-        mimeType: params.response.mimeType,
+    // Network log capture (Network.enable already called by connect)
+    page.cdp.on('Network.requestWillBeSent', (params) => {
+      pendingRequests.set(params.requestId, {
+        url: params.request.url,
+        method: params.request.method,
+        timestamp: new Date().toISOString(),
       });
-      pendingRequests.delete(params.requestId);
-    }
-  });
+    });
 
-  page.cdp.on('Network.loadingFailed', (params) => {
-    const req = pendingRequests.get(params.requestId);
-    if (req) {
-      networkLogs.push({
-        ...req,
-        status: 0,
-        error: params.errorText,
-      });
-      pendingRequests.delete(params.requestId);
-    }
-  });
+    page.cdp.on('Network.responseReceived', (params) => {
+      const req = pendingRequests.get(params.requestId);
+      if (req) {
+        networkLogs.push({
+          ...req,
+          status: params.response.status,
+          statusText: params.response.statusText,
+          mimeType: params.response.mimeType,
+        });
+        pendingRequests.delete(params.requestId);
+      }
+    });
+
+    page.cdp.on('Network.loadingFailed', (params) => {
+      const req = pendingRequests.get(params.requestId);
+      if (req) {
+        networkLogs.push({
+          ...req,
+          status: 0,
+          error: params.errorText,
+        });
+        pendingRequests.delete(params.requestId);
+      }
+    });
+  }
 
   // Navigate to initial URL if provided
   if (initialUrl) {
@@ -316,6 +343,20 @@ export async function runDaemon(opts, outputDir, initialUrl) {
     },
 
     async eval({ expression }) {
+      // Firefox/BiDi has no page.cdp — evaluate over BiDi in the active context.
+      if (!page.cdp) {
+        try {
+          // BiDi's raw result.value serializes objects into a {type,value}
+          // entries structure, not a plain object (CDP's returnByValue does).
+          // Stringify + parse in-page so an object/array eval matches the CDP
+          // shape (same trick readable() uses). `undefined` → JSON `null`.
+          const wrapped = `(async () => { const v = await (${expression}); return JSON.stringify(v === undefined ? null : v); })()`;
+          const raw = await page.bidi.evaluate(page.context, wrapped, true);
+          return { ok: true, value: raw == null ? null : JSON.parse(raw) };
+        } catch (err) {
+          return { ok: false, error: err.message || 'eval error' };
+        }
+      }
       const result = await page.cdp.send('Runtime.evaluate', {
         expression,
         returnByValue: true,