@cplieger/sse 1.0.0

package/src/fold.ts

@@ -0,0 +1,225 @@
+import type { OnlineSource } from "./online.js";
+import type { VisibilityEvent, VisibilityInput, VisibilitySource } from "./visibility.js";
+
+export interface TabState {
+  readonly visible: boolean;
+  readonly online: boolean;
+  /** A freshly attached tab may earn one pageshow; cleared by its first. */
+  readonly pageshowPending: boolean;
+}
+
+export type FoldInput =
+  | {
+      readonly type: "attach";
+      readonly tabId: string;
+      readonly visible: boolean;
+      readonly online: boolean;
+    }
+  | { readonly type: "visibility"; readonly tabId: string; readonly ev: VisibilityInput }
+  | { readonly type: "network"; readonly tabId: string; readonly online: boolean }
+  /** Detach, port close, expiry: the tab leaves as if by pagehide. */
+  | { readonly type: "remove"; readonly tabId: string };
+
+export type FoldOutput = "visible" | "hidden" | "pageshow" | "online" | "offline";
+
+export interface FoldState {
+  readonly tabs: ReadonlyMap<string, TabState>;
+  /** The latest network report from any tab, seeded by the host. */
+  readonly online: boolean;
+  /** Whether a pageshow was emitted since the fold last became visible. */
+  readonly pageshown: boolean;
+}
+
+export function createFoldState(online: boolean): FoldState {
+  return { tabs: new Map(), online, pageshown: false };
+}
+
+/** The profile reads visible while any attached tab does. */
+export function anyVisible(state: FoldState): boolean {
+  for (const tab of state.tabs.values()) {
+    if (tab.visible) {
+      return true;
+    }
+  }
+  return false;
+}
+
+interface Folded {
+  readonly state: FoldState;
+  readonly events: FoldOutput[];
+}
+
+/**
+ * Folds one tab's platform event into the profile's, pure over the tab set. Visibility events
+ * precede network events within one step, the order a single tab would report them in.
+ */
+export function foldTabs(state: FoldState, input: FoldInput): Folded {
+  const tabs = new Map(state.tabs);
+  const visibilityEvents: FoldOutput[] = [];
+  const networkEvents: FoldOutput[] = [];
+  const before = anyVisible(state);
+  let online = state.online;
+  let pageshown = state.pageshown;
+
+  function report(value: boolean): void {
+    if (value !== online) {
+      online = value;
+      networkEvents.push(value ? "online" : "offline");
+    }
+  }
+
+  switch (input.type) {
+    case "attach":
+      tabs.set(input.tabId, {
+        visible: input.visible,
+        online: input.online,
+        pageshowPending: true,
+      });
+      report(input.online);
+      break;
+    case "network": {
+      const tab = tabs.get(input.tabId);
+      if (tab !== undefined) {
+        tabs.set(input.tabId, { ...tab, online: input.online });
+      }
+      report(input.online);
+      break;
+    }
+    case "remove":
+      tabs.delete(input.tabId);
+      break;
+    case "visibility": {
+      const tab = tabs.get(input.tabId);
+      if (tab === undefined) {
+        break;
+      }
+      switch (input.ev) {
+        case "visible":
+          tabs.set(input.tabId, { ...tab, visible: true });
+          break;
+        case "hidden":
+          tabs.set(input.tabId, { ...tab, visible: false });
+          break;
+        case "pagehide":
+          tabs.delete(input.tabId);
+          break;
+        case "pageshow":
+          if (tab.visible && tab.pageshowPending && !pageshown) {
+            pageshown = true;
+            visibilityEvents.push("pageshow");
+          }
+          tabs.set(input.tabId, { ...tab, pageshowPending: false });
+          break;
+      }
+      break;
+    }
+  }
+
+  const after = anyVisible({ tabs, online, pageshown });
+  if (after && !before) {
+    visibilityEvents.unshift("visible");
+    pageshown = visibilityEvents.includes("pageshow");
+  } else if (!after && before) {
+    visibilityEvents.push("hidden");
+    pageshown = false;
+  }
+  return { state: { tabs, online, pageshown }, events: [...visibilityEvents, ...networkEvents] };
+}
+
+type Listener<T> = (value: T) => void;
+
+function listenable<T>(): { readonly listeners: Set<Listener<T>>; emit(value: T): void } {
+  const listeners = new Set<Listener<T>>();
+  return {
+    listeners,
+    emit(value) {
+      for (const cb of [...listeners]) {
+        cb(value);
+      }
+    },
+  };
+}
+
+/** A VisibilitySource over attached tabs, fed by the worker host. */
+export interface ProfileVisibilitySource extends VisibilitySource {
+  attach(tabId: string, visible: boolean): void;
+  detach(tabId: string): void;
+  report(tabId: string, ev: VisibilityInput): void;
+}
+
+export function createProfileVisibilitySource(): ProfileVisibilitySource {
+  let state = createFoldState(true);
+  const out = listenable<VisibilityEvent>();
+
+  function apply(input: FoldInput): void {
+    const folded = foldTabs(state, input);
+    state = folded.state;
+    for (const ev of folded.events) {
+      if (ev === "visible" || ev === "hidden" || ev === "pageshow") {
+        out.emit(ev);
+      }
+    }
+  }
+
+  return {
+    visible: () => anyVisible(state),
+    listen(cb) {
+      out.listeners.add(cb);
+      return () => {
+        out.listeners.delete(cb);
+      };
+    },
+    attach(tabId, visible) {
+      apply({ type: "attach", tabId, visible, online: true });
+    },
+    detach(tabId) {
+      apply({ type: "remove", tabId });
+    },
+    report(tabId, ev) {
+      apply({ type: "visibility", tabId, ev });
+    },
+  };
+}
+
+/** An OnlineSource over the tabs' forwarded network events, seeded from the worker's own reading. */
+export interface ProfileOnlineSource extends OnlineSource {
+  attach(tabId: string, online: boolean): void;
+  detach(tabId: string): void;
+  report(tabId: string, online: boolean): void;
+}
+
+export function createProfileOnlineSource(seed: boolean): ProfileOnlineSource {
+  let state = createFoldState(seed);
+  const out = listenable<boolean>();
+
+  function apply(input: FoldInput): void {
+    const folded = foldTabs(state, input);
+    state = folded.state;
+    for (const ev of folded.events) {
+      if (ev === "online") {
+        out.emit(true);
+      } else if (ev === "offline") {
+        out.emit(false);
+      }
+    }
+  }
+
+  return {
+    online: () => state.online,
+    listen(cb) {
+      out.listeners.add(cb);
+      return () => {
+        out.listeners.delete(cb);
+      };
+    },
+    attach(tabId, online) {
+      apply({ type: "attach", tabId, visible: false, online });
+    },
+    detach(tabId) {
+      apply({ type: "remove", tabId });
+    },
+    report(tabId, online) {
+      apply({ type: "network", tabId, online });
+    },
+  };
+}

package/src/index.ts

@@ -0,0 +1,102 @@
+export {
+  DEFAULT_KEEPALIVE_MS,
+  DEFAULT_RETRY_MS,
+  DEFAULT_TIMING,
+  DIGEST_MAX_SUBJECTS,
+  KEEPALIVE_EVENT,
+  MAX_FRAME_BYTES,
+  MAX_OFFSET,
+  MAX_OFFSET_STRING,
+  WIRE,
+  resolveTiming,
+  watchdogMs,
+} from "./timing.js";
+export type { TimingConfig } from "./timing.js";
+export {
+  HELLO_EVENT,
+  RESERVED_PREFIX,
+  RESET_EVENT,
+  compareOffset,
+  cursorToString,
+  parseCursor,
+  parseResetReason,
+  validateHello,
+} from "./wire.js";
+export type { Cursor, Hello, HelloRefusal, HelloResult, ResetReason } from "./wire.js";
+export { createParser } from "./parser.js";
+export type { ParsedEvent, Parser, ParserHandlers, ParserOptions } from "./parser.js";
+export { initialState, jitter, reduce } from "./reducer.js";
+export type {
+  ClientEvent,
+  ClientState,
+  ConnectFailure,
+  Effect,
+  Reduction,
+  StreamEnd,
+  Timer,
+} from "./reducer.js";
+export type { HeldDiscardCause, LifecycleEvent, RevalidateCause } from "./lifecycle.js";
+export {
+  adaptVisibility,
+  createDOMVisibilitySource,
+  createVisibilityManager,
+} from "./visibility.js";
+export type {
+  VisibilityEvent,
+  VisibilityInput,
+  VisibilityManager,
+  VisibilitySource,
+} from "./visibility.js";
+export { createDOMOnlineSource, createOnlineManager } from "./online.js";
+export type { OnlineManager, OnlineSource } from "./online.js";
+export { bindListener, createVersionMap, staleListener } from "./versions.js";
+export type { Held, Subject, VersionMap, VersionMapOptions } from "./versions.js";
+export { DigestStatusError, createDigestClient } from "./digest.js";
+export type {
+  DigestClient,
+  DigestClientOptions,
+  DigestResult,
+  DigestSnapshot,
+  Removed,
+  State,
+} from "./digest.js";
+export { createStream } from "./stream.js";
+export type { Frame, RevalidateContext, Stream, StreamOptions } from "./stream.js";
+export type {
+  Connection,
+  ConnectOptions,
+  TransportCallbacks,
+  TransportFrame,
+} from "./transport.js";
+export {
+  anyVisible,
+  createFoldState,
+  createProfileOnlineSource,
+  createProfileVisibilitySource,
+  foldTabs,
+} from "./fold.js";
+export type {
+  FoldInput,
+  FoldOutput,
+  FoldState,
+  ProfileOnlineSource,
+  ProfileVisibilitySource,
+  TabState,
+} from "./fold.js";
+export { isTabMessage, isWorkerMessage } from "./port-protocol.js";
+export type {
+  DetachCause,
+  PortRevalidateContext,
+  TabToWorker,
+  WorkerToTab,
+} from "./port-protocol.js";
+export { createWorkerHost } from "./worker.js";
+export type { DigestVerdict, TabSet, WorkerHost, WorkerHostOptions } from "./worker.js";
+export { attachToWorker } from "./tab.js";
+export type {
+  AttachOptions,
+  SharedWorkerLike,
+  TabAttachment,
+  TabFallback,
+  TabRevalidateContext,
+} from "./tab.js";

package/src/lifecycle.ts

@@ -0,0 +1,48 @@
+import type { ClientState, ConnectFailure } from "./reducer.js";
+import type { Subject } from "./versions.js";
+import type { ResetReason } from "./wire.js";
+
+export type RevalidateCause = "visible" | "pageshow" | "online" | "hello";
+
+export type HeldDiscardCause =
+  "abort" | "stream_ended" | "hold_timeout" | "hold_overflow" | "revalidate_failed";
+
+/** Every record the observability feed (`onLifecycle`) can carry. Nothing branches on one. */
+export type LifecycleEvent =
+  | { kind: "state"; from: ClientState["kind"]; to: ClientState["kind"]; generation: number }
+  | {
+      kind: "hello";
+      verdict: string;
+      wire: number;
+      resumed: boolean;
+      epoch: string;
+      floor: string;
+      head: string;
+    }
+  | { kind: "watchdog"; sinceLastByteMs: number }
+  | { kind: "connect_failed"; reason: ConnectFailure }
+  | { kind: "reset"; reason: ResetReason }
+  | { kind: "stale_event"; type: string; generation: number }
+  | { kind: "drain"; length: number; dropped: number }
+  | { kind: "held_discarded"; cause: HeldDiscardCause; length: number }
+  | { kind: "revalidate_timeout" }
+  | { kind: "revalidate_failed"; cause: string; latch: boolean; ended: boolean }
+  | { kind: "wire_unsupported"; wire: number | null }
+  | { kind: "stale_stamp"; subject: Subject; epoch: string }
+  | { kind: "revalidate"; cause: RevalidateCause; full: boolean }
+  | { kind: "digest"; changed: number; removed: number; mustRefetch: boolean }
+  | { kind: "hidden_closed"; arm: "timer" | "read" }
+  | { kind: "reopened" }
+  | { kind: "alive_ack"; ok: boolean; status: number | null }
+  | { kind: "unknown_frame"; type: string }
+  | { kind: "bad_cursor"; id: string }
+  | { kind: "frame_rejected"; type: string; error: unknown }
+  | { kind: "worker_spawned" }
+  | { kind: "worker_dead"; sinceLastPortMessageMs: number }
+  | { kind: "worker_unavailable"; cause: "silent" | "error" }
+  | { kind: "worker_recovered" }
+  | { kind: "auth_lost"; route: string; status: number }
+  | { kind: "tab_attached"; replaced: boolean; state: ClientState["kind"] }
+  | { kind: "tab_detached"; cause: string }
+  | { kind: "port_expired"; sinceLastAckMs: number }
+  | { kind: "port_repaired" };

package/src/online.ts

@@ -0,0 +1,98 @@
+export interface OnlineSource {
+  online(): boolean;
+  listen(cb: (online: boolean) => void): () => void;
+}
+
+export interface OnlineManager {
+  isOnline(): boolean;
+  /** The source is listened to from the first subscriber to the last. */
+  subscribe(listener: (online: boolean) => void): () => void;
+  /** Pins the value and stops listening: emits it once, then nothing. undefined clears the pin. */
+  setOnline(value: boolean | undefined): void;
+}
+
+/** Creates the manager over `source`, defaulting to navigator.onLine and the window events. */
+export function createOnlineManager(source: OnlineSource = createDOMOnlineSource()): OnlineManager {
+  const listeners = new Set<(online: boolean) => void>();
+  let pinned: boolean | undefined;
+  let unlisten: (() => void) | null = null;
+
+  function forward(online: boolean): void {
+    for (const listener of [...listeners]) {
+      listener(online);
+    }
+  }
+
+  function listenIfNeeded(): void {
+    if (unlisten === null && listeners.size > 0 && pinned === undefined) {
+      unlisten = source.listen(forward);
+    }
+  }
+
+  function stopListening(): void {
+    unlisten?.();
+    unlisten = null;
+  }
+
+  return {
+    isOnline: () => pinned ?? source.online(),
+    subscribe(listener) {
+      listeners.add(listener);
+      listenIfNeeded();
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          stopListening();
+        }
+      };
+    },
+    setOnline(value) {
+      pinned = value;
+      if (value === undefined) {
+        listenIfNeeded();
+        return;
+      }
+      stopListening();
+      forward(value);
+    },
+  };
+}
+
+// Read through globalThis so the module typechecks under a WebWorker lib, where window is absent.
+interface DOMOnlineGlobals {
+  readonly navigator?: { readonly onLine?: boolean };
+  readonly window?: EventTarget;
+}
+
+/** navigator.onLine is a hint: true can mean no route, so the value is only ever a reason to try. */
+export function createDOMOnlineSource(): OnlineSource {
+  const dom = globalThis as DOMOnlineGlobals;
+  return {
+    online: () => dom.navigator?.onLine !== false,
+    listen(cb) {
+      const win = dom.window;
+      if (win === undefined) {
+        return () => undefined;
+      }
+      const controller = new AbortController();
+      const opts = { signal: controller.signal };
+      win.addEventListener(
+        "online",
+        () => {
+          cb(true);
+        },
+        opts,
+      );
+      win.addEventListener(
+        "offline",
+        () => {
+          cb(false);
+        },
+        opts,
+      );
+      return () => {
+        controller.abort();
+      };
+    },
+  };
+}

package/src/parser.ts

@@ -0,0 +1,193 @@
+// Parse loop follows rexxars/eventsource-parser (MIT): https://github.com/rexxars/eventsource-parser
+
+/** One dispatched frame. `id` is this frame's field or null; `lastEventId` is the sticky WHATWG value. */
+export interface ParsedEvent {
+  readonly type: string;
+  readonly data: string;
+  readonly id: string | null;
+  readonly lastEventId: string;
+  /** Encoded bytes of the frame as received, terminating blank line included. */
+  readonly bytes: number;
+}
+
+export interface ParserHandlers {
+  readonly onEvent: (event: ParsedEvent) => void;
+  readonly onRetry?: (ms: number) => void;
+  readonly onComment?: () => void;
+  /** Called once when a frame exceeds maxBufferBytes; the parser then ignores every feed until reset(). */
+  readonly onOverflow?: (bytes: number) => void;
+}
+
+export interface ParserOptions {
+  readonly maxBufferBytes: number;
+}
+
+export interface Parser {
+  feed(chunk: Uint8Array): void;
+  /** Returns the parser to its construction state; a partial event is discarded. */
+  reset(): void;
+}
+
+const LF = 0x0a;
+const CR = 0x0d;
+const DIGITS_RE = /^[0-9]+$/;
+
+/** Creates a WHATWG event-stream parser over raw bytes. */
+export function createParser(handlers: ParserHandlers, opts: ParserOptions): Parser {
+  const { onEvent, onRetry, onComment, onOverflow } = handlers;
+  const maxBufferBytes = opts.maxBufferBytes;
+
+  let decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+  let lineParts: string[] = [];
+  let pendingCR = false;
+  let atStart = true;
+  let frameBytes = 0;
+  let overflowed = false;
+
+  let dataLines: string[] = [];
+  let typeBuffer = "";
+  let frameId: string | null = null;
+  let lastEventId = "";
+
+  function dispatch(): void {
+    if (frameId !== null) {
+      lastEventId = frameId;
+    }
+    if (dataLines.length > 0) {
+      const type = typeBuffer === "" ? "message" : typeBuffer;
+      onEvent({ type, data: dataLines.join("\n"), id: frameId, lastEventId, bytes: frameBytes });
+    }
+    dataLines = [];
+    typeBuffer = "";
+    frameId = null;
+    frameBytes = 0;
+  }
+
+  function processField(field: string, value: string): void {
+    switch (field) {
+      case "event":
+        typeBuffer = value;
+        break;
+      case "data":
+        dataLines.push(value);
+        break;
+      case "id":
+        if (!value.includes("\0")) {
+          frameId = value;
+        }
+        break;
+      case "retry":
+        if (DIGITS_RE.test(value)) {
+          onRetry?.(parseInt(value, 10));
+        }
+        break;
+      default:
+        break;
+    }
+  }
+
+  function processLine(line: string): void {
+    if (line === "") {
+      dispatch();
+      return;
+    }
+    if (line.charCodeAt(0) === 0x3a) {
+      onComment?.();
+      return;
+    }
+    const colon = line.indexOf(":");
+    if (colon === -1) {
+      processField(line, "");
+      return;
+    }
+    const valueStart = line.charCodeAt(colon + 1) === 0x20 ? colon + 2 : colon + 1;
+    processField(line.slice(0, colon), line.slice(valueStart));
+  }
+
+  function endLine(bytes: Uint8Array): void {
+    let text: string;
+    if (lineParts.length === 0) {
+      text = decoder.decode(bytes);
+    } else {
+      lineParts.push(decoder.decode(bytes));
+      text = lineParts.join("");
+      lineParts = [];
+    }
+    if (atStart) {
+      atStart = false;
+      if (text.charCodeAt(0) === 0xfeff) {
+        text = text.slice(1);
+      }
+    }
+    processLine(text);
+  }
+
+  function overflow(): void {
+    overflowed = true;
+    lineParts = [];
+    dataLines = [];
+    onOverflow?.(frameBytes);
+  }
+
+  function feed(chunk: Uint8Array): void {
+    if (overflowed || chunk.length === 0) {
+      return;
+    }
+    let pos = 0;
+    if (pendingCR) {
+      pendingCR = false;
+      if (chunk[0] === LF) {
+        pos = 1;
+      }
+    }
+    let lineStart = pos;
+    while (pos < chunk.length) {
+      const b = chunk[pos];
+      if (b !== LF && b !== CR) {
+        pos++;
+        continue;
+      }
+      let terminator = 1;
+      if (b === CR) {
+        if (pos + 1 < chunk.length) {
+          if (chunk[pos + 1] === LF) {
+            terminator = 2;
+          }
+        } else {
+          pendingCR = true;
+        }
+      }
+      frameBytes += pos - lineStart + terminator;
+      if (frameBytes > maxBufferBytes) {
+        overflow();
+        return;
+      }
+      endLine(chunk.subarray(lineStart, pos));
+      pos += terminator;
+      lineStart = pos;
+    }
+    if (lineStart < chunk.length) {
+      frameBytes += chunk.length - lineStart;
+      if (frameBytes > maxBufferBytes) {
+        overflow();
+        return;
+      }
+      lineParts.push(decoder.decode(chunk.subarray(lineStart), { stream: true }));
+    }
+  }
+
+  function reset(): void {
+    decoder = new TextDecoder("utf-8", { ignoreBOM: true });
+    lineParts = [];
+    pendingCR = false;
+    atStart = true;
+    frameBytes = 0;
+    overflowed = false;
+    dataLines = [];
+    typeBuffer = "";
+    frameId = null;
+    lastEventId = "";
+  }
+
+  return { feed, reset };
+}