@monoes/monobrowse 1.0.13 → 1.0.14

package/src/__tests__/cdp-transport.test.ts

@@ -0,0 +1,198 @@
+/**
+ * The transport seam under CdpClient.
+ *
+ * Two halves: WebSocketTransport must behave exactly as the inlined `ws`
+ * handling it replaced (that is what keeps the 474 existing tests honest),
+ * and CdpClient must drive *any* transport — the whole point of the seam,
+ * since the bridge-backed one is not a socket to a local Chrome at all.
+ */
+import { describe, expect, it, vi } from 'vitest';
+
+// --- fake `ws` -------------------------------------------------------------
+let lastSocket: FakeWs | null = null;
+
+class FakeWs {
+  handlers = new Map<string, Array<(...a: unknown[]) => void>>();
+  sent: string[] = [];
+  closed = false;
+  sendError: Error | null = null;
+
+  constructor(public url: string) {
+    lastSocket = this;
+  }
+
+  on(event: string, fn: (...a: unknown[]) => void): void {
+    if (!this.handlers.has(event)) this.handlers.set(event, []);
+    this.handlers.get(event)!.push(fn);
+  }
+
+  emit(event: string, ...args: unknown[]): void {
+    for (const fn of [...(this.handlers.get(event) ?? [])]) fn(...args);
+  }
+
+  send(data: string, cb?: (err?: Error) => void): void {
+    this.sent.push(data);
+    cb?.(this.sendError ?? undefined);
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+}
+
+vi.mock('ws', () => ({ WebSocket: FakeWs }));
+
+const { WebSocketTransport } = await import('../browser/transport.js');
+const { CdpClient } = await import('../browser/cdp.js');
+
+import type { CdpTransport, CdpTransportHandlers } from '../browser/transport.js';
+
+/** Collects what a transport hands back up to its owner. */
+function recorder(): CdpTransportHandlers & {
+  messages: string[];
+  closes: Array<Error | undefined>;
+} {
+  const messages: string[] = [];
+  const closes: Array<Error | undefined> = [];
+  const errors: Error[] = [];
+  return {
+    messages,
+    closes,
+    message: (d: string) => void messages.push(d),
+    close: (e?: Error) => void closes.push(e),
+    error: (e: Error) => void errors.push(e),
+  };
+}
+
+describe('WebSocketTransport', () => {
+  it('opens on the socket "open" event and reports the url it dialed', async () => {
+    const t = new WebSocketTransport('ws://127.0.0.1:9222/devtools/page/ABC');
+    const p = t.open(recorder());
+    lastSocket!.emit('open');
+    await p;
+    expect(lastSocket!.url).toBe('ws://127.0.0.1:9222/devtools/page/ABC');
+  });
+
+  it('rejects open() when the socket errors before it ever opened', async () => {
+    const t = new WebSocketTransport('ws://127.0.0.1:1/devtools');
+    const p = t.open(recorder());
+    lastSocket!.emit('error', new Error('ECONNREFUSED'));
+    await expect(p).rejects.toThrow('ECONNREFUSED');
+  });
+
+  it('routes a post-open error to error(), not to a rejected open()', async () => {
+    const h = recorder();
+    const errors: Error[] = [];
+    h.error = (e: Error) => void errors.push(e);
+    const t = new WebSocketTransport('ws://x');
+    const p = t.open(h);
+    lastSocket!.emit('open');
+    await p;
+    lastSocket!.emit('error', new Error('EPIPE'));
+    expect(errors.map((e) => e.message)).toEqual(['EPIPE']);
+  });
+
+  it('delivers messages as strings and reports close', async () => {
+    const h = recorder();
+    const t = new WebSocketTransport('ws://x');
+    const p = t.open(h);
+    lastSocket!.emit('open');
+    await p;
+    lastSocket!.emit('message', Buffer.from('{"id":1}'));
+    expect(h.messages).toEqual(['{"id":1}']);
+    lastSocket!.emit('close');
+    expect(h.closes).toHaveLength(1);
+  });
+
+  it('rejects send() with the socket error and closes the socket on close()', async () => {
+    const t = new WebSocketTransport('ws://x');
+    const p = t.open(recorder());
+    lastSocket!.emit('open');
+    await p;
+    await expect(t.send('{"id":1}')).resolves.toBeUndefined();
+    expect(lastSocket!.sent).toEqual(['{"id":1}']);
+    lastSocket!.sendError = new Error('socket gone');
+    await expect(t.send('{"id":2}')).rejects.toThrow('socket gone');
+    t.close();
+    expect(lastSocket!.closed).toBe(true);
+  });
+});
+
+// --- CdpClient over an arbitrary transport ---------------------------------
+
+/** A transport with no socket at all: the test *is* the other end. */
+class ScriptedTransport implements CdpTransport {
+  sent: string[] = [];
+  closed = false;
+  private handlers: CdpTransportHandlers | null = null;
+
+  async open(handlers: CdpTransportHandlers): Promise<void> {
+    this.handlers = handlers;
+  }
+
+  async send(frame: string): Promise<void> {
+    this.sent.push(frame);
+  }
+
+  close(): void {
+    this.closed = true;
+  }
+
+  /** Push a frame up as if it had arrived from the other side. */
+  deliver(msg: unknown): void {
+    this.handlers!.message(JSON.stringify(msg));
+  }
+
+  drop(err?: Error): void {
+    this.handlers!.close(err);
+  }
+}
+
+describe('CdpClient.connectTransport', () => {
+  it('round-trips a command through a transport that is not a socket', async () => {
+    const t = new ScriptedTransport();
+    const client = new CdpClient();
+    await client.connectTransport(t);
+    expect(client.isConnected()).toBe(true);
+
+    const pending = client.send<{ frameId: string }>('Page.navigate', { url: 'https://x.test' });
+    const sent = JSON.parse(t.sent[0]);
+    expect(sent.method).toBe('Page.navigate');
+    expect(sent.params).toEqual({ url: 'https://x.test' });
+
+    t.deliver({ id: sent.id, result: { frameId: 'F1' } });
+    expect(await pending).toEqual({ frameId: 'F1' });
+  });
+
+  it('dispatches events with their sessionId to listeners', async () => {
+    const t = new ScriptedTransport();
+    const client = new CdpClient();
+    await client.connectTransport(t);
+
+    const seen: Array<[Record<string, unknown>, string | undefined]> = [];
+    client.on('Network.responseReceived', (params, sid) => void seen.push([params, sid]));
+    t.deliver({ method: 'Network.responseReceived', params: { requestId: 'R1' }, sessionId: 'S1' });
+
+    expect(seen).toEqual([[{ requestId: 'R1' }, 'S1']]);
+  });
+
+  it('flushes in-flight commands when the transport drops', async () => {
+    const t = new ScriptedTransport();
+    const client = new CdpClient();
+    await client.connectTransport(t);
+
+    const pending = client.send('Page.enable');
+    t.drop(new Error('bridge disconnected'));
+    await expect(pending).rejects.toThrow('bridge disconnected');
+    expect(client.isConnected()).toBe(false);
+  });
+
+  it('closes the transport when the client closes', async () => {
+    const t = new ScriptedTransport();
+    const client = new CdpClient();
+    await client.connectTransport(t);
+    client.close();
+    expect(t.closed).toBe(true);
+    await expect(client.send('Page.enable')).rejects.toThrow('CDP not connected');
+  });
+});

package/src/browser/bridge.ts

@@ -0,0 +1,354 @@
+import { enableSessionDomains } from './browser.js';
+import { CdpClient } from './cdp.js';
+import type { CdpTransport, CdpTransportHandlers } from './transport.js';
+import { WebSocketTransport } from './transport.js';
+
+/**
+ * CDP over the MonoAgent extension bridge.
+ *
+ * The extension already holds Chrome's `debugger` permission and attaches to
+ * tabs with `chrome.debugger.attach`; mono-agent's Go server already owns the
+ * WebSocket to it. This transport puts CDP frames on that path — out through
+ * the relay's `/monoagent/cdp` socket, into `chrome.debugger.sendCommand`,
+ * and back — so a CdpClient can drive the browser the user is actually
+ * signed into rather than a headless Chrome we launched. Every instrument
+ * built on CdpClient (console, network, HAR, vitals, trace, CPU profiler,
+ * snapshot, screenshot, emulation) comes along unchanged.
+ *
+ * Two mismatches have to be reconciled here, and they are the whole job:
+ *
+ * **Sessions.** Against a raw socket, monobrowse attaches to a target and
+ * carries the resulting `sessionId` on every command and every event.
+ * `chrome.debugger` has no such id for the tab: the debuggee *is* the page
+ * session, and a `sessionId` on the wire means a *child* session (an
+ * out-of-process iframe). So this transport mints a stable synthetic id for
+ * the tab, strips it on the way out, stamps it onto relayed events on the
+ * way in, and passes any other id through untouched for real child sessions.
+ *
+ * **Attachment.** A socket is opened; a debuggee is attached. open() does the
+ * attach and fails if it cannot, rather than handing back a transport whose
+ * first command would fail. close() detaches, which is what takes Chrome's
+ * "…started debugging this browser" banner off the user's tab.
+ *
+ * Known gaps, which are Chrome's and not this file's: `chrome.debugger`
+ * exposes a fixed set of domains, and `HeapProfiler` and `Browser` are not
+ * among them, so heap snapshots and `Browser.close` fail over the bridge.
+ */
+
+/** Header the Go relay authenticates with; mirrors internal/extension/token.go. */
+export const BRIDGE_TOKEN_HEADER = 'X-Monoagent-Extension-Token';
+
+/** Default relay endpoint; mirrors the extension server's default port. */
+export const DEFAULT_BRIDGE_URL = 'ws://127.0.0.1:9222/monoagent/cdp';
+
+/** How long the attach handshake may take before open() gives up. */
+const DEFAULT_ATTACH_TIMEOUT_MS = 15_000;
+
+/** The synthetic target id standing in for a Chrome tab. */
+export function bridgeTargetId(tabId: number): string {
+  return `bridge-tab-${tabId}`;
+}
+
+/** The synthetic session id standing in for a tab's page session. */
+export function bridgeSessionId(tabId: number): string {
+  return `bridge-session-${tabId}`;
+}
+
+/** True for ids this transport minted, as opposed to real CDP child sessions. */
+export function isBridgeSessionId(sessionId: string | undefined): boolean {
+  return typeof sessionId === 'string' && sessionId.startsWith('bridge-session-');
+}
+
+export interface BridgeTransportOptions {
+  /**
+   * The Chrome tab to drive. Omit it to drive whichever tab the user is
+   * looking at: the extension resolves the active tab and reports the id
+   * back on attach, which is the normal way in — the caller has no tab ids
+   * to hand, only a browser with the user's session in it.
+   */
+  tabId?: number;
+  /** Relay endpoint. Defaults to DEFAULT_BRIDGE_URL. */
+  url?: string;
+  /** Relay token, from ~/.monoagent (the Go side writes it). */
+  token?: string;
+  /** Attach-handshake budget in ms. */
+  attachTimeoutMs?: number;
+  /**
+   * The byte pipe underneath. Defaults to a WebSocket to `url`; tests inject
+   * a scripted one so they can be the relay.
+   */
+  socket?: CdpTransport;
+}
+
+/** One bridge-level envelope, as the Go relay and the extension speak it. */
+interface BridgeEnvelope {
+  id: string;
+  type: 'cdp' | 'cdp_attach' | 'cdp_detach';
+  /** Omitted when the extension should resolve the active tab itself. */
+  tabId?: number;
+  params?: Record<string, unknown>;
+}
+
+interface BridgeReply {
+  id?: string;
+  type?: string;
+  success?: boolean;
+  data?: {
+    result?: unknown;
+    tabId?: number;
+    method?: string;
+    params?: unknown;
+    sessionId?: string;
+  };
+  error?: string;
+}
+
+/** A CDP frame on its way out of CdpClient. */
+interface OutboundCdp {
+  id: number;
+  method: string;
+  params?: Record<string, unknown>;
+  sessionId?: string;
+}
+
+export class BridgeTransport implements CdpTransport {
+  /** 0 until the extension resolves the active tab (see open()). */
+  private tabId: number;
+  private readonly socket: CdpTransport;
+  private readonly attachTimeoutMs: number;
+  private handlers: CdpTransportHandlers | null = null;
+  private nextEnvelopeId = 1;
+  private readonly pending = new Map<string, (reply: BridgeReply) => void>();
+  private closed = false;
+
+  constructor(opts: BridgeTransportOptions) {
+    this.tabId = opts.tabId ?? 0;
+    this.attachTimeoutMs = opts.attachTimeoutMs ?? DEFAULT_ATTACH_TIMEOUT_MS;
+    this.socket =
+      opts.socket ??
+      new WebSocketTransport(
+        opts.url ?? DEFAULT_BRIDGE_URL,
+        opts.token ? { [BRIDGE_TOKEN_HEADER]: opts.token } : undefined,
+      );
+  }
+
+  async open(handlers: CdpTransportHandlers): Promise<void> {
+    this.handlers = handlers;
+    await this.socket.open({
+      message: (data) => this.onBridgeMessage(data),
+      close: (err) => this.onGone(err ?? new Error('extension bridge closed')),
+      error: (err) => this.onGone(err),
+    });
+    const reply = await this.command('cdp_attach', undefined, this.attachTimeoutMs);
+    if (reply.success === false) {
+      this.socket.close();
+      const where = this.tabId ? `tab ${this.tabId}` : 'the active tab';
+      throw new Error(`bridge attach to ${where} failed: ${reply.error ?? 'unknown'}`);
+    }
+    // The extension answers with the tab it actually attached to, which is
+    // the only way to learn the id when we asked for "whatever is active".
+    if (typeof reply.data?.tabId === 'number') this.tabId = reply.data.tabId;
+    if (!this.tabId) {
+      this.socket.close();
+      throw new Error('bridge attach did not report a tab id');
+    }
+  }
+
+  /** The tab this transport is driving; valid once open() has resolved. */
+  get attachedTabId(): number {
+    return this.tabId;
+  }
+
+  /** The session id every instrument should use against this transport. */
+  get sessionId(): string {
+    return bridgeSessionId(this.tabId);
+  }
+
+  async send(frame: string): Promise<void> {
+    const cdp = JSON.parse(frame) as OutboundCdp;
+    if (this.answerLocally(cdp)) return;
+
+    const params: Record<string, unknown> = {
+      method: cdp.method,
+      params: cdp.params ?? {},
+    };
+    // A synthetic id means "the tab itself", which chrome.debugger addresses
+    // by its debuggee alone. Anything else is a real child session id and
+    // has to travel, or the command lands in the wrong frame.
+    if (cdp.sessionId !== undefined && !isBridgeSessionId(cdp.sessionId)) {
+      params.sessionId = cdp.sessionId;
+    }
+
+    const reply = await this.command('cdp', params);
+    if (reply.success === false) {
+      this.deliver({
+        id: cdp.id,
+        // -32000 is CDP's own "server error" code; the bridge has no richer
+        // one to offer, and the message is what a caller actually reads.
+        error: { code: -32000, message: reply.error ?? 'bridge command failed' },
+      });
+      return;
+    }
+    this.deliver({ id: cdp.id, result: reply.data?.result ?? {} });
+  }
+
+  close(): void {
+    if (this.closed) return;
+    this.closed = true;
+    // Best effort, and deliberately not awaited: leaving the debugger
+    // attached leaves Chrome's debugging banner on the user's tab. The
+    // extension's idle sweep would eventually detach anyway.
+    void this.command('cdp_detach').catch(() => {});
+    this.socket.close();
+    this.failPending(new Error('extension bridge closed'));
+  }
+
+  // --- internals -----------------------------------------------------------
+
+  /**
+   * Commands this transport answers itself. `Target.attachToTarget` against
+   * the tab is the one that matters: monobrowse's connect path asks for a
+   * session, and over the bridge there is nothing to ask — the debuggee is
+   * already the session. Any *other* target id is a genuine child target and
+   * goes to Chrome.
+   */
+  private answerLocally(cdp: OutboundCdp): boolean {
+    const targetId = cdp.params?.targetId;
+    if (cdp.method === 'Target.attachToTarget' && targetId === bridgeTargetId(this.tabId)) {
+      this.deliver({ id: cdp.id, result: { sessionId: bridgeSessionId(this.tabId) } });
+      return true;
+    }
+    if (
+      cdp.method === 'Target.detachFromTarget' &&
+      isBridgeSessionId(cdp.params?.sessionId as string | undefined)
+    ) {
+      this.deliver({ id: cdp.id, result: {} });
+      return true;
+    }
+    return false;
+  }
+
+  private command(
+    type: BridgeEnvelope['type'],
+    params?: Record<string, unknown>,
+    timeoutMs = 0,
+  ): Promise<BridgeReply> {
+    const id = `cdp-${this.nextEnvelopeId++}`;
+    const envelope: BridgeEnvelope = { id, type, params };
+    if (this.tabId) envelope.tabId = this.tabId;
+    return new Promise<BridgeReply>((resolve, reject) => {
+      let timer: ReturnType<typeof setTimeout> | undefined;
+      if (timeoutMs > 0) {
+        timer = setTimeout(() => {
+          this.pending.delete(id);
+          reject(new Error(`bridge ${type} timed out after ${timeoutMs}ms`));
+        }, timeoutMs);
+        timer.unref?.();
+      }
+      this.pending.set(id, (reply) => {
+        if (timer) clearTimeout(timer);
+        resolve(reply);
+      });
+      this.socket.send(JSON.stringify(envelope)).catch((err) => {
+        if (timer) clearTimeout(timer);
+        this.pending.delete(id);
+        reject(err);
+      });
+    });
+  }
+
+  private onBridgeMessage(data: string): void {
+    let msg: BridgeReply;
+    try {
+      msg = JSON.parse(data) as BridgeReply;
+    } catch {
+      return; // malformed frames are ignored, as on a raw CDP socket
+    }
+
+    if (msg.type === 'cdp_event') {
+      this.relayEvent(msg);
+      return;
+    }
+    if (msg.id !== undefined) {
+      const settle = this.pending.get(msg.id);
+      if (settle) {
+        this.pending.delete(msg.id);
+        settle(msg);
+      }
+    }
+  }
+
+  private relayEvent(msg: BridgeReply): void {
+    const ev = msg.data;
+    if (!ev?.method) return;
+    // One relay socket can carry several tabs; take only our own.
+    if (ev.tabId !== undefined && ev.tabId !== this.tabId) return;
+
+    // The debugger went away — the user hit Cancel on the banner, DevTools
+    // opened on the tab, or the tab closed. Nothing else will arrive, and a
+    // caller waiting on a command should hear that now rather than time out.
+    if (ev.method === 'Inspector.detached') {
+      const reason = (ev.params as { reason?: string } | undefined)?.reason ?? 'unknown';
+      this.onGone(new Error(`extension bridge detached from tab ${this.tabId}: ${reason}`));
+      return;
+    }
+
+    this.deliver({
+      method: ev.method,
+      params: (ev.params as Record<string, unknown>) ?? {},
+      // A real child session id wins; otherwise this is the tab's own
+      // session, which every instrument filters its events by.
+      sessionId: ev.sessionId ?? bridgeSessionId(this.tabId),
+    });
+  }
+
+  private deliver(frame: Record<string, unknown>): void {
+    this.handlers?.message(JSON.stringify(frame));
+  }
+
+  private onGone(err: Error): void {
+    this.failPending(err);
+    this.handlers?.close(err);
+  }
+
+  private failPending(err: Error): void {
+    for (const settle of this.pending.values()) {
+      settle({ success: false, error: err.message });
+    }
+    this.pending.clear();
+  }
+}
+
+/** What a bridge connection hands back: the same shape connectToTarget gives. */
+export interface BridgeConnection {
+  client: CdpClient;
+  sessionId: string;
+  tabId: number;
+  transport: BridgeTransport;
+}
+
+/**
+ * Connect a CdpClient to the user's real Chrome through the extension
+ * bridge, with the same domains enabled that a local session gets. This is
+ * the whole of the "point the instruments at the logged-in browser" story
+ * at the call site:
+ *
+ *     const { client, sessionId } = await connectBridge({ token });
+ *     const vitals = await collectVitals(client, sessionId);
+ *
+ * `enableDomains` is on by default for parity with connectToTarget. Turn it
+ * off for a caller that wants to choose its own domains (a bridge attach is
+ * visible to the user, so a lighter footprint is sometimes the point).
+ */
+export async function connectBridge(
+  opts: BridgeTransportOptions & { enableDomains?: boolean } = {},
+): Promise<BridgeConnection> {
+  const transport = new BridgeTransport(opts);
+  const client = new CdpClient();
+  await client.connectTransport(transport);
+  const sessionId = transport.sessionId;
+  if (opts.enableDomains !== false) {
+    await enableSessionDomains(client, sessionId);
+  }
+  return { client, sessionId, tabId: transport.attachedTabId, transport };
+}