@cplieger/sse 1.0.0

package/src/tab.ts

@@ -0,0 +1,458 @@
+import type { LifecycleEvent } from "./lifecycle.js";
+import { type OnlineManager, createOnlineManager } from "./online.js";
+import {
+  type PortRevalidateContext,
+  type TabToWorker,
+  type WorkerToTab,
+  isWorkerMessage,
+} from "./port-protocol.js";
+import type { ClientState } from "./reducer.js";
+import type { Frame, Stream } from "./stream.js";
+import { DEFAULT_TIMING } from "./timing.js";
+import type { Subject, VersionMap } from "./versions.js";
+import {
+  type VisibilityInput,
+  type VisibilityManager,
+  adaptVisibility,
+  createVisibilityManager,
+} from "./visibility.js";
+
+/** What a host-routed run hands this tab: the port context plus the tab's own signal. */
+export type TabRevalidateContext = PortRevalidateContext & { readonly signal: AbortSignal };
+
+/** What `spawn()` returns: a SharedWorker, or anything with its port and error event. */
+export interface SharedWorkerLike {
+  readonly port: MessagePort;
+  addEventListener(type: "error", listener: () => void): void;
+}
+
+/** What `fallback()` returns: the per-tab stream and the two records the tab writes into it. */
+export interface TabFallback {
+  readonly stream: Stream;
+  /** The map the stream was built on; `observe()` records into it. */
+  readonly versions: VersionMap;
+  /** The record the stream reads at every request; the tab writes `SSE-Client` into it. */
+  readonly headers: Record<string, string>;
+}
+
+export interface AttachOptions {
+  /** Constructs the worker with the fixed URL, name and options; called on every spawn. */
+  readonly spawn: () => SharedWorkerLike;
+  /** Constructs the per-tab stream when the ladder gives up on the worker. */
+  readonly fallback: () => TabFallback;
+  readonly onFrame: (frame: Frame) => void;
+  readonly onLifecycle?: (ev: LifecycleEvent) => void;
+  /** The body, when the host routes a run to this tab. */
+  readonly revalidate?: (ctx: TabRevalidateContext) => Promise<void>;
+  readonly visibility?: VisibilityManager;
+  readonly online?: OnlineManager;
+  readonly heartbeatMs?: number;
+  /** The SSE-Client value this tab computed for the profile. */
+  readonly tag?: string;
+  /** Overrides the `typeof SharedWorker` presence test. */
+  readonly supported?: boolean;
+  /** Bound on a run routed to this tab; defaults to revalidateTimeoutMs. */
+  readonly revalidateTimeoutMs?: number;
+}
+
+export interface TabAttachment {
+  /** Leaves the host; `logout` also ends the profile's stream, or this tab's fallback stream. */
+  detach(cause?: "unload" | "logout"): void;
+  /** The host's last state broadcast, or the fallback stream's own state. */
+  state(): ClientState | null;
+  mode(): "worker" | "fallback";
+  /** Reports a stamp this tab applied, into the host's version map or the fallback's. */
+  observe(subject: Subject, version: string, epoch: string): void;
+  /** Reconnects the stream this tab is attached to; `resetCursor` drops the cursor first. */
+  reconnect(opts?: { readonly resetCursor?: boolean }): void;
+  /** Presents `tag` as SSE-Client from the next connect, reconnecting once; "" is ignored. */
+  setTag(tag: string): void;
+}
+
+const WINDOW_BEATS = 3;
+
+interface Link {
+  readonly worker: SharedWorkerLike;
+  readonly port: MessagePort;
+}
+
+function randomId(): string {
+  return crypto.randomUUID();
+}
+
+function hasSharedWorker(): boolean {
+  return typeof (globalThis as { SharedWorker?: unknown }).SharedWorker !== "undefined";
+}
+
+/** Attaches this tab to the profile's worker host, or runs the per-tab stream when it cannot. */
+export function attachToWorker(opts: AttachOptions): TabAttachment {
+  const heartbeatMs = opts.heartbeatMs ?? DEFAULT_TIMING.heartbeatMs;
+  const windowMs = WINDOW_BEATS * heartbeatMs;
+  const runTimeoutMs = opts.revalidateTimeoutMs ?? DEFAULT_TIMING.revalidateTimeoutMs;
+  const visibility = opts.visibility ?? createVisibilityManager();
+  const online = opts.online ?? createOnlineManager();
+  const tabId = randomId();
+  let tag = opts.tag ?? "";
+
+  let mode: "worker" | "fallback" = "worker";
+  let link: Link | null = null;
+  let fallback: TabFallback | null = null;
+  let lastState: ClientState | null = null;
+  let watchdog: ReturnType<typeof setTimeout> | null = null;
+  let lastPortMessageAt = Date.now();
+  let heartbeatSeen = false;
+  let silentSpawns = 0;
+  let pingSeq = 0;
+  let probe: { readonly link: Link; readonly timer: ReturnType<typeof setTimeout> } | null = null;
+  let triedThisVisible = false;
+  let detached = false;
+
+  const now = (): number => Date.now();
+
+  function emit(event: LifecycleEvent): void {
+    opts.onLifecycle?.(event);
+  }
+
+  function post(message: TabToWorker): void {
+    link?.port.postMessage(message);
+  }
+
+  function disarmWatchdog(): void {
+    if (watchdog !== null) {
+      clearTimeout(watchdog);
+      watchdog = null;
+    }
+  }
+
+  function armWatchdog(): void {
+    disarmWatchdog();
+    watchdog = setTimeout(onWatchdog, windowMs);
+  }
+
+  function abandon(): void {
+    disarmWatchdog();
+    if (link === null) {
+      return;
+    }
+    link.port.onmessage = null;
+    link.port.close();
+    link = null;
+  }
+
+  function attachMessage(hadWorker: boolean): TabToWorker {
+    return {
+      type: "attach",
+      tabId,
+      visible: visibility.isVisible(),
+      online: online.isOnline(),
+      hadWorker,
+      tag,
+    };
+  }
+
+  function spawnLink(): Link | null {
+    let worker: SharedWorkerLike;
+    try {
+      worker = opts.spawn();
+    } catch {
+      return null;
+    }
+    return { worker, port: worker.port };
+  }
+
+  function spawnAndAttach(hadWorker: boolean): void {
+    const next = spawnLink();
+    if (next === null) {
+      fallbackNow("error");
+      return;
+    }
+    link = next;
+    heartbeatSeen = false;
+    next.worker.addEventListener("error", () => {
+      if (link === next) {
+        fallbackNow("error");
+      }
+    });
+    next.port.onmessage = (event: MessageEvent) => {
+      if (link === next) {
+        onMessage(event.data);
+      }
+    };
+    next.port.start();
+    post(attachMessage(hadWorker));
+    emit({ kind: "worker_spawned" });
+    lastPortMessageAt = now();
+    if (visibility.isVisible()) {
+      armWatchdog();
+    }
+  }
+
+  function runRevalidate(port: MessagePort, runId: number, ctx: PortRevalidateContext): void {
+    const reply = (message: TabToWorker): void => {
+      if (link?.port === port) {
+        port.postMessage(message);
+      }
+    };
+    if (opts.revalidate === undefined) {
+      reply({ type: "revalidate_done", runId });
+      return;
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => {
+      controller.abort(new DOMException("revalidate timed out", "TimeoutError"));
+    }, runTimeoutMs);
+    let promise: Promise<void>;
+    try {
+      promise = Promise.resolve(opts.revalidate({ ...ctx, signal: controller.signal }));
+    } catch (e: unknown) {
+      promise = Promise.reject(e instanceof Error ? e : new Error(String(e)));
+    }
+    promise
+      .then(
+        () => {
+          reply({ type: "revalidate_done", runId });
+        },
+        (e: unknown) => {
+          reply({
+            type: "revalidate_failed",
+            runId,
+            cause: e instanceof Error ? e.message : String(e),
+          });
+        },
+      )
+      .finally(() => {
+        clearTimeout(timer);
+      });
+  }
+
+  function onMessage(data: unknown): void {
+    if (!isWorkerMessage(data) || link === null) {
+      return;
+    }
+    lastPortMessageAt = now();
+    if (visibility.isVisible()) {
+      armWatchdog();
+    }
+    const message: WorkerToTab = data;
+    switch (message.type) {
+      case "heartbeat":
+        heartbeatSeen = true;
+        silentSpawns = 0;
+        post({ type: "heartbeat_ack", seq: message.seq });
+        return;
+      case "pong":
+      case "stale":
+        return;
+      case "frame":
+        try {
+          opts.onFrame(message.frame);
+        } catch {
+          post({ type: "frame_failed", generation: message.generation, cursor: message.frame.id });
+        }
+        return;
+      case "lifecycle":
+        emit(message.event);
+        return;
+      case "revalidate_run":
+        runRevalidate(link.port, message.runId, message.ctx);
+        return;
+      case "state":
+        lastState = message.state;
+        return;
+    }
+  }
+
+  function onWatchdog(): void {
+    watchdog = null;
+    if (link === null || !visibility.isVisible()) {
+      return;
+    }
+    emit({ kind: "worker_dead", sinceLastPortMessageMs: now() - lastPortMessageAt });
+    silentSpawns = heartbeatSeen ? 0 : silentSpawns + 1;
+    if (silentSpawns >= 2) {
+      fallbackNow("silent");
+      return;
+    }
+    post({ type: "detach", cause: "respawn" });
+    abandon();
+    spawnAndAttach(true);
+  }
+
+  function startFallback(): void {
+    fallback = opts.fallback();
+    if (tag !== "") {
+      fallback.headers["SSE-Client"] = tag;
+    }
+    fallback.stream.start();
+  }
+
+  function fallbackNow(cause: "silent" | "error"): void {
+    post({ type: "detach", cause: "fallback" });
+    abandon();
+    mode = "fallback";
+    triedThisVisible = true;
+    startFallback();
+    emit({ kind: "worker_unavailable", cause });
+  }
+
+  function closeProbe(): void {
+    if (probe === null) {
+      return;
+    }
+    clearTimeout(probe.timer);
+    probe.link.port.onmessage = null;
+    probe.link.port.close();
+    probe = null;
+  }
+
+  function tryRecover(): void {
+    const next = spawnLink();
+    if (next === null) {
+      return;
+    }
+    const current: { readonly link: Link; readonly timer: ReturnType<typeof setTimeout> } = {
+      link: next,
+      timer: setTimeout(closeProbe, windowMs),
+    };
+    probe = current;
+    next.worker.addEventListener("error", () => {
+      if (probe === current) {
+        closeProbe();
+      }
+    });
+    next.port.onmessage = (event: MessageEvent) => {
+      const data: unknown = event.data;
+      if (probe !== current || !isWorkerMessage(data) || data.type !== "heartbeat") {
+        return;
+      }
+      clearTimeout(current.timer);
+      probe = null;
+      fallback?.stream.stop();
+      fallback = null;
+      mode = "worker";
+      link = next;
+      heartbeatSeen = true;
+      silentSpawns = 0;
+      next.port.onmessage = (inner: MessageEvent) => {
+        if (link === next) {
+          onMessage(inner.data);
+        }
+      };
+      post({ type: "heartbeat_ack", seq: data.seq });
+      post(attachMessage(true));
+      lastPortMessageAt = now();
+      if (visibility.isVisible()) {
+        armWatchdog();
+      }
+      emit({ kind: "worker_recovered" });
+    };
+    next.port.start();
+  }
+
+  function onVisibility(input: VisibilityInput): void {
+    if (mode === "fallback") {
+      if (input === "visible" && !triedThisVisible) {
+        triedThisVisible = true;
+        tryRecover();
+      } else if (input === "hidden" || input === "pagehide") {
+        triedThisVisible = false;
+        closeProbe();
+      }
+      return;
+    }
+    switch (input) {
+      case "visible":
+        post({ type: "visibility", ev: "visible" });
+        post({ type: "ping", seq: ++pingSeq });
+        if (link !== null) {
+          lastPortMessageAt = now();
+          armWatchdog();
+        }
+        return;
+      case "hidden":
+        post({ type: "visibility", ev: "hidden" });
+        disarmWatchdog();
+        return;
+      case "pagehide":
+        post({ type: "visibility", ev: "pagehide" });
+        abandon();
+        return;
+      case "pageshow":
+        if (link === null) {
+          spawnAndAttach(true);
+        } else {
+          post({ type: "visibility", ev: "pageshow" });
+        }
+        return;
+    }
+  }
+
+  const unsubscribes = [
+    adaptVisibility(
+      visibility,
+      { visible: () => visibility.isVisible(), listen: () => () => undefined },
+      onVisibility,
+    ),
+    online.subscribe((value) => {
+      post({ type: "network", online: value });
+    }),
+  ];
+
+  if (opts.supported ?? hasSharedWorker()) {
+    spawnAndAttach(false);
+  } else {
+    mode = "fallback";
+    startFallback();
+  }
+
+  return {
+    detach(cause = "unload") {
+      if (detached) {
+        return;
+      }
+      detached = true;
+      post({ type: "detach", cause });
+      abandon();
+      closeProbe();
+      for (const unsubscribe of unsubscribes) {
+        unsubscribe();
+      }
+      fallback?.stream.stop();
+    },
+    state: () => (mode === "fallback" ? (fallback?.stream.state() ?? null) : lastState),
+    mode: () => mode,
+    observe(subject, version, epoch) {
+      if (mode === "fallback") {
+        fallback?.versions.observe(subject, version, epoch);
+        return;
+      }
+      post({ type: "observed", subject, version, epoch });
+    },
+    reconnect(reconnectOpts) {
+      const resetCursor = reconnectOpts?.resetCursor ?? false;
+      if (mode === "fallback") {
+        if (resetCursor) {
+          fallback?.stream.resetCursor();
+        }
+        fallback?.stream.reconnect();
+        return;
+      }
+      post({ type: "reconnect", resetCursor });
+    },
+    setTag(next) {
+      if (next === "") {
+        return;
+      }
+      const changed = next !== tag;
+      tag = next;
+      if (mode === "fallback") {
+        if (changed && fallback !== null) {
+          fallback.headers["SSE-Client"] = next;
+          fallback.stream.reconnect();
+        }
+        return;
+      }
+      post({ type: "set_tag", tag: next });
+    },
+  };
+}

package/src/timing.ts

@@ -0,0 +1,98 @@
+/** Wire revision this client speaks; a hello outside [minWire, maxWire] is refused. */
+export const WIRE = 1;
+
+/** Largest encoded frame either side accepts, terminating blank line included. */
+export const MAX_FRAME_BYTES = 1_048_576;
+
+/** Largest offset a cursor may carry: 2^53 - 1, the JavaScript exact-integer bound. */
+export const MAX_OFFSET = 9_007_199_254_740_991n;
+
+/** MAX_OFFSET as the decimal string it takes on the wire. */
+export const MAX_OFFSET_STRING = "9007199254740991";
+
+/** Server keepalive interval the hello reports when the hub runs at its default. */
+export const DEFAULT_KEEPALIVE_MS = 15_000;
+
+/** The `retry:` value the server writes when it runs at its default. */
+export const DEFAULT_RETRY_MS = 1_500;
+
+/** Event name of the server keepalive frame when the hub runs at its default. */
+export const KEEPALIVE_EVENT = "sse:keepalive";
+
+/** Subjects one digest request may carry when the server runs at its default. */
+export const DIGEST_MAX_SUBJECTS = 256;
+
+/** Client-side timing knobs. Every field has a default in DEFAULT_TIMING. */
+export interface TimingConfig {
+  /** Deadline from fetch start to response headers. */
+  readonly connectTimeoutMs: number;
+  /** Deadline from response headers to a complete, valid hello. */
+  readonly helloTimeoutMs: number;
+  /** Bound on one revalidate run; the run's signal aborts at it. */
+  readonly revalidateTimeoutMs: number;
+  /** Deadline on one digest POST. */
+  readonly digestTimeoutMs: number;
+  /** Frames a hold may queue before the connection ends with hold_overflow. */
+  readonly heldMaxFrames: number;
+  /** Encoded bytes a hold may queue before the connection ends with hold_overflow. */
+  readonly heldMaxBytes: number;
+  /** Full-jitter backoff base. */
+  readonly baseMs: number;
+  /** Full-jitter backoff cap. */
+  readonly capMs: number;
+  /** Connected time after which the backoff attempt counter resets. */
+  readonly stableMs: number;
+  /** Hidden time after which the stream is closed deliberately. */
+  readonly hiddenCloseAfterMs: number;
+  /** Minimum spacing between two wake-driven revalidations. */
+  readonly wakeThrottleMs: number;
+  /** Worker-host port heartbeat interval. */
+  readonly heartbeatMs: number;
+  /** Keepalives received per alive acknowledgement POST. */
+  readonly aliveEveryBeats: number;
+  /** Missed keepalives before the silence watchdog fires. */
+  readonly watchdogBeats: number;
+  /** Lower bound on the watchdog interval whatever the keepalive is. */
+  readonly watchdogFloorMs: number;
+  /** Parser buffer cap; must be at least MAX_FRAME_BYTES. */
+  readonly maxBufferBytes: number;
+}
+
+export const DEFAULT_TIMING: TimingConfig = {
+  connectTimeoutMs: 15_000,
+  helloTimeoutMs: 10_000,
+  revalidateTimeoutMs: 30_000,
+  digestTimeoutMs: 10_000,
+  heldMaxFrames: 2_000,
+  heldMaxBytes: 64 * MAX_FRAME_BYTES,
+  baseMs: 500,
+  capMs: 30_000,
+  stableMs: 30_000,
+  hiddenCloseAfterMs: 60_000,
+  wakeThrottleMs: 1_000,
+  heartbeatMs: 5_000,
+  aliveEveryBeats: 1,
+  watchdogBeats: 3,
+  watchdogFloorMs: 15_000,
+  maxBufferBytes: MAX_FRAME_BYTES,
+};
+
+// Silence watchdog derivation follows Yaffle/EventSource: max(3 beats, 15 s), 45 s at the default keepalive.
+export function watchdogMs(keepaliveMs: number, cfg: TimingConfig = DEFAULT_TIMING): number {
+  return Math.max(cfg.watchdogBeats * keepaliveMs, cfg.watchdogFloorMs);
+}
+
+/**
+ * Fills a partial timing with the defaults. Throws RangeError when maxBufferBytes is
+ * below MAX_FRAME_BYTES: the two caps are one wire rule, and a lower client cap would
+ * make a legal ring entry abort every reconnect.
+ */
+export function resolveTiming(partial: Partial<TimingConfig> = {}): TimingConfig {
+  const cfg: TimingConfig = { ...DEFAULT_TIMING, ...partial };
+  if (cfg.maxBufferBytes < MAX_FRAME_BYTES) {
+    throw new RangeError(
+      `maxBufferBytes ${String(cfg.maxBufferBytes)} is below MAX_FRAME_BYTES ${String(MAX_FRAME_BYTES)}`,
+    );
+  }
+  return cfg;
+}