@omercnet/paseo-shared-browser 1.2.1 → 1.2.2-next.237.1

package/server/native-video-settings.test.ts

@@ -0,0 +1,245 @@
+/** Execute the shipped extension program so rate admission is not a duplicate policy test. */
+import { createContext, runInContext } from "node:vm";
+import { expect, it } from "vitest";
+import { NATIVE_VIDEO_EXTENSION_SOURCE } from "./native-video-extension-source";
+
+it("owns bitrate/FPS per encoder, actually rate-limits frames, and closes only the removed cohort", async () => {
+  const encoders: Encoder[] = [];
+  const constraints: unknown[] = [];
+  let deliver: (value: unknown) => void = () => {};
+  let context: ReturnType<typeof createContext>;
+  class Encoder {
+    static async isConfigSupported() {
+      return { supported: true };
+    }
+    configuration = { bitrate: 0, framerate: 0 };
+    calls = 0;
+    encoded: { timestamp: number; keyFrame: boolean }[] = [];
+    closed = false;
+    encodeQueueSize = 0;
+    constructor(readonly callbacks: { output(chunk: unknown, metadata: unknown): void }) {
+      encoders.push(this);
+    }
+    configure(value: typeof this.configuration) {
+      this.configuration = value;
+    }
+    close() {
+      this.closed = true;
+    }
+    reset() {}
+    encode(frame: { timestamp: number }, options: { keyFrame: boolean }) {
+      this.calls++;
+      this.encoded.push({ timestamp: frame.timestamp, keyFrame: options.keyFrame });
+      this.callbacks.output(
+        {
+          timestamp: frame.timestamp,
+          type: "key",
+          byteLength: 1,
+          copyTo: (bytes: Uint8Array) => bytes.fill(1),
+        },
+        {},
+      );
+    }
+  }
+  const reader = {
+    read: () =>
+      new Promise((resolve) => {
+        deliver = resolve;
+      }),
+    cancel: async () => {
+      deliver({ done: true });
+    },
+  };
+  context = createContext({
+    chrome: {
+      debugger: { getTargets: async () => [{ id: "exact", type: "page", tabId: 7 }] },
+      tabCapture: { getMediaStreamId: async () => "source" },
+    },
+    navigator: {
+      mediaDevices: {
+        getUserMedia: async (value: unknown) => {
+          constraints.push(value);
+          return {
+            getVideoTracks: () => [{ getSettings: () => ({ width: 1280, height: 800 }) }],
+            getTracks: () => [{ stop() {} }],
+          };
+        },
+      },
+    },
+    MediaStreamTrackProcessor: class {
+      readable = { getReader: () => reader };
+    },
+    VideoEncoder: Encoder,
+    nativeVideoPacket(json: string) {
+      const packet = JSON.parse(json);
+      runInContext(`acknowledge(${JSON.stringify(packet.streamId)},${packet.sequence})`, context);
+    },
+    performance: { now: () => 0 },
+    Uint8Array,
+    Map,
+    Set,
+    Object,
+    JSON,
+    Number,
+    Math,
+    btoa: (value: string) => Buffer.from(value, "binary").toString("base64"),
+  });
+  runInContext(NATIVE_VIDEO_EXTENSION_SOURCE, context);
+  await runInContext('startCapture("exact",1280,800,1)', context);
+  await runInContext('addEncoder("24000000:15","slow",24000000,15)', context);
+  await runInContext('addEncoder("5000000:30","medium",5000000,30)', context);
+  await runInContext('addEncoder("12000000:60","fast",12000000,60)', context);
+  expect(
+    encoders.map((value) => [value.configuration.bitrate, value.configuration.framerate]),
+  ).toEqual([
+    [24_000_000, 15],
+    [5_000_000, 30],
+    [12_000_000, 60],
+  ]);
+  expect(constraints[0]).toMatchObject({ video: { mandatory: { maxFrameRate: 60 } } });
+  await expect(
+    runInContext('addEncoder("2000000:30","fourth",2000000,30)', context),
+  ).rejects.toThrow("limit");
+  for (let i = 0; i < 60; i++) {
+    deliver({
+      value: {
+        timestamp: 1_000_000 + Math.ceil((i * 1_000_000) / 60),
+        displayWidth: 1280,
+        displayHeight: 800,
+        close() {},
+      },
+      done: false,
+    });
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  }
+  expect(encoders.map((value) => value.calls)).toEqual([15, 30, 60]);
+  // A forced recovery key bypasses FPS thinning, while backlog remains a hard gate.
+  runInContext('requestKeyFrame("24000000:15")', context);
+  encoders[0]!.encodeQueueSize = 2;
+  const push = async (timestamp: number) => {
+    deliver({
+      value: { timestamp, displayWidth: 1280, displayHeight: 800, close() {} },
+      done: false,
+    });
+    await new Promise<void>((resolve) => setImmediate(resolve));
+  };
+  await push(1_985_000);
+  expect(encoders.map((value) => value.calls)).toEqual([15, 30, 60]);
+  encoders[0]!.encodeQueueSize = 0;
+  await push(1_990_000);
+  expect(encoders.map((value) => value.calls)).toEqual([16, 30, 60]);
+  expect(encoders[0]!.encoded.at(-1)).toEqual({ timestamp: 1_990_000, keyFrame: true });
+  await push(1_991_000);
+  expect(encoders.map((value) => value.calls)).toEqual([16, 30, 60]);
+
+  runInContext('removeEncoder("5000000:30")', context);
+  expect(encoders.map((value) => value.closed)).toEqual([false, true, false]);
+  await runInContext('addEncoder("2000000:30","new",2000000,30)', context);
+  expect(encoders).toHaveLength(4);
+  await runInContext("stopCapture()", context);
+  expect(encoders.every((value) => value.closed)).toBe(true);
+});
+
+/** Codec probes deliberately remain pending, as a timed-out CDP evaluation does. */
+function allocationFixture() {
+  const support: ((value: { supported: boolean }) => void)[] = [];
+  const created: { closed: boolean; configure(value: unknown): void }[] = [];
+  let deliver: (result: unknown) => void = () => {};
+  const context = createContext({
+    chrome: {
+      debugger: { getTargets: async () => [{ id: "exact", type: "page", tabId: 7 }] },
+      tabCapture: { getMediaStreamId: async () => "source" },
+    },
+    navigator: {
+      mediaDevices: {
+        getUserMedia: async () => ({
+          getVideoTracks: () => [{ getSettings: () => ({}) }],
+          getTracks: () => [{ stop() {} }],
+        }),
+      },
+    },
+    MediaStreamTrackProcessor: class {
+      readable = {
+        getReader: () => ({
+          read: () =>
+            new Promise((resolve) => {
+              deliver = resolve;
+            }),
+          cancel: async () => {
+            deliver({ done: true });
+          },
+        }),
+      };
+    },
+    VideoEncoder: class {
+      static isConfigSupported() {
+        return new Promise((resolve) => support.push(resolve));
+      }
+      closed = false;
+      constructor() {
+        created.push(this);
+      }
+      configure(_value: unknown) {}
+      close() {
+        this.closed = true;
+      }
+      reset() {}
+    },
+    nativeVideoPacket() {},
+    performance: { now: () => 0 },
+    btoa() {},
+  });
+  runInContext(NATIVE_VIDEO_EXTENSION_SOURCE, context);
+  const evaluate = (expression: string) => runInContext(expression, context);
+  return { support, created, evaluate };
+}
+it("helper reserves its three pending slots before asynchronous codec probes", async () => {
+  const f = allocationFixture();
+  await f.evaluate('startCapture("exact",1280,800,1)');
+  const pending = [2_000_000, 5_000_000, 12_000_000].map((value) =>
+    f.evaluate(`addEncoder("${value}:30","${value}",${value},30)`),
+  );
+  await expect(f.evaluate('addEncoder("24000000:30","fourth",24000000,30)')).rejects.toThrow(
+    "limit",
+  );
+  expect(f.support).toHaveLength(3);
+  for (const resolve of f.support) resolve({ supported: true });
+  await Promise.all(pending);
+  expect(f.created).toHaveLength(3);
+  await f.evaluate("stopCapture()");
+});
+it("same-key allocation cannot replace or orphan an encoder with a different stream identity", async () => {
+  const f = allocationFixture();
+  await f.evaluate('startCapture("exact",1280,800,1)');
+  const first = f.evaluate('addEncoder("12000000:30","original",12000000,30)');
+  const same = f.evaluate('addEncoder("12000000:30","original",12000000,30)');
+  await expect(f.evaluate('addEncoder("12000000:30","replacement",12000000,30)')).rejects.toThrow(
+    "identity",
+  );
+  expect(f.support).toHaveLength(1);
+  f.support[0]!({ supported: true });
+  await Promise.all([first, same]);
+  expect(f.created).toHaveLength(1);
+  await expect(f.evaluate('addEncoder("12000000:30","replacement",12000000,30)')).rejects.toThrow(
+    "identity",
+  );
+  await f.evaluate("stopCapture()");
+});
+it("cancelled pending allocation cannot publish after a replacement or capture restart", async () => {
+  const f = allocationFixture();
+  await f.evaluate('startCapture("exact",1280,800,1)');
+  const old = f.evaluate('addEncoder("12000000:30","old",12000000,30)');
+  const oldRejected = expect(old).rejects.toThrow("changed");
+  f.evaluate('removeEncoder("12000000:30")');
+  const newOne = f.evaluate('addEncoder("12000000:30","new",12000000,30)');
+  f.support[0]!({ supported: true });
+  await oldRejected;
+  expect(f.created).toHaveLength(0);
+  await f.evaluate("stopCapture()");
+  await f.evaluate('startCapture("exact",1280,800,2)');
+  const newRejected = expect(newOne).rejects.toThrow("changed");
+  f.support[1]!({ supported: true });
+  await newRejected;
+  expect(f.created).toHaveLength(0);
+  await f.evaluate("stopCapture()");
+});

package/server/navigation-budget.ts

@@ -0,0 +1,8 @@
+/** Ready, attached navigation budget inside the host's 30s RPC deadline.
+ * Native ACK and matched main-frame commit are distinct from document loading.
+ * Metadata gets one bounded post-commit phase; history needs a preflight.
+ * Reattachment and held-input cleanup remain separate possible failure costs.
+ */
+export const NAVIGATION_ACK_TIMEOUT_MS = 10_000;
+export const NAVIGATION_COMMIT_TIMEOUT_MS = 3_000;
+export const NAVIGATION_METADATA_TIMEOUT_MS = 3_000;

package/server/navigation-commit.ts

@@ -0,0 +1,125 @@
+/** Observes one native navigation's main-frame commit, never DOM readiness.
+ * Events can precede the command ACK, so bounded receipts are buffered before
+ * dispatch. A missing or detached post-ACK commit is uncertain, never replayed.
+ */
+import { type CdpSession, CdpUnknownOutcomeError } from "./cdp";
+
+export interface NavigationCommitReceipt {
+  frameId: string;
+  loaderId?: string;
+  previousLoaderId?: string;
+  /** Required for same-document commits and history entry selection. */
+  url?: string;
+  download?: boolean;
+}
+
+type Commit = { frameId: string; loaderId?: string; url: string; sameDocument: boolean };
+
+function normalizedUrl(url: string): string {
+  try {
+    return new URL(url).href;
+  } catch {
+    return url;
+  }
+}
+
+/** Dispatch once, then await the matching root commit within timeoutMs.
+ * assertCurrent binds the original native attachment before and after waiting.
+ * Download ACKs intentionally leave the current document unchanged.
+ */
+export async function waitForNavigationCommit(
+  page: CdpSession,
+  dispatch: () => Promise<NavigationCommitReceipt>,
+  assertCurrent: () => void,
+  timeoutMs: number,
+): Promise<void> {
+  const commits: Commit[] = [];
+  let attachmentLost = false;
+  let notify: (() => void) | undefined;
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const append = (commit: Commit): void => {
+    if (commits.length === 64) commits.shift();
+    commits.push(commit);
+    notify?.();
+  };
+  const frameNavigated = (event: {
+    frame: { id: string; parentId?: string; loaderId?: string; url: string; urlFragment?: string };
+  }): void => {
+    if (event.frame.parentId) return;
+    append({
+      frameId: event.frame.id,
+      ...(event.frame.loaderId ? { loaderId: event.frame.loaderId } : {}),
+      // CDP Frame.url omits the fragment; history entries keep the full URL.
+      url: event.frame.url + (event.frame.urlFragment ?? ""),
+      sameDocument: false,
+    });
+  };
+  const withinDocument = (event: { frameId: string; url: string }): void => {
+    append({ frameId: event.frameId, url: event.url, sameDocument: true });
+  };
+  const detached = (): void => {
+    attachmentLost = true;
+    notify?.();
+  };
+  page.on("Page.frameNavigated", frameNavigated);
+  page.on("Page.navigatedWithinDocument", withinDocument);
+  page.on("Inspector.detached", detached);
+  page.connection.on("disconnect", detached);
+
+  try {
+    assertCurrent();
+    const receipt = await dispatch();
+    const unknown = (): CdpUnknownOutcomeError =>
+      new CdpUnknownOutcomeError(
+        "Navigation was acknowledged but its matching document commit was not observed; outcome is unknown",
+      );
+    const checkCurrent = (): void => {
+      if (attachmentLost) throw unknown();
+      try {
+        assertCurrent();
+      } catch {
+        throw unknown();
+      }
+    };
+    checkCurrent();
+    if (receipt.download) return;
+    if (!receipt.frameId) throw unknown();
+    const matches = (commit: Commit): boolean => {
+      if (commit.frameId !== receipt.frameId) return false;
+      if (receipt.loaderId) return !commit.sameDocument && commit.loaderId === receipt.loaderId;
+      if (commit.sameDocument) {
+        return (
+          receipt.url !== undefined && normalizedUrl(commit.url) === normalizedUrl(receipt.url)
+        );
+      }
+      // History/reload ACK has no loader. Require a fresh main loader, and the
+      // selected history URL when known, rather than accepting an old event.
+      return (
+        receipt.previousLoaderId !== undefined &&
+        commit.loaderId !== undefined &&
+        commit.loaderId !== receipt.previousLoaderId &&
+        (receipt.url === undefined || normalizedUrl(commit.url) === normalizedUrl(receipt.url))
+      );
+    };
+    let expired = false;
+    timer = setTimeout(() => {
+      expired = true;
+      notify?.();
+    }, timeoutMs);
+    for (;;) {
+      checkCurrent();
+      if (commits.some(matches)) return;
+      if (expired) throw unknown();
+      const waiter = Promise.withResolvers<void>();
+      notify = waiter.resolve;
+      await waiter.promise;
+      notify = undefined;
+    }
+  } finally {
+    if (timer) clearTimeout(timer);
+    page.off("Page.frameNavigated", frameNavigated);
+    page.off("Page.navigatedWithinDocument", withinDocument);
+    page.off("Inspector.detached", detached);
+    page.connection.off("disconnect", detached);
+  }
+}

package/server/navigation-policy.test.ts

@@ -0,0 +1,153 @@
+/** Navigation metadata budget and single-publication behavior through the real session policy. */
+import { afterEach, expect, it, vi } from "vitest";
+import { type BrowserRuntimeClient, SessionManager } from "./browser-policy";
+import { CdpUnknownOutcomeError } from "./cdp";
+import { NAVIGATION_METADATA_TIMEOUT_MS } from "./navigation-budget";
+
+async function fixture() {
+  let counter = 0;
+  let url = "https://before.invalid/";
+  let inputGeneration = "0:0";
+  let metadataFails = false;
+  let dispatchFails = false;
+  const calls: { operation: string; input: unknown }[] = [];
+  const client: BrowserRuntimeClient = {
+    connect: async () => ({ epoch: 1 }),
+    ensureWorkspace: async (workspaceId) => ({
+      workspaceId,
+      runtimeId: "r".repeat(32),
+      createdAt: 1,
+    }),
+    requestWorkspace: async (_workspaceId, operation, input) => {
+      calls.push({ operation, input });
+      if (operation === "identity") return { userAgent: "Fixture" };
+      if (operation === "state") {
+        if (metadataFails) throw new Error("Browser metadata unavailable");
+        return {
+          url,
+          title: "Still loading",
+          canGoBack: true,
+          canGoForward: true,
+          inputGeneration,
+        };
+      }
+      if (["navigate", "back", "forward", "reload"].includes(operation)) {
+        if (dispatchFails) throw new CdpUnknownOutcomeError("Navigation acknowledgement unknown");
+        // A redirect is observed from the native state, never invented from the request URL.
+        url = "https://redirected.invalid/";
+        inputGeneration = "0:1";
+      }
+      return null;
+    },
+    archiveWorkspace: async () => {},
+    closeWorkspace: async () => {},
+    disconnect() {},
+  };
+  const manager = new SessionManager({
+    client,
+    validateWorkspace: async () => true,
+    issueToken: () => String(++counter).padStart(32, "0"),
+  });
+  await manager.connect();
+  const attached = await manager.attach("owned", "Viewer");
+  const control = await manager.acquireControl(attached.viewerToken);
+  const context = {
+    viewerToken: attached.viewerToken,
+    controlToken: control.controlToken,
+    expected: {
+      sessionId: control.state.sessionId,
+      navigationGeneration: control.state.navigationGeneration,
+      viewportGeneration: control.state.viewportGeneration,
+      runtimeId: control.state.runtimeId!,
+      bridgeEpoch: control.state.bridgeEpoch!,
+    },
+  };
+  calls.length = 0;
+  return {
+    manager,
+    context,
+    calls,
+    failMetadata: () => {
+      metadataFails = true;
+    },
+    failDispatch: () => {
+      dispatchFails = true;
+    },
+  };
+}
+
+afterEach(() => vi.restoreAllMocks());
+
+it.each(["goto", "back", "forward", "reload"] as const)(
+  "%s performs one bounded post-observation, with one preflight only for history actions",
+  async (kind) => {
+    const f = await fixture();
+    try {
+      const action = kind === "goto" ? { kind, url: "https://requested.invalid/" } : { kind };
+      const result = await f.manager.navigate({ ...f.context, action });
+      expect(result.state.url).toBe("https://redirected.invalid/");
+      expect(result.state.title).toBe("Still loading");
+      const metadata = f.calls.filter((call) => call.operation === "state");
+      expect(metadata).toHaveLength(kind === "back" || kind === "forward" ? 2 : 1);
+      expect(
+        metadata.every(
+          (call) =>
+            JSON.stringify(call.input) ===
+            JSON.stringify({ timeoutMs: NAVIGATION_METADATA_TIMEOUT_MS }),
+        ),
+      ).toBe(true);
+      expect(
+        f.calls.filter((call) =>
+          ["navigate", "back", "forward", "reload"].includes(call.operation),
+        ),
+      ).toHaveLength(1);
+    } finally {
+      await f.manager.disconnect();
+    }
+  },
+);
+
+it("acknowledged navigation with unavailable metadata returns explicit error, never cached-ready", async () => {
+  const f = await fixture();
+  try {
+    f.failMetadata();
+    const result = await f.manager.navigate({
+      ...f.context,
+      action: { kind: "goto", url: "https://requested.invalid/" },
+    });
+    expect(result.state.status).toBe("error");
+    expect(result.state.error).toBe("Browser metadata unavailable");
+    expect(f.calls.map((call) => call.operation)).toEqual(["navigate", "state"]);
+  } finally {
+    await f.manager.disconnect();
+  }
+});
+
+it("failed history preflight blocks publication", async () => {
+  const f = await fixture();
+  try {
+    f.failMetadata();
+    await expect(f.manager.navigate({ ...f.context, action: { kind: "back" } })).rejects.toThrow(
+      "metadata unavailable",
+    );
+    expect(f.calls.map((call) => call.operation)).toEqual(["state"]);
+  } finally {
+    await f.manager.disconnect();
+  }
+});
+
+it("uncertain native publication is not retried or relabelled as a loaded document", async () => {
+  const f = await fixture();
+  try {
+    f.failDispatch();
+    await expect(
+      f.manager.navigate({
+        ...f.context,
+        action: { kind: "goto", url: "https://requested.invalid/" },
+      }),
+    ).rejects.toBeInstanceOf(CdpUnknownOutcomeError);
+    expect(f.calls.map((call) => call.operation)).toEqual(["navigate"]);
+  } finally {
+    await f.manager.disconnect();
+  }
+});

package/server/process-identity.ts

@@ -0,0 +1,58 @@
+import { readFile } from "node:fs/promises";
+
+/** Proof that a PID is a process launched by this runtime and has not been replaced since. */
+export interface ProcessIdentity {
+  pid: number;
+  /** Kernel start time in clock ticks; a recycled PID has a different value. */
+  startTicks: string;
+}
+
+/** Environment variable carrying the per-runtime ownership nonce through the launch chain. */
+export const RUNTIME_OWNER_VARIABLE = "PASEO_SHARED_BROWSER_RUNTIME_OWNER";
+
+/** Positive outcomes are distinct from "could not tell": only `absent` proves disappearance. */
+export type ProcessProbe =
+  | { status: "owned"; identity: ProcessIdentity }
+  /** The process exists and was read, but is not this runtime's (no nonce): proven replacement. */
+  | { status: "foreign" }
+  /** The kernel reports no such process (ENOENT/ESRCH): positive exit. */
+  | { status: "absent" }
+  /** Unreadable, unsupported platform or malformed data: nothing is proven either way. */
+  | { status: "unknown" };
+
+/**
+ * Probes `pid` for this runtime's private nonce, i.e. a descendant of its own launch (JS
+ * launcher, native CLI, daemon) rather than merely a process running some executable.
+ */
+export async function probeProcess(pid: number, nonce: string): Promise<ProcessProbe> {
+  if (process.platform !== "linux" || !Number.isSafeInteger(pid) || pid <= 0)
+    return { status: "unknown" };
+  try {
+    const [stat, environment] = await Promise.all([
+      readFile(`/proc/${pid}/stat`, "utf8"),
+      readFile(`/proc/${pid}/environ`, "utf8"),
+    ]);
+    if (!environment.split("\0").includes(`${RUNTIME_OWNER_VARIABLE}=${nonce}`))
+      return { status: "foreign" };
+    // Fields after the parenthesised command name; starttime is field 22 overall.
+    const startTicks = stat.slice(stat.lastIndexOf(")") + 2).split(" ")[19];
+    return startTicks && /^\d+$/.test(startTicks)
+      ? { status: "owned", identity: { pid, startTicks } }
+      : { status: "unknown" };
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code === "ENOENT" ||
+      (error as NodeJS.ErrnoException).code === "ESRCH"
+      ? { status: "absent" }
+      : { status: "unknown" };
+  }
+}
+
+/** Signal-0 probe: only ESRCH proves the process is gone; EPERM means it is still alive. */
+export function processExists(pid: number): boolean {
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch (error) {
+    return (error as NodeJS.ErrnoException).code !== "ESRCH";
+  }
+}