@cplieger/sse 1.0.0

package/src/transport.ts

@@ -0,0 +1,278 @@
+import { createParser } from "./parser.js";
+import type { ConnectFailure, StreamEnd } from "./reducer.js";
+import type { TimingConfig } from "./timing.js";
+import {
+  type Cursor,
+  HELLO_EVENT,
+  type Hello,
+  RESERVED_PREFIX,
+  RESET_EVENT,
+  cursorToString,
+  parseCursor,
+  parseResetReason,
+  validateHello,
+} from "./wire.js";
+
+/** An application frame as the transport hands it up: the id already parsed as a cursor. */
+export interface TransportFrame {
+  readonly type: string;
+  readonly data: string;
+  readonly id: Cursor | null;
+  /** Encoded bytes of the frame as received; feeds the hold's byte bound. */
+  readonly bytes: number;
+}
+
+/**
+ * What one connection attempt reports. Every callback carries the attempt's generation.
+ * Exactly one of onConnected-then-onEnd, onConnectFailed, or nothing (after abort) happens.
+ */
+export interface TransportCallbacks {
+  readonly onByte: (generation: number) => void;
+  readonly onConnected: (generation: number, hello: Hello) => void;
+  readonly onConnectFailed: (generation: number, reason: ConnectFailure) => void;
+  readonly onFrame: (generation: number, frame: TransportFrame) => void;
+  readonly onKeepalive: (generation: number) => void;
+  readonly onUnknownFrame: (generation: number, type: string) => void;
+  readonly onBadCursor: (generation: number, id: string) => void;
+  readonly onRetry: (generation: number, ms: number) => void;
+  readonly onEnd: (generation: number, reason: StreamEnd) => void;
+}
+
+export interface ConnectOptions {
+  readonly url: string;
+  readonly fetch: typeof fetch;
+  readonly headers: Readonly<Record<string, string>>;
+  readonly cursor: Cursor | null;
+  readonly minWire: number;
+  readonly maxWire: number;
+  readonly timing: TimingConfig;
+  readonly generation: number;
+  readonly callbacks: TransportCallbacks;
+}
+
+export interface Connection {
+  /** Ends the attempt; nothing is dispatched afterwards. */
+  abort(reason: string): void;
+}
+
+const EVENT_STREAM = "text/event-stream";
+
+function mediaType(contentType: string | null): string {
+  if (contentType === null) {
+    return "";
+  }
+  const semicolon = contentType.indexOf(";");
+  return (semicolon === -1 ? contentType : contentType.slice(0, semicolon)).trim().toLowerCase();
+}
+
+/** Opens one stream attempt: fetch, the two connect-phase deadlines, and the frame translation. */
+export function connect(opts: ConnectOptions): Connection {
+  const { generation: g, callbacks: cb, timing } = opts;
+  const controller = new AbortController();
+  let abortReason: string | null = null;
+  let finished = false;
+  let helloSeen = false;
+  let keepaliveEvent = "";
+  let deadline: ReturnType<typeof setTimeout> | null = null;
+
+  function clearDeadline(): void {
+    if (deadline !== null) {
+      clearTimeout(deadline);
+      deadline = null;
+    }
+  }
+
+  function abort(reason: string): void {
+    abortReason ??= reason;
+    controller.abort(new DOMException(reason, "AbortError"));
+  }
+
+  const reason = (): string | null => abortReason;
+  const done = (): boolean => finished;
+
+  function fail(reason: ConnectFailure): void {
+    if (finished) {
+      return;
+    }
+    finished = true;
+    clearDeadline();
+    abort("refused");
+    cb.onConnectFailed(g, reason);
+  }
+
+  function end(reason: StreamEnd): void {
+    if (finished) {
+      return;
+    }
+    finished = true;
+    clearDeadline();
+    abort("ended");
+    cb.onEnd(g, reason);
+  }
+
+  const parser = createParser(
+    {
+      onEvent(ev) {
+        if (finished) {
+          return;
+        }
+        if (!helloSeen) {
+          if (ev.type !== HELLO_EVENT) {
+            fail({ kind: "bad_hello" });
+            return;
+          }
+          let data: unknown;
+          try {
+            data = JSON.parse(ev.data);
+          } catch {
+            fail({ kind: "bad_hello" });
+            return;
+          }
+          const result = validateHello(data, opts.minWire, opts.maxWire);
+          if (!result.ok) {
+            fail(result.reason);
+            return;
+          }
+          helloSeen = true;
+          keepaliveEvent = result.hello.keepalive_event;
+          clearDeadline();
+          cb.onConnected(g, result.hello);
+          return;
+        }
+        if (ev.type === HELLO_EVENT) {
+          end("error");
+          return;
+        }
+        if (ev.type === keepaliveEvent) {
+          cb.onKeepalive(g);
+          return;
+        }
+        if (ev.type === RESET_EVENT) {
+          end(parseResetReason(ev.data) ?? "error");
+          return;
+        }
+        if (ev.type.startsWith(RESERVED_PREFIX)) {
+          cb.onUnknownFrame(g, ev.type);
+          return;
+        }
+        let id: Cursor | null = null;
+        if (ev.id !== null) {
+          id = parseCursor(ev.id);
+          if (id === null) {
+            cb.onBadCursor(g, ev.id);
+            return;
+          }
+        }
+        cb.onFrame(g, { type: ev.type, data: ev.data, id, bytes: ev.bytes });
+      },
+      onRetry(ms) {
+        if (!finished) {
+          cb.onRetry(g, ms);
+        }
+      },
+      onOverflow() {
+        end("frame_too_large");
+      },
+    },
+    { maxBufferBytes: timing.maxBufferBytes },
+  );
+
+  function requestHeaders(): Record<string, string> {
+    const headers: Record<string, string> = {
+      Accept: EVENT_STREAM,
+      "SSE-Wire": String(opts.maxWire),
+    };
+    if (opts.cursor !== null) {
+      headers["Last-Event-ID"] = cursorToString(opts.cursor);
+    }
+    return { ...headers, ...opts.headers };
+  }
+
+  async function run(): Promise<void> {
+    deadline = setTimeout(() => {
+      abort("timeout_headers");
+    }, timing.connectTimeoutMs);
+    let response: Response;
+    try {
+      response = await opts.fetch(opts.url, {
+        headers: requestHeaders(),
+        cache: "no-store",
+        credentials: "same-origin",
+        signal: controller.signal,
+      });
+    } catch {
+      clearDeadline();
+      if (reason() === "timeout_headers") {
+        fail({ kind: "timeout_headers" });
+      } else if (reason() === null) {
+        fail({ kind: "network" });
+      }
+      return;
+    }
+    clearDeadline();
+    if (reason() !== null) {
+      return;
+    }
+    if (response.status !== 200) {
+      fail({ kind: "status", status: response.status });
+      return;
+    }
+    const contentType = response.headers.get("content-type");
+    if (mediaType(contentType) !== EVENT_STREAM) {
+      fail({ kind: "content_type", value: contentType ?? "" });
+      return;
+    }
+    if (response.body === null) {
+      end("eof");
+      return;
+    }
+    deadline = setTimeout(() => {
+      abort("timeout_hello");
+    }, timing.helloTimeoutMs);
+    const reader = response.body.getReader();
+    for (;;) {
+      let result: ReadableStreamReadResult<Uint8Array>;
+      try {
+        result = await reader.read();
+      } catch {
+        if (done()) {
+          return;
+        }
+        if (reason() === "timeout_hello") {
+          fail({ kind: "timeout_hello" });
+        } else if (reason() === null) {
+          end("error");
+        }
+        return;
+      }
+      if (done() || reason() !== null) {
+        return;
+      }
+      if (result.done) {
+        end("eof");
+        return;
+      }
+      if (result.value.length === 0) {
+        continue;
+      }
+      cb.onByte(g);
+      parser.feed(result.value);
+      if (done()) {
+        return;
+      }
+    }
+  }
+
+  void run();
+
+  return {
+    abort(reason) {
+      if (finished) {
+        return;
+      }
+      finished = true;
+      clearDeadline();
+      abort(reason);
+    },
+  };
+}

package/src/versions.ts

@@ -0,0 +1,134 @@
+/** A digest subject key: the application's kind and reference. */
+export interface Subject {
+  readonly kind: string;
+  readonly ref: string;
+}
+
+/** A subject with the version the client holds for it. */
+export interface Held extends Subject {
+  readonly version: string;
+}
+
+/**
+ * The epoch-bound version map. Versions are opaque strings recorded after the state they
+ * stamp has been applied, never from a digest answer.
+ */
+export interface VersionMap {
+  /** The epoch every held version was minted under; null until bound. */
+  epoch(): string | null;
+  /** Binds the map to `epoch`; a different epoch clears every entry. Returns the dropped count. */
+  bind(epoch: string): number;
+  /**
+   * Records `version` for `subject` and returns whether the held version changed. With `epoch`:
+   * an unbound map binds to it first; a map bound to a different epoch ignores the call and
+   * reports it through onStale.
+   */
+  observe(subject: Subject, version: string, epoch?: string): boolean;
+  forget(subject: Subject): void;
+  has(subject: Subject): boolean;
+  snapshot(): { epoch: string | null; held: Held[] };
+}
+
+export interface VersionMapOptions {
+  /** Called for every stamp ignored because its epoch differs from the bound epoch. */
+  readonly onStale?: (subject: Subject, epoch: string) => void;
+}
+
+type BindListener = (epoch: string, dropped: number) => void;
+type StaleListener = (subject: Subject, epoch: string) => void;
+
+interface Listeners {
+  readonly bound: Set<BindListener>;
+  readonly stale: Set<StaleListener>;
+}
+
+const listeners = new WeakMap<VersionMap, Listeners>();
+
+function key(subject: Subject): string {
+  return `${subject.kind}\0${subject.ref}`;
+}
+
+// Epoch binding follows IMAP CONDSTORE (RFC 7162): a UIDVALIDITY change discards cached mod-sequences.
+/** Creates an empty, unbound version map. */
+export function createVersionMap(opts: VersionMapOptions = {}): VersionMap {
+  let epoch: string | null = null;
+  const held = new Map<string, Held>();
+  const bound = new Set<BindListener>();
+  const stale = new Set<StaleListener>();
+
+  const map: VersionMap = {
+    epoch: () => epoch,
+    bind(next) {
+      let dropped = 0;
+      if (epoch !== next) {
+        dropped = held.size;
+        held.clear();
+        epoch = next;
+      }
+      for (const listener of bound) {
+        listener(next, dropped);
+      }
+      return dropped;
+    },
+    observe(subject, version, stampEpoch) {
+      if (stampEpoch !== undefined) {
+        if (epoch === null) {
+          epoch = stampEpoch;
+        } else if (epoch !== stampEpoch) {
+          opts.onStale?.(subject, stampEpoch);
+          for (const listener of stale) {
+            listener(subject, stampEpoch);
+          }
+          return false;
+        }
+      }
+      const k = key(subject);
+      const previous = held.get(k);
+      held.set(k, { kind: subject.kind, ref: subject.ref, version });
+      return previous?.version !== version;
+    },
+    forget(subject) {
+      held.delete(key(subject));
+    },
+    has(subject) {
+      return held.has(key(subject));
+    },
+    snapshot() {
+      return { epoch, held: [...held.values()] };
+    },
+  };
+  listeners.set(map, { bound, stale });
+  return map;
+}
+
+function listenersOf(map: VersionMap, caller: string): Listeners {
+  const set = listeners.get(map);
+  if (set === undefined) {
+    throw new TypeError(`${caller}: map was not created by createVersionMap`);
+  }
+  return set;
+}
+
+/**
+ * Subscribes to every bind() on a map created by createVersionMap; the runtime uses it to
+ * discharge a queued full revalidation. Returns the unsubscribe. Throws on a foreign map.
+ */
+export function bindListener(map: VersionMap, fn: BindListener): () => void {
+  const set = listenersOf(map, "bindListener").bound;
+  set.add(fn);
+  return () => {
+    set.delete(fn);
+  };
+}
+
+/**
+ * Subscribes to every stamp the map ignores for a foreign epoch; the runtime reports each as
+ * stale_stamp. Returns the unsubscribe. Throws on a foreign map.
+ */
+export function staleListener(map: VersionMap, fn: StaleListener): () => void {
+  const set = listenersOf(map, "staleListener").stale;
+  set.add(fn);
+  return () => {
+    set.delete(fn);
+  };
+}

package/src/visibility.ts

@@ -0,0 +1,137 @@
+export type VisibilityEvent = "visible" | "hidden" | "pagehide" | "pageshow" | "freeze" | "resume";
+
+/** The four visibility inputs the reducer accepts; the adapter folds freeze and resume into them. */
+export type VisibilityInput = "visible" | "hidden" | "pagehide" | "pageshow";
+
+export interface VisibilitySource {
+  visible(): boolean;
+  listen(cb: (ev: VisibilityEvent) => void): () => void;
+}
+
+export interface VisibilityManager {
+  isVisible(): boolean;
+  /** The source is listened to from the first subscriber to the last. */
+  subscribe(listener: (ev: VisibilityEvent) => void): () => void;
+  /** Pins the value and stops listening: emits visible or hidden once, then nothing. undefined clears the pin. */
+  setVisible(value: boolean | undefined): void;
+}
+
+/** Creates the manager over `source`, defaulting to the DOM. */
+export function createVisibilityManager(
+  source: VisibilitySource = createDOMVisibilitySource(),
+): VisibilityManager {
+  const listeners = new Set<(ev: VisibilityEvent) => void>();
+  let pinned: boolean | undefined;
+  let unlisten: (() => void) | null = null;
+
+  function forward(ev: VisibilityEvent): void {
+    for (const listener of [...listeners]) {
+      listener(ev);
+    }
+  }
+
+  function listenIfNeeded(): void {
+    if (unlisten === null && listeners.size > 0 && pinned === undefined) {
+      unlisten = source.listen(forward);
+    }
+  }
+
+  function stopListening(): void {
+    unlisten?.();
+    unlisten = null;
+  }
+
+  return {
+    isVisible: () => pinned ?? source.visible(),
+    subscribe(listener) {
+      listeners.add(listener);
+      listenIfNeeded();
+      return () => {
+        listeners.delete(listener);
+        if (listeners.size === 0) {
+          stopListening();
+        }
+      };
+    },
+    setVisible(value) {
+      pinned = value;
+      if (value === undefined) {
+        listenIfNeeded();
+        return;
+      }
+      stopListening();
+      forward(value ? "visible" : "hidden");
+    },
+  };
+}
+
+// Read through globalThis so the module typechecks under a WebWorker lib, where neither exists.
+interface DOMVisibilityGlobals {
+  readonly document?: EventTarget & { readonly visibilityState?: string };
+  readonly window?: EventTarget;
+}
+
+/** The only reader of document and window visibility in the package. */
+export function createDOMVisibilitySource(): VisibilitySource {
+  const dom = globalThis as DOMVisibilityGlobals;
+  const visible = (): boolean => dom.document?.visibilityState !== "hidden";
+  return {
+    visible,
+    listen(cb) {
+      const doc = dom.document;
+      const win = dom.window;
+      if (doc === undefined || win === undefined) {
+        return () => undefined;
+      }
+      const controller = new AbortController();
+      const opts = { signal: controller.signal };
+      const on = (target: EventTarget, type: string, ev: () => VisibilityEvent): void => {
+        target.addEventListener(
+          type,
+          () => {
+            cb(ev());
+          },
+          opts,
+        );
+      };
+      on(doc, "visibilitychange", () => (visible() ? "visible" : "hidden"));
+      on(doc, "freeze", () => "freeze");
+      on(doc, "resume", () => "resume");
+      on(win, "pagehide", () => "pagehide");
+      on(win, "pageshow", () => "pageshow");
+      return () => {
+        controller.abort();
+      };
+    },
+  };
+}
+
+/**
+ * Maps manager events onto reducer inputs: freeze is hidden; resume and pageshow are emitted
+ * only while the source reads visible, because a restored or resumed page may still be hidden.
+ */
+export function adaptVisibility(
+  manager: VisibilityManager,
+  source: VisibilitySource,
+  emit: (ev: VisibilityInput) => void,
+): () => void {
+  return manager.subscribe((ev) => {
+    switch (ev) {
+      case "freeze":
+        emit("hidden");
+        return;
+      case "resume":
+        if (source.visible()) {
+          emit("visible");
+        }
+        return;
+      case "pageshow":
+        if (source.visible()) {
+          emit("pageshow");
+        }
+        return;
+      default:
+        emit(ev);
+    }
+  });
+}

package/src/wire.ts

@@ -0,0 +1,156 @@
+import { MAX_OFFSET_STRING } from "./timing.js";
+
+/** Event name of the handshake frame the server writes once per connection. */
+export const HELLO_EVENT = "sse:hello";
+
+/** Event name of the frame the server writes immediately before a deliberate close. */
+export const RESET_EVENT = "sse:reset";
+
+/** Prefix reserved for library-owned frames; an application never publishes one. */
+export const RESERVED_PREFIX = "sse:";
+
+/** A resume position: the hub epoch and a decimal offset, presented as `Last-Event-ID`. */
+export interface Cursor {
+  readonly epoch: string;
+  readonly offset: string;
+}
+
+/** The hello frame's payload after validation. `resumed === true` is the only branch point. */
+export interface Hello {
+  readonly wire: number;
+  readonly epoch: string;
+  readonly floor: string;
+  readonly head: string;
+  readonly resumed: boolean;
+  readonly verdict: string;
+  readonly keepalive_ms: number;
+  readonly keepalive_event: string;
+}
+
+/** Why a hello was refused; both reasons take the ordinary backoff ladder. */
+export type HelloRefusal =
+  { kind: "bad_hello" } | { kind: "wire_unsupported"; wire: number | null };
+
+export type HelloResult = { ok: true; hello: Hello } | { ok: false; reason: HelloRefusal };
+
+const EPOCH_RE = /^[0-9a-f]{16}$/;
+const OFFSET_RE = /^(0|[1-9][0-9]*)$/;
+const MAX_CURSOR_LENGTH = 33;
+
+/** Orders two offsets in the wire grammar exactly, above 2^53 included. */
+export function compareOffset(a: string, b: string): -1 | 0 | 1 {
+  const x = BigInt(a);
+  const y = BigInt(b);
+  if (x < y) {
+    return -1;
+  }
+  return x > y ? 1 : 0;
+}
+
+function isOffset(value: unknown): value is string {
+  return (
+    typeof value === "string" &&
+    OFFSET_RE.test(value) &&
+    compareOffset(value, MAX_OFFSET_STRING) <= 0
+  );
+}
+
+function isEpoch(value: unknown): value is string {
+  return typeof value === "string" && EPOCH_RE.test(value);
+}
+
+/** Parses `<epoch>:<offset>`; null for anything else, a bare integer included. */
+export function parseCursor(id: string): Cursor | null {
+  if (id.length === 0 || id.length > MAX_CURSOR_LENGTH) {
+    return null;
+  }
+  const colon = id.indexOf(":");
+  if (colon === -1) {
+    return null;
+  }
+  const epoch = id.slice(0, colon);
+  const offset = id.slice(colon + 1);
+  if (!isEpoch(epoch) || !isOffset(offset)) {
+    return null;
+  }
+  return { epoch, offset };
+}
+
+/** Renders a cursor as the `Last-Event-ID` value the server parses. */
+export function cursorToString(cursor: Cursor): string {
+  return `${cursor.epoch}:${cursor.offset}`;
+}
+
+const BAD_HELLO: HelloResult = { ok: false, reason: { kind: "bad_hello" } };
+
+// Structural pessimism follows Centrifugo's recovered/was_recovering: only `resumed === true` resumes.
+/** Validates a decoded hello payload against the wire contract and the accepted revision range. */
+export function validateHello(data: unknown, minWire: number, maxWire: number): HelloResult {
+  if (typeof data !== "object" || data === null) {
+    return BAD_HELLO;
+  }
+  const record = data as Record<string, unknown>;
+  const wire = record["wire"];
+  if (typeof wire !== "number" || !Number.isInteger(wire)) {
+    return BAD_HELLO;
+  }
+  if (wire < minWire || wire > maxWire) {
+    return { ok: false, reason: { kind: "wire_unsupported", wire } };
+  }
+  const epoch = record["epoch"];
+  const floor = record["floor"];
+  const head = record["head"];
+  const resumed = record["resumed"];
+  const keepaliveMs = record["keepalive_ms"];
+  const keepaliveEvent = record["keepalive_event"];
+  if (!isEpoch(epoch) || !isOffset(floor) || !isOffset(head)) {
+    return BAD_HELLO;
+  }
+  if (typeof resumed !== "boolean") {
+    return BAD_HELLO;
+  }
+  if (typeof keepaliveMs !== "number" || !Number.isInteger(keepaliveMs) || keepaliveMs <= 0) {
+    return BAD_HELLO;
+  }
+  if (typeof keepaliveEvent !== "string") {
+    return BAD_HELLO;
+  }
+  const verdict = record["verdict"];
+  return {
+    ok: true,
+    hello: {
+      wire,
+      epoch,
+      floor,
+      head,
+      resumed,
+      verdict: typeof verdict === "string" ? verdict : "",
+      keepalive_ms: keepaliveMs,
+      keepalive_event: keepaliveEvent,
+    },
+  };
+}
+
+/** The two stream-end reasons an `sse:reset` frame can carry. */
+export type ResetReason = "reset:slow" | "reset:shutdown";
+
+/** Maps an `sse:reset` payload to its reason; null when the payload is not one of the two. */
+export function parseResetReason(data: string): ResetReason | null {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(data);
+  } catch {
+    return null;
+  }
+  if (typeof parsed !== "object" || parsed === null) {
+    return null;
+  }
+  const reason = (parsed as Record<string, unknown>)["reason"];
+  if (reason === "slow") {
+    return "reset:slow";
+  }
+  if (reason === "shutdown") {
+    return "reset:shutdown";
+  }
+  return null;
+}