@mochi.js/core 0.0.1 → 0.1.2

package/src/cdp/forbidden.ts

@@ -0,0 +1,102 @@
+/**
+ * Hard-coded list of CDP methods (and method+param combinations) that mochi
+ * MUST NEVER send to a Chromium target. These constraints are non-negotiable
+ * stealth invariants and the CDP transport enforces them with a synchronous
+ * assertion at `send()` time.
+ *
+ * @see PLAN.md §8.2 — "What we do NOT send"
+ */
+
+/**
+ * Thrown synchronously by the CDP transport when calling code attempts to send
+ * a method that is on the forbidden list. The error references the PLAN.md §8.2
+ * line for the specific constraint so reviewers can trace the rule back to the
+ * design doc.
+ */
+export class ForbiddenCdpMethodError extends Error {
+  /** The CDP method name that was rejected. */
+  readonly method: string;
+  /** Human-readable rationale citing PLAN.md §8.2. */
+  readonly reason: string;
+
+  constructor(method: string, reason: string) {
+    super(
+      `[mochi] forbidden CDP method "${method}" — ${reason} ` +
+        "(see PLAN.md §8.2). This is a stealth invariant; do not bypass.",
+    );
+    this.name = "ForbiddenCdpMethodError";
+    this.method = method;
+    this.reason = reason;
+  }
+}
+
+/**
+ * Methods that are forbidden unconditionally, regardless of params or target.
+ * @see PLAN.md §8.2
+ */
+const FORBIDDEN_METHODS: ReadonlyMap<string, string> = new Map([
+  [
+    "Runtime.enable",
+    "PLAN.md §8.2 line 1: 'Runtime.enable (any target). Detectable by error.stack lookup tricks.'",
+  ],
+  [
+    "Page.createIsolatedWorld",
+    "PLAN.md §8.2 line 2: 'Page.createIsolatedWorld. Also detectable.' Use main-world (worldName: '') injection only.",
+  ],
+]);
+
+/**
+ * Methods that are forbidden only when called with specific param shapes. The
+ * predicate returns the violation reason (string) when params are forbidden, or
+ * `null` when the call is acceptable.
+ * @see PLAN.md §8.2 line 3
+ */
+const PARAM_FORBIDDEN: ReadonlyMap<string, (params: unknown) => string | null> = new Map([
+  [
+    "Runtime.evaluate",
+    (params: unknown): string | null => {
+      if (
+        params !== null &&
+        typeof params === "object" &&
+        "includeCommandLineAPI" in params &&
+        (params as { includeCommandLineAPI?: unknown }).includeCommandLineAPI === true
+      ) {
+        return (
+          "PLAN.md §8.2 line 3: 'Runtime.evaluate with includeCommandLineAPI: true' " +
+          "(leaks $x, $_, etc. devtools globals to page script)."
+        );
+      }
+      return null;
+    },
+  ],
+]);
+
+/**
+ * Inspect a CDP request and throw `ForbiddenCdpMethodError` if it violates
+ * any §8.2 invariant. Called synchronously by the transport before serializing
+ * and before any I/O.
+ *
+ * Exported separately from the transport so tests and contract tests can
+ * exercise the invariant directly without spawning Chromium.
+ */
+export function assertNotForbidden(method: string, params?: unknown): void {
+  const flatReason = FORBIDDEN_METHODS.get(method);
+  if (flatReason !== undefined) {
+    throw new ForbiddenCdpMethodError(method, flatReason);
+  }
+  const paramCheck = PARAM_FORBIDDEN.get(method);
+  if (paramCheck !== undefined) {
+    const reason = paramCheck(params);
+    if (reason !== null) {
+      throw new ForbiddenCdpMethodError(method, reason);
+    }
+  }
+}
+
+/**
+ * The list of unconditionally-forbidden method names. Exported for tests and
+ * documentation tooling. Do not consume from product code.
+ *
+ * @internal
+ */
+export const FORBIDDEN_METHOD_NAMES: readonly string[] = Array.from(FORBIDDEN_METHODS.keys());

package/src/cdp/framer.ts

@@ -0,0 +1,79 @@
+/**
+ * Pipe-mode CDP framing.
+ *
+ * Chromium's `--remote-debugging-pipe` writes one CDP JSON message per record,
+ * each terminated by a single NUL byte (`\0`). The reader can deliver any
+ * chunk size — partial messages, multiple messages in one chunk, or a single
+ * message split across chunks. This framer buffers bytes until it sees a NUL,
+ * yields the bytes-before-the-NUL as one frame, and continues with the
+ * remainder.
+ *
+ * @see PLAN.md §8.1 (Transport)
+ */
+
+const NUL = 0x00;
+
+/**
+ * Stateful streaming framer for NUL-delimited CDP records. Push raw byte
+ * chunks; receive complete frames (without the delimiter) in order.
+ *
+ * The buffer is unbounded — Chromium will not produce frames that exceed the
+ * caller's available memory in normal operation; if it does, the higher-level
+ * router timeout will surface the issue.
+ */
+export class CdpFramer {
+  private buffer: Uint8Array = new Uint8Array(0);
+  private decoder = new TextDecoder("utf-8", { fatal: false });
+
+  /**
+   * Append a chunk of bytes to the internal buffer and return any complete
+   * frames that became available. Frames are returned as decoded UTF-8 strings
+   * (CDP guarantees JSON; the framer does not validate).
+   */
+  push(chunk: Uint8Array): string[] {
+    if (chunk.length === 0) {
+      return [];
+    }
+    // Concatenate. We could optimize with a ring buffer, but JSON-RPC over
+    // pipe never approaches the throughput where that matters.
+    const next = new Uint8Array(this.buffer.length + chunk.length);
+    next.set(this.buffer, 0);
+    next.set(chunk, this.buffer.length);
+    this.buffer = next;
+
+    const frames: string[] = [];
+    let start = 0;
+    for (let i = 0; i < this.buffer.length; i++) {
+      if (this.buffer[i] === NUL) {
+        const frameBytes = this.buffer.subarray(start, i);
+        if (frameBytes.length > 0) {
+          frames.push(this.decoder.decode(frameBytes));
+        }
+        start = i + 1;
+      }
+    }
+    if (start > 0) {
+      this.buffer = this.buffer.subarray(start);
+    }
+    return frames;
+  }
+
+  /**
+   * True iff the framer has no buffered bytes (i.e., no partial frame is in
+   * flight). Useful for graceful-shutdown assertions.
+   */
+  get isEmpty(): boolean {
+    return this.buffer.length === 0;
+  }
+}
+
+/**
+ * Encode a CDP JSON-RPC string to its on-the-wire bytes (UTF-8 + trailing NUL).
+ */
+export function encodeFrame(json: string): Uint8Array {
+  const utf8 = new TextEncoder().encode(json);
+  const out = new Uint8Array(utf8.length + 1);
+  out.set(utf8, 0);
+  out[utf8.length] = NUL;
+  return out;
+}

package/src/cdp/router.ts

@@ -0,0 +1,240 @@
+/**
+ * CDP message router.
+ *
+ * Sits between {@link CdpTransport} (raw frames) and the higher-level
+ * Session/Page code (typed `send` + event subscriptions). Owns:
+ *
+ *   - request-id correlation: every `send(method, params)` returns a Promise
+ *     that resolves with `result` or rejects with the CDP error.
+ *   - per-method event dispatch: `on(method, handler)` / `off(method, handler)`.
+ *   - per-call timeout: default 30s, override per request.
+ *   - shutdown: rejects all pending requests with a stable error.
+ *
+ * The router does NOT spawn the browser, parse flags, or know about pages.
+ * It's a pure JSON-RPC dispatcher with a §8.2-aware transport underneath.
+ *
+ * @see PLAN.md §8
+ */
+
+import { CdpTransport, type PipeReader, type PipeWriter } from "./transport";
+import type { CdpRequest, CdpResponse, CdpSessionId } from "./types";
+
+const DEFAULT_TIMEOUT_MS = 30_000;
+
+/** A handler invoked when a CDP event arrives. */
+export type CdpEventHandler = (params: unknown, sessionId?: CdpSessionId) => void;
+
+/** A subscription token returned by `on()`; call to unsubscribe. */
+export type Unsubscribe = () => void;
+
+/**
+ * Generic CDP error surfaced when a method returns `{error: ...}`.
+ */
+export class CdpRemoteError extends Error {
+  readonly method: string;
+  readonly code: number;
+  readonly data: unknown;
+  constructor(method: string, code: number, message: string, data?: unknown) {
+    super(`[mochi] CDP error from ${method} (${code}): ${message}`);
+    this.name = "CdpRemoteError";
+    this.method = method;
+    this.code = code;
+    this.data = data;
+  }
+}
+
+/**
+ * Thrown when the underlying child process exits unexpectedly while a CDP
+ * request is in flight, or when the pipe terminates abnormally.
+ */
+export class BrowserCrashedError extends Error {
+  override readonly cause?: Error;
+  constructor(message = "browser process exited or pipe closed unexpectedly", cause?: Error) {
+    super(`[mochi] ${message}`);
+    this.name = "BrowserCrashedError";
+    if (cause !== undefined) {
+      this.cause = cause;
+    }
+  }
+}
+
+/** Thrown when a CDP request exceeds its per-call timeout. */
+export class CdpTimeoutError extends Error {
+  readonly method: string;
+  readonly timeoutMs: number;
+  constructor(method: string, timeoutMs: number) {
+    super(`[mochi] CDP method ${method} timed out after ${timeoutMs}ms`);
+    this.name = "CdpTimeoutError";
+    this.method = method;
+    this.timeoutMs = timeoutMs;
+  }
+}
+
+interface PendingCall {
+  method: string;
+  resolve: (result: unknown) => void;
+  reject: (err: Error) => void;
+  timer: ReturnType<typeof setTimeout>;
+}
+
+/** Optional knobs for `MessageRouter.send()`. */
+export interface SendOptions {
+  /** Override the default 30s timeout. */
+  timeoutMs?: number;
+  /** Route to a sub-target session (worker, OOPIF). */
+  sessionId?: CdpSessionId;
+}
+
+/**
+ * Couples a transport with request/response correlation + event dispatch.
+ */
+export class MessageRouter {
+  readonly transport: CdpTransport;
+  private readonly pending = new Map<number, PendingCall>();
+  private readonly handlers = new Map<string, Set<CdpEventHandler>>();
+  private readonly defaultTimeoutMs: number;
+  private closeCause: Error | undefined;
+
+  constructor(reader: PipeReader, writer: PipeWriter, opts: { defaultTimeoutMs?: number } = {}) {
+    this.defaultTimeoutMs = opts.defaultTimeoutMs ?? DEFAULT_TIMEOUT_MS;
+    this.transport = new CdpTransport(reader, writer, {
+      onFrame: (json) => this.dispatch(json),
+      onClose: (reason) => this.onTransportClosed(reason),
+    });
+  }
+
+  /** Begin reading from the underlying transport. */
+  start(): void {
+    this.transport.start();
+  }
+
+  /**
+   * Send a CDP method and resolve with its `result` payload. Rejects with
+   * {@link CdpRemoteError}, {@link CdpTimeoutError}, or
+   * {@link BrowserCrashedError} on failure modes.
+   *
+   * Calls {@link assertNotForbidden} via the transport before any I/O — for
+   * forbidden methods this rejects synchronously (well, on next microtask)
+   * with {@link ForbiddenCdpMethodError}.
+   */
+  send<T = unknown>(method: string, params?: unknown, opts: SendOptions = {}): Promise<T> {
+    if (this.transport.isClosed) {
+      return Promise.reject(this.closeCause ?? new BrowserCrashedError("transport already closed"));
+    }
+    const id = this.transport.nextRequestId();
+    const timeoutMs = opts.timeoutMs ?? this.defaultTimeoutMs;
+    const request: CdpRequest = { id, method, params };
+    if (opts.sessionId !== undefined) {
+      request.sessionId = opts.sessionId;
+    }
+    return new Promise<T>((resolve, reject) => {
+      const timer = setTimeout(() => {
+        const entry = this.pending.get(id);
+        if (entry !== undefined) {
+          this.pending.delete(id);
+          entry.reject(new CdpTimeoutError(method, timeoutMs));
+        }
+      }, timeoutMs);
+      this.pending.set(id, {
+        method,
+        resolve: resolve as (v: unknown) => void,
+        reject,
+        timer,
+      });
+      try {
+        this.transport.send(request);
+      } catch (err) {
+        // Synchronous rejection (e.g. ForbiddenCdpMethodError, closed pipe).
+        clearTimeout(timer);
+        this.pending.delete(id);
+        reject(err instanceof Error ? err : new Error(String(err)));
+      }
+    });
+  }
+
+  /**
+   * Subscribe to CDP events of a given method name (e.g. `Page.frameNavigated`).
+   * Returns an unsubscribe function. Multiple handlers per method are supported.
+   */
+  on(method: string, handler: CdpEventHandler): Unsubscribe {
+    let set = this.handlers.get(method);
+    if (set === undefined) {
+      set = new Set();
+      this.handlers.set(method, set);
+    }
+    set.add(handler);
+    return () => {
+      const current = this.handlers.get(method);
+      if (current !== undefined) {
+        current.delete(handler);
+        if (current.size === 0) this.handlers.delete(method);
+      }
+    };
+  }
+
+  /** Subscribe once; auto-unsubscribes after the first event. */
+  once(method: string, handler: CdpEventHandler): Unsubscribe {
+    const wrapped: CdpEventHandler = (params, sessionId) => {
+      unsubscribe();
+      handler(params, sessionId);
+    };
+    const unsubscribe = this.on(method, wrapped);
+    return unsubscribe;
+  }
+
+  /** Tear down. Pending calls reject with `BrowserCrashedError`. Idempotent. */
+  async close(reason?: Error): Promise<void> {
+    if (this.transport.isClosed) return;
+    await this.transport.close(reason);
+  }
+
+  /** Decode an incoming JSON frame and dispatch to pending caller or event listeners. */
+  private dispatch(json: string): void {
+    let msg: CdpResponse;
+    try {
+      msg = JSON.parse(json) as CdpResponse;
+    } catch (err) {
+      console.error("[mochi] failed to parse CDP frame:", err, json.slice(0, 200));
+      return;
+    }
+    if (typeof msg.id === "number") {
+      const entry = this.pending.get(msg.id);
+      if (entry === undefined) {
+        // Stale response (e.g. timed-out call). Drop silently.
+        return;
+      }
+      this.pending.delete(msg.id);
+      clearTimeout(entry.timer);
+      if (msg.error !== undefined) {
+        entry.reject(
+          new CdpRemoteError(entry.method, msg.error.code, msg.error.message, msg.error.data),
+        );
+      } else {
+        entry.resolve(msg.result);
+      }
+      return;
+    }
+    if (typeof msg.method === "string") {
+      const set = this.handlers.get(msg.method);
+      if (set === undefined) return;
+      for (const handler of set) {
+        try {
+          handler(msg.params, msg.sessionId);
+        } catch (err) {
+          console.error(`[mochi] CDP event handler for ${msg.method} threw:`, err);
+        }
+      }
+    }
+  }
+
+  private onTransportClosed(reason?: Error): void {
+    const cause = reason ?? new BrowserCrashedError();
+    this.closeCause = cause;
+    for (const [, entry] of this.pending) {
+      clearTimeout(entry.timer);
+      entry.reject(cause);
+    }
+    this.pending.clear();
+    // Event handlers stay registered — a future re-attach is a v2 concern.
+  }
+}

package/src/cdp/transport.ts

@@ -0,0 +1,167 @@
+/**
+ * Pipe-mode CDP transport.
+ *
+ * Owns the read loop on FD 3 (browser → us) and the writer on FD 4 (us →
+ * browser). Decodes frames via {@link CdpFramer}, hands them to a callback
+ * supplied by the {@link MessageRouter}. Writes via {@link encodeFrame}.
+ *
+ * The transport itself is intentionally I/O-only — it does not understand
+ * request/response correlation, events, or sessions. The router does that.
+ * What the transport DOES do is enforce the §8.2 forbidden-method invariants
+ * via {@link assertNotForbidden} on every send, before any I/O.
+ *
+ * @see PLAN.md §8.1 / §8.2
+ */
+
+import { assertNotForbidden } from "./forbidden";
+import { CdpFramer, encodeFrame } from "./framer";
+import type { CdpRequest } from "./types";
+
+/** Minimal duplex pipe surface. Bun's `proc.stdio[3]` is a `ReadableStream` and
+ * `proc.stdio[4]` is a `FileSink`. We type against the actual shapes we use so
+ * the transport is unit-testable with mocks. */
+export interface PipeReader {
+  /**
+   * Returns a `ReadableStream<Uint8Array>` reader. The transport will pull
+   * chunks until the stream ends (browser exit) or `close()` is called.
+   */
+  getReader(): ReadableStreamDefaultReader<Uint8Array>;
+}
+
+export interface PipeWriter {
+  /** Write a chunk; returns void or a promise (Bun's FileSink returns number). */
+  write(chunk: Uint8Array): unknown;
+  /** Flush any buffered bytes. */
+  flush?(): unknown;
+  /** Close the underlying FD. */
+  end?(): unknown;
+}
+
+/** Callback the router supplies to receive complete JSON frames. */
+export type FrameHandler = (json: string) => void;
+
+/**
+ * Transport-level events surfaced to the router. The transport never throws
+ * asynchronously; it reports lifecycle changes through this channel.
+ */
+export interface TransportListener {
+  /** Called for every complete JSON frame from the browser. */
+  onFrame: FrameHandler;
+  /** Called once when the pipe closes (browser exit, manual close, or read error). */
+  onClose: (reason?: Error) => void;
+}
+
+/**
+ * The core transport. Construct with already-opened pipe handles plus a
+ * listener; call `start()` to begin the read loop, `send()` to write a CDP
+ * request, `close()` to release resources.
+ */
+export class CdpTransport {
+  private readonly framer = new CdpFramer();
+  private readonly reader: PipeReader;
+  private readonly writer: PipeWriter;
+  private readonly listener: TransportListener;
+  private nextId = 1;
+  private closed = false;
+  private readLoopPromise: Promise<void> | null = null;
+  private currentReader: ReadableStreamDefaultReader<Uint8Array> | null = null;
+
+  constructor(reader: PipeReader, writer: PipeWriter, listener: TransportListener) {
+    this.reader = reader;
+    this.writer = writer;
+    this.listener = listener;
+  }
+
+  /** True after `close()` has been called or the read loop has terminated. */
+  get isClosed(): boolean {
+    return this.closed;
+  }
+
+  /** Mint the next monotonic CDP request id. */
+  nextRequestId(): number {
+    return this.nextId++;
+  }
+
+  /** Start the async read loop. Idempotent. */
+  start(): void {
+    if (this.readLoopPromise !== null) return;
+    this.readLoopPromise = this.runReadLoop();
+  }
+
+  /**
+   * Synchronously enforce §8.2 invariants, then serialize and write the
+   * request to the browser pipe.
+   *
+   * Throws {@link ForbiddenCdpMethodError} *before* any I/O for any §8.2
+   * violation.
+   */
+  send(request: CdpRequest): void {
+    assertNotForbidden(request.method, request.params);
+    if (this.closed) {
+      throw new Error(`[mochi] cannot send CDP method ${request.method}: transport is closed`);
+    }
+    const json = JSON.stringify(request);
+    const bytes = encodeFrame(json);
+    this.writer.write(bytes);
+    if (typeof this.writer.flush === "function") {
+      // Bun's FileSink returns a promise we don't need to await; failures
+      // surface on the next write or via the close listener.
+      void this.writer.flush();
+    }
+  }
+
+  /**
+   * Tear down the transport. Idempotent. Cancels the read loop, closes the
+   * writer, and notifies the listener exactly once.
+   */
+  async close(reason?: Error): Promise<void> {
+    if (this.closed) return;
+    this.closed = true;
+    try {
+      if (this.currentReader !== null) {
+        await this.currentReader.cancel().catch(() => {});
+      }
+    } catch {
+      // ignore cancel failures
+    }
+    try {
+      if (typeof this.writer.end === "function") {
+        await this.writer.end();
+      }
+    } catch {
+      // ignore writer-close failures
+    }
+    this.listener.onClose(reason);
+  }
+
+  private async runReadLoop(): Promise<void> {
+    let closeReason: Error | undefined;
+    try {
+      const reader = this.reader.getReader();
+      this.currentReader = reader;
+      while (!this.closed) {
+        const { value, done } = await reader.read();
+        if (done) break;
+        if (value !== undefined && value.length > 0) {
+          const frames = this.framer.push(value);
+          for (const frame of frames) {
+            try {
+              this.listener.onFrame(frame);
+            } catch (err) {
+              // A handler bug should not kill the read loop.
+              // Surface to listener.onClose only on truly fatal conditions.
+              console.error("[mochi] CDP frame handler threw:", err);
+            }
+          }
+        }
+      }
+    } catch (err) {
+      closeReason = err instanceof Error ? err : new Error(String(err));
+    } finally {
+      if (!this.closed) {
+        this.closed = true;
+        this.listener.onClose(closeReason);
+      }
+    }
+  }
+}