Skip to content

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

13.6 KB
Raw Blame
/**
 * The built-in browser's link to the desktop shell: request/reply and events over the
 * utilityProcess port (`process.parentPort`), beside the updater and tray relay the HMR layer
 * wires on the same port (services/desktop-update-port.ts, left untouched).
 *
 * A link belongs to one platform generation. It adds its own listener to the port and takes
 * it off again on dispose, so a hot swap never leaves a dead App's listener answering frames.
 * Request ids carry a per-link prefix for the same reason: a late reply to the previous
 * generation's request can never be mistaken for one of this generation's.
 *
 * The handshake is `hello`. A shell older than the built-in browser ignores the frame, so
 * silence past the hello timeout means "this shell cannot host the browser"; the handshake is
 * tried again later rather than trusted forever, since the one pairing that produces it — a
 * platform pushed onto an older installation — cannot change without a new shell anyway.
 *
 * Nothing the shell sends can take the server down: a frame is validated before anything reads
 * it, and a listener that throws on one is logged and skipped, since an exception escaping a
 * port listener is an uncaught exception, which ends the server process (index.ts).
 */
import { randomUUID } from "node:crypto";
import type {
  BuiltinBrowserTab,
  BuiltinBrowserTabMetrics,
  DesktopBrowserCommand,
  DesktopBrowserCommandMessage,
  DesktopBrowserEvent,
  DesktopBrowserReplyMessage,
} from "../api/types.js";
import type { ShellPort } from "../services/desktop-update-port.js";

type MessageListener = (e: { data: unknown }) => void;

/** The port as this link uses it: Electron's ParentPort is an EventEmitter, so a listener can come off again. */
export interface BrowserShellPort extends ShellPort {
  off?(event: "message", listener: MessageListener): void;
  removeListener?(event: "message", listener: MessageListener): void;
}

/**
 * Why a request did not produce a result: the shell refused it (`message` is the shell's own
 * error — a CDP error text, or `no_such_tab`), it did not answer in time, or the link was
 * disposed under it.
 */
export class ShellLinkError extends Error {
  constructor(
    readonly kind: "refused" | "timeout" | "closed",
    message: string,
  ) {
    super(message);
    this.name = "ShellLinkError";
  }
}

export interface ShellLinkTiming {
  /** How long `hello` may take before the shell counts as one that cannot host the browser. */
  helloTimeoutMs: number;
  /** After a failed hello, how long a non-forced handshake answers from that failure. */
  helloRetryMs: number;
  /** Any other request that names no timeout of its own. */
  defaultTimeoutMs: number;
}

export const DEFAULT_SHELL_LINK_TIMING: ShellLinkTiming = {
  helloTimeoutMs: 3_000,
  helloRetryMs: 10_000,
  defaultTimeoutMs: 30_000,
};

const isRecord = (value: unknown): value is Record<string, unknown> =>
  typeof value === "object" && value !== null && !Array.isArray(value);

/**
 * The longest favicons a tab keeps: a `data:` icon rides every tab event and every tab list the
 * windows hear, so one a page inlines at any size (or swaps on a timer) is dropped past a
 * 32-pixel icon's worth, as the shell does; an address longer than this is not one worth sending.
 */
export const MAX_DATA_FAVICON_CHARS = 4 * 1024;
export const MAX_FAVICON_URL_CHARS = 2 * 1024;

function faviconOf(value: unknown): string | undefined {
  if (typeof value !== "string" || value === "") return undefined;
  const limit = /^data:/i.test(value) ? MAX_DATA_FAVICON_CHARS : MAX_FAVICON_URL_CHARS;
  return value.length <= limit ? value : undefined;
}

/** Why a renderer went away, as Electron names it: a short lowercase word. */
function crashReasonOf(value: unknown): string | undefined {
  return typeof value === "string" && /^[a-z][a-z-]{0,39}$/.test(value) ? value : undefined;
}

/** A tab as the shell reports it; null for anything that does not have the shape. */
export function parseTab(value: unknown): BuiltinBrowserTab | null {
  if (!isRecord(value)) return null;
  const { id, url, title, loading, canGoBack, canGoForward } = value;
  if (typeof id !== "number" || !Number.isSafeInteger(id)) return null;
  if (typeof url !== "string" || typeof title !== "string") return null;
  if (typeof loading !== "boolean") return null;
  if (typeof canGoBack !== "boolean" || typeof canGoForward !== "boolean") return null;
  const favicon = faviconOf(value.favicon);
  const crashed = crashReasonOf(value.crashed);
  return {
    id,
    url,
    title,
    loading,
    canGoBack,
    canGoForward,
    ...(favicon !== undefined ? { favicon } : {}),
    ...(crashed !== undefined ? { crashed } : {}),
  };
}

/** The most tabs one measurement may name. */
const MAX_MEASURED_TABS = 1_000;

const isAmount = (value: unknown): value is number =>
  typeof value === "number" && Number.isFinite(value) && value >= 0;

/** A `metrics` event's tab list; null when any entry is not a tab's measurement. */
function parseTabMetrics(value: unknown): BuiltinBrowserTabMetrics[] | null {
  if (!Array.isArray(value) || value.length > MAX_MEASURED_TABS) return null;
  const tabs: BuiltinBrowserTabMetrics[] = [];
  for (const entry of value as unknown[]) {
    if (!isRecord(entry)) return null;
    const { tabId, memoryKB, cpuPercent } = entry;
    if (typeof tabId !== "number" || !Number.isSafeInteger(tabId)) return null;
    if (!isAmount(memoryKB) || !isAmount(cpuPercent)) return null;
    tabs.push({ tabId, memoryKB, cpuPercent });
  }
  return tabs;
}

/** One shell push, validated; null when the frame is not a browser event or is malformed. */
export function parseBrowserEvent(data: unknown): DesktopBrowserEvent | null {
  if (!isRecord(data) || data.type !== "desktop-browser-event" || !isRecord(data.event)) {
    return null;
  }
  const event = data.event;
  switch (event.kind) {
    case "tab": {
      const tab = parseTab(event.tab);
      return tab === null ? null : { kind: "tab", tab };
    }
    case "tab-closed":
      return typeof event.tabId === "number" ? { kind: "tab-closed", tabId: event.tabId } : null;
    case "open-request":
      if (typeof event.url !== "string" || typeof event.openerTabId !== "number") return null;
      return {
        kind: "open-request",
        url: event.url,
        openerTabId: event.openerTabId,
        ...(event.background === true ? { background: true } : {}),
      };
    case "cdp-event":
      if (typeof event.tabId !== "number" || typeof event.method !== "string") return null;
      return {
        kind: "cdp-event",
        tabId: event.tabId,
        method: event.method,
        params: isRecord(event.params) ? event.params : {},
      };
    case "tab-crashed": {
      const reason = crashReasonOf(event.reason) ?? "crashed";
      if (typeof event.tabId !== "number" || !Number.isSafeInteger(event.tabId)) return null;
      const exitCode = typeof event.exitCode === "number" ? event.exitCode : 0;
      return { kind: "tab-crashed", tabId: event.tabId, reason, exitCode };
    }
    case "metrics": {
      const tabs = parseTabMetrics(event.tabs);
      if (tabs === null || !isAmount(event.totalKB)) return null;
      return { kind: "metrics", tabs, totalKB: event.totalKB };
    }
    default:
      return null;
  }
}

/** One shell reply, validated; null when the frame is not one. */
export function parseBrowserReply(data: unknown): DesktopBrowserReplyMessage | null {
  if (!isRecord(data) || data.type !== "desktop-browser-reply") return null;
  if (typeof data.id !== "string" || typeof data.ok !== "boolean") return null;
  return {
    type: "desktop-browser-reply",
    id: data.id,
    ok: data.ok,
    ...("result" in data ? { result: data.result } : {}),
    ...(typeof data.error === "string" ? { error: data.error } : {}),
  };
}

interface Pending {
  resolve(result: unknown): void;
  reject(err: ShellLinkError): void;
  timer: NodeJS.Timeout;
}

export class ShellLink {
  private readonly timing: ShellLinkTiming;
  private readonly pending = new Map<string, Pending>();
  private readonly eventListeners = new Set<(event: DesktopBrowserEvent) => void>();
  private readonly connectListeners = new Set<() => Promise<void> | void>();
  private readonly prefix = randomUUID().slice(0, 8);
  private seq = 0;
  private state: "unknown" | "connected" | "unsupported" = "unknown";
  private failedAt = 0;
  private handshaking: Promise<boolean> | null = null;
  private disposed = false;
  private readonly onMessage: MessageListener = (e) => this.receive(e.data);

  constructor(
    private readonly port: BrowserShellPort,
    timing: Partial<ShellLinkTiming> = {},
    private readonly now: () => number = Date.now,
    private readonly log: (line: string) => void = () => {},
  ) {
    this.timing = { ...DEFAULT_SHELL_LINK_TIMING, ...timing };
    port.on("message", this.onMessage);
  }

  /** Whether the shell has answered `hello`. */
  get connected(): boolean {
    return this.state === "connected";
  }

  /** Sends one command and resolves with the shell's result. */
  request(
    command: DesktopBrowserCommand,
    timeoutMs = this.timing.defaultTimeoutMs,
  ): Promise<unknown> {
    if (this.disposed) return Promise.reject(new ShellLinkError("closed", "The link is closed."));
    this.seq += 1;
    const id = `${this.prefix}-${this.seq}`;
    return new Promise<unknown>((resolve, reject) => {
      const timer = setTimeout(() => {
        this.pending.delete(id);
        reject(
          new ShellLinkError(
            "timeout",
            `The desktop shell did not answer '${command.op}' within ${Math.round(timeoutMs / 1000)}s.`,
          ),
        );
      }, timeoutMs);
      this.pending.set(id, { resolve, reject, timer });
      try {
        this.port.postMessage({
          type: "desktop-browser-command",
          id,
          command,
        } satisfies DesktopBrowserCommandMessage);
      } catch (err) {
        clearTimeout(timer);
        this.pending.delete(id);
        reject(new ShellLinkError("closed", err instanceof Error ? err.message : String(err)));
      }
    });
  }

  /**
   * The handshake, one at a time: true once the shell has answered `hello`. After a failure a
   * call answers from it for `helloRetryMs`, unless `force` (the status route) asks again now.
   * Connect listeners run before the first successful handshake resolves, so a caller that
   * awaited it sees their effect (the tab list refreshed).
   */
  handshake(force = false): Promise<boolean> {
    if (this.state === "connected") return Promise.resolve(true);
    if (this.handshaking !== null) return this.handshaking;
    if (
      this.state === "unsupported" &&
      !force &&
      this.now() - this.failedAt < this.timing.helloRetryMs
    ) {
      return Promise.resolve(false);
    }
    this.handshaking = (async () => {
      try {
        await this.request({ op: "hello" }, this.timing.helloTimeoutMs);
      } catch {
        if (!this.disposed) {
          this.state = "unsupported";
          this.failedAt = this.now();
        }
        return false;
      }
      this.state = "connected";
      for (const listener of this.connectListeners) {
        try {
          await listener();
        } catch {
          // A listener's failure (a refresh that timed out) does not undo the handshake.
        }
      }
      return true;
    })().finally(() => {
      this.handshaking = null;
    });
    return this.handshaking;
  }

  /** Every validated shell event, in order. Returns the unsubscribe. */
  onEvent(listener: (event: DesktopBrowserEvent) => void): () => void {
    this.eventListeners.add(listener);
    return () => this.eventListeners.delete(listener);
  }

  /** Runs after each successful handshake (the registry refreshes its tabs here). */
  onConnect(listener: () => Promise<void> | void): () => void {
    this.connectListeners.add(listener);
    return () => this.connectListeners.delete(listener);
  }

  /** Takes the listener off the port and fails whatever is still waiting. */
  dispose(): void {
    if (this.disposed) return;
    this.disposed = true;
    if (typeof this.port.off === "function") this.port.off("message", this.onMessage);
    else this.port.removeListener?.("message", this.onMessage);
    for (const [id, pending] of this.pending) {
      clearTimeout(pending.timer);
      pending.reject(new ShellLinkError("closed", "The link is closed."));
      this.pending.delete(id);
    }
    this.eventListeners.clear();
    this.connectListeners.clear();
  }

  /** One frame off the port. Never throws: what fails here is logged, and the frame dropped. */
  private receive(data: unknown): void {
    if (this.disposed) return;
    let event: DesktopBrowserEvent | null;
    try {
      const reply = parseBrowserReply(data);
      if (reply !== null) {
        this.settle(reply);
        return;
      }
      event = parseBrowserEvent(data);
    } catch (err) {
      this.log(`builtin browser: dropped a frame from the shell: ${messageOf(err)}`);
      return;
    }
    if (event === null) return;
    for (const listener of this.eventListeners) {
      try {
        listener(event);
      } catch (err) {
        this.log(
          `builtin browser: a '${event.kind}' event from the shell failed: ${messageOf(err)}`,
        );
      }
    }
  }

  private settle(reply: DesktopBrowserReplyMessage): void {
    const pending = this.pending.get(reply.id);
    if (pending === undefined) return;
    this.pending.delete(reply.id);
    clearTimeout(pending.timer);
    if (reply.ok) pending.resolve(reply.result);
    else
      pending.reject(
        new ShellLinkError("refused", reply.error ?? "The shell refused the command."),
      );
  }
}

const messageOf = (err: unknown): string => (err instanceof Error ? err.message : String(err));