Skip to content

A local-first multi-agent app development platform, built on PenguinHarness

12.0 KB
Raw Blame
/**
 * The shell link over a fake parentPort: request / reply by id, the per-request timeout, the
 * hello handshake (and a shell too old to answer it), event fan-out that no listener's failure
 * can escape from, and disposal taking the listener off the port — the hot-swap guarantee.
 */
import { describe, expect, it } from "vitest";
import type { DesktopBrowserCommandMessage } from "../../src/api/types.js";
import {
  ShellLink,
  ShellLinkError,
  parseBrowserEvent,
  parseBrowserReply,
  parseTab,
} from "../../src/builtin-browser/shell-link.js";
import { FakePort, FakeShell, tab } from "./fake-shell.js";

const lastCommand = (port: FakePort) => port.sent.at(-1) as DesktopBrowserCommandMessage;

describe("ShellLink requests", () => {
  it("sends a command frame and resolves with the reply to its id", async () => {
    const port = new FakePort();
    const link = new ShellLink(port);
    const pending = link.request({ op: "tabs" });
    const frame = lastCommand(port);
    expect(frame.type).toBe("desktop-browser-command");
    expect(frame.command).toEqual({ op: "tabs" });
    // A reply to someone else's id, and frames of other relays, are ignored.
    port.emit({ type: "desktop-browser-reply", id: "not-mine", ok: true, result: 1 });
    port.emit({ type: "desktop-updater-status", status: {} });
    port.emit({ type: "desktop-browser-reply", id: frame.id, ok: true, result: { tabs: [] } });
    await expect(pending).resolves.toEqual({ tabs: [] });
    link.dispose();
  });

  it("gives each request its own id, and each generation its own prefix", () => {
    const port = new FakePort();
    const a = new ShellLink(port);
    const b = new ShellLink(port);
    void a.request({ op: "tabs" }).catch(() => {});
    void a.request({ op: "tabs" }).catch(() => {});
    void b.request({ op: "tabs" }).catch(() => {});
    const ids = port.sent.map((m) => (m as DesktopBrowserCommandMessage).id);
    expect(new Set(ids).size).toBe(3);
    expect(ids[0]!.split("-")[0]).toBe(ids[1]!.split("-")[0]);
    expect(ids[0]!.split("-")[0]).not.toBe(ids[2]!.split("-")[0]);
    a.dispose();
    b.dispose();
  });

  it("rejects with the shell's error when it refuses", async () => {
    const port = new FakePort();
    const link = new ShellLink(port);
    const pending = link.request({ op: "cdp", tabId: 3, method: "Page.reload" });
    port.emit({
      type: "desktop-browser-reply",
      id: lastCommand(port).id,
      ok: false,
      error: "no_such_tab",
    });
    const err = await pending.catch((e: unknown) => e);
    expect(err).toBeInstanceOf(ShellLinkError);
    expect((err as ShellLinkError).kind).toBe("refused");
    expect((err as ShellLinkError).message).toBe("no_such_tab");
    link.dispose();
  });

  it("times out a request the shell never answers", async () => {
    const port = new FakePort();
    const link = new ShellLink(port);
    const err = await link.request({ op: "tabs" }, 30).catch((e: unknown) => e);
    expect((err as ShellLinkError).kind).toBe("timeout");
    // A reply after the deadline changes nothing.
    port.emit({ type: "desktop-browser-reply", id: lastCommand(port).id, ok: true, result: {} });
    link.dispose();
  });

  it("fails what is pending and leaves the port when disposed", async () => {
    const port = new FakePort();
    const link = new ShellLink(port);
    expect(port.listenerCount).toBe(1);
    const pending = link.request({ op: "tabs" });
    link.dispose();
    expect(port.listenerCount).toBe(0);
    expect(((await pending.catch((e: unknown) => e)) as ShellLinkError).kind).toBe("closed");
    expect(
      ((await link.request({ op: "tabs" }).catch((e: unknown) => e)) as ShellLinkError).kind,
    ).toBe("closed");
  });

  it("falls back to removeListener on a port without off", () => {
    const port = new FakePort();
    const bare = {
      on: port.on.bind(port),
      postMessage: port.postMessage.bind(port),
      removeListener: port.off.bind(port),
    };
    const link = new ShellLink(bare);
    expect(port.listenerCount).toBe(1);
    link.dispose();
    expect(port.listenerCount).toBe(0);
  });
});

describe("ShellLink handshake", () => {
  it("connects on hello and runs the connect listeners before resolving", async () => {
    const shell = new FakeShell();
    const link = new ShellLink(shell.port);
    const order: string[] = [];
    link.onConnect(async () => {
      order.push("refresh");
    });
    expect(link.connected).toBe(false);
    await expect(link.handshake()).resolves.toBe(true);
    expect(order).toEqual(["refresh"]);
    expect(link.connected).toBe(true);
    // Once connected, no further hello is sent.
    await link.handshake(true);
    expect(shell.commands.filter((c) => c.op === "hello")).toHaveLength(1);
    link.dispose();
  });

  it("shares one hello between concurrent callers", async () => {
    const shell = new FakeShell();
    const link = new ShellLink(shell.port);
    const results = await Promise.all([link.handshake(), link.handshake(), link.handshake(true)]);
    expect(results).toEqual([true, true, true]);
    expect(shell.commands.filter((c) => c.op === "hello")).toHaveLength(1);
    link.dispose();
  });

  it("treats a silent shell as unsupported, answers from that for a while, and retries when forced", async () => {
    const shell = new FakeShell();
    shell.speaksBrowser = false;
    let now = 1_000;
    const link = new ShellLink(shell.port, { helloTimeoutMs: 20, helloRetryMs: 10_000 }, () => now);
    await expect(link.handshake()).resolves.toBe(false);
    const hellos = () => shell.port.sent.length;
    const sent = hellos();
    // Within the retry window a plain handshake does not ask again…
    await expect(link.handshake()).resolves.toBe(false);
    expect(hellos()).toBe(sent);
    // …a forced one (the status route) does, and a shell that now answers connects.
    shell.speaksBrowser = true;
    await expect(link.handshake(true)).resolves.toBe(true);
    link.dispose();

    const later = new FakeShell();
    later.speaksBrowser = false;
    const again = new ShellLink(
      later.port,
      { helloTimeoutMs: 20, helloRetryMs: 10_000 },
      () => now,
    );
    await again.handshake();
    later.speaksBrowser = true;
    now += 10_001;
    await expect(again.handshake()).resolves.toBe(true);
    again.dispose();
  });
});

describe("ShellLink events", () => {
  it("fans validated events out to every listener, and drops malformed ones", () => {
    const shell = new FakeShell();
    const link = new ShellLink(shell.port);
    const a: unknown[] = [];
    const b: unknown[] = [];
    link.onEvent((e) => a.push(e));
    const unsubscribe = link.onEvent((e) => b.push(e));
    shell.show(tab(5));
    shell.port.emit({ type: "desktop-browser-event", event: { kind: "tab", tab: { id: "x" } } });
    shell.port.emit({ type: "desktop-browser-event", event: { kind: "mystery" } });
    unsubscribe();
    shell.close(5);
    expect(a).toEqual([
      { kind: "tab", tab: tab(5) },
      { kind: "tab-closed", tabId: 5 },
    ]);
    expect(b).toEqual([{ kind: "tab", tab: tab(5) }]);
    link.dispose();
  });

  it("logs a listener that throws and goes on to the next, never throwing out of the port", () => {
    const shell = new FakeShell();
    const logs: string[] = [];
    const link = new ShellLink(shell.port, {}, Date.now, (line) => logs.push(line));
    const after: unknown[] = [];
    link.onEvent(() => {
      throw new Error("boom");
    });
    link.onEvent((e) => after.push(e));
    expect(() => shell.show(tab(5))).not.toThrow();
    expect(after).toEqual([{ kind: "tab", tab: tab(5) }]);
    expect(logs).toEqual(["builtin browser: a 'tab' event from the shell failed: boom"]);
    // A frame no parser can read (a getter that throws) is dropped the same way.
    const hostile = {
      type: "desktop-browser-event",
      get event(): unknown {
        throw new Error("unreadable");
      },
    };
    expect(() => shell.port.emit(hostile)).not.toThrow();
    expect(logs.at(-1)).toBe("builtin browser: dropped a frame from the shell: unreadable");
    link.dispose();
  });
});

describe("wire parsing", () => {
  it("reads tabs strictly and keeps only a non-empty favicon", () => {
    expect(parseTab(tab(1, { favicon: "https://a.test/f.ico" }))).toEqual(
      tab(1, { favicon: "https://a.test/f.ico" }),
    );
    expect(parseTab({ ...tab(1), favicon: "" })).toEqual(tab(1));
    expect(parseTab({ ...tab(1), loading: "no" })).toBeNull();
    expect(parseTab({ ...tab(1), id: 1.5 })).toBeNull();
  });

  it("drops a favicon too large to ride every tab list: a data: icon past 4 KB, an address past 2 KB", () => {
    const data = (n: number) => `data:image/png;base64,${"A".repeat(n)}`;
    expect(parseTab(tab(1, { favicon: data(3_000) }))?.favicon).toBe(data(3_000));
    expect(parseTab(tab(1, { favicon: data(5_000) }))?.favicon).toBeUndefined();
    const long = `https://a.test/${"p".repeat(2_100)}.ico`;
    expect(parseTab(tab(1, { favicon: long }))?.favicon).toBeUndefined();
  });

  it("reads why a tab crashed, and nothing that is not a reason", () => {
    expect(parseTab(tab(1, { crashed: "oom" }))).toEqual(tab(1, { crashed: "oom" }));
    expect(parseTab({ ...tab(1), crashed: "Out of memory!" })).toEqual(tab(1));
    expect(parseTab({ ...tab(1), crashed: 3 })).toEqual(tab(1));
  });

  it("reads a crash and a measurement", () => {
    const event = (value: Record<string, unknown>) =>
      parseBrowserEvent({ type: "desktop-browser-event", event: value });
    expect(event({ kind: "tab-crashed", tabId: 3, reason: "oom", exitCode: 137 })).toEqual({
      kind: "tab-crashed",
      tabId: 3,
      reason: "oom",
      exitCode: 137,
    });
    // A reason the server does not know is still a crash.
    expect(event({ kind: "tab-crashed", tabId: 3, reason: 7 })).toEqual({
      kind: "tab-crashed",
      tabId: 3,
      reason: "crashed",
      exitCode: 0,
    });
    expect(event({ kind: "tab-crashed", tabId: "3", reason: "oom" })).toBeNull();
    const tabs = [{ tabId: 3, memoryKB: 204_800, cpuPercent: 1.5 }];
    expect(event({ kind: "metrics", tabs, totalKB: 204_800 })).toEqual({
      kind: "metrics",
      tabs,
      totalKB: 204_800,
    });
    expect(event({ kind: "metrics", tabs, totalKB: -1 })).toBeNull();
    expect(event({ kind: "metrics", tabs: [{ tabId: 3, memoryKB: 1 }], totalKB: 1 })).toBeNull();
    expect(event({ kind: "metrics", tabs: {}, totalKB: 1 })).toBeNull();
  });

  it("reads open requests, background included", () => {
    expect(
      parseBrowserEvent({
        type: "desktop-browser-event",
        event: { kind: "open-request", url: "https://a.test/", openerTabId: 2, background: true },
      }),
    ).toEqual({ kind: "open-request", url: "https://a.test/", openerTabId: 2, background: true });
    expect(
      parseBrowserEvent({
        type: "desktop-browser-event",
        event: { kind: "open-request", url: "https://a.test/", openerTabId: 2, background: "yes" },
      }),
    ).toEqual({ kind: "open-request", url: "https://a.test/", openerTabId: 2 });
  });

  it("reads a relayed CDP event, its params an object whatever arrived", () => {
    const event = (value: Record<string, unknown>) =>
      parseBrowserEvent({ type: "desktop-browser-event", event: { kind: "cdp-event", ...value } });
    const params = { type: "confirm", message: "Delete?" };
    expect(event({ tabId: 3, method: "Page.javascriptDialogOpening", params })).toEqual({
      kind: "cdp-event",
      tabId: 3,
      method: "Page.javascriptDialogOpening",
      params,
    });
    expect(event({ tabId: 3, method: "Page.frameNavigated", params: null })).toEqual({
      kind: "cdp-event",
      tabId: 3,
      method: "Page.frameNavigated",
      params: {},
    });
    expect(event({ tabId: "3", method: "Page.frameNavigated" })).toBeNull();
  });

  it("reads replies and ignores everything else", () => {
    expect(
      parseBrowserReply({ type: "desktop-browser-reply", id: "1", ok: true, result: 2 }),
    ).toEqual({
      type: "desktop-browser-reply",
      id: "1",
      ok: true,
      result: 2,
    });
    expect(parseBrowserReply({ type: "desktop-browser-reply", id: 1, ok: true })).toBeNull();
    expect(parseBrowserReply({ type: "desktop-tray-status" })).toBeNull();
  });
});