@statewalker/webrun-http-events 0.1.0

package/src/handler.test.ts

@@ -0,0 +1,191 @@
+import { describe, expect, it, vi } from "vitest";
+import { newBroker } from "./broker.js";
+import { createSseSource, newPubSub } from "./handler.js";
+
+/** Read exactly `count` SSE frames off a response body, then release it. */
+async function readFrames(res: Response, count: number): Promise<string[]> {
+  const reader = (res.body as ReadableStream<Uint8Array>).getReader();
+  const decoder = new TextDecoder();
+  const frames: string[] = [];
+  let buffer = "";
+  while (frames.length < count) {
+    const { value, done } = await reader.read();
+    if (done) break;
+    buffer += decoder.decode(value, { stream: true });
+    for (let i = buffer.indexOf("\n\n"); i !== -1; i = buffer.indexOf("\n\n")) {
+      frames.push(buffer.slice(0, i + 2));
+      buffer = buffer.slice(i + 2);
+    }
+  }
+  await reader.cancel();
+  return frames;
+}
+
+describe("newPubSub handler", () => {
+  it("answers with an event-stream content type", async () => {
+    const ps = newPubSub();
+    const res = await ps.handler(new Request("http://h/_events/build"));
+    expect(res.status).toBe(200);
+    expect(res.headers.get("content-type")).toBe("text/event-stream");
+    expect(res.headers.get("cache-control")).toBe("no-cache");
+    await res.body?.cancel();
+  });
+
+  it("streams events published after the subscription opens", async () => {
+    const ps = newPubSub();
+    const res = await ps.handler(new Request("http://h/_events/build"));
+    const frames = readFrames(res, 2);
+    ps.publish("build", { changed: ["/a.html"] }, "rebuilt");
+    ps.publish("build", { changed: ["/b.html"] }, "rebuilt");
+    expect(await frames).toEqual([
+      'id: 1\nevent: rebuilt\ndata: {"changed":["/a.html"]}\n\n',
+      'id: 2\nevent: rebuilt\ndata: {"changed":["/b.html"]}\n\n',
+    ]);
+  });
+
+  it("replays missed events when Last-Event-ID is supplied", async () => {
+    const ps = newPubSub();
+    ps.publish("build", "one");
+    ps.publish("build", "two");
+    const res = await ps.handler(
+      new Request("http://h/_events/build", { headers: { "last-event-id": "1" } }),
+    );
+    const frames = await readFrames(res, 1);
+    expect(frames[0]).toBe('id: 2\ndata: "two"\n\n');
+  });
+
+  // (4) a gap the buffer cannot cover must be signalled, not silently partial
+  it("signals a gap when Last-Event-ID predates the replay buffer", async () => {
+    const ps = newPubSub({ bufferSize: 2 });
+    for (const d of ["a", "b", "c", "d"]) ps.publish("build", d);
+    const res = await ps.handler(
+      new Request("http://h/_events/build", { headers: { "last-event-id": "1" } }),
+    );
+    const frames = await readFrames(res, 1);
+    expect(frames[0]).toContain("event: gap");
+  });
+
+  it("releases the subscriber when the client cancels the body", async () => {
+    const ps = newPubSub();
+    const res = await ps.handler(new Request("http://h/_events/build"));
+    await readFrames(res, 0); // opens and cancels the reader
+    expect(ps.subscriberCount("build")).toBe(0);
+  });
+});
+
+describe("newPubSub handler — hostile input", () => {
+  // C-1: `publish("build", undefined, "reload")` — a payload-free signal — used to
+  // throw out of publish(), and then out of ps.handler() for every reconnecting
+  // client that hit the event in the replay ring.
+  it("survives a payload that cannot be serialized, live and on replay", async () => {
+    const ps = newPubSub();
+    const res = await ps.handler(new Request("http://h/_events/build"));
+    const frames = readFrames(res, 1);
+
+    expect(() => ps.publish("build", undefined, "reload")).not.toThrow();
+    expect(await frames).toEqual(["id: 1\nevent: reload\ndata: null\n\n"]);
+
+    const again = await ps.handler(
+      new Request("http://h/_events/build", { headers: { "last-event-id": "0" } }),
+    );
+    expect((await readFrames(again, 1))[0]).toBe("id: 1\nevent: reload\ndata: null\n\n");
+  });
+
+  // C-2, through the handler: a Last-Event-ID from a previous server epoch.
+  it("signals a gap when Last-Event-ID is above anything this server has issued", async () => {
+    const ps = newPubSub();
+    ps.publish("build", "a");
+    const res = await ps.handler(
+      new Request("http://h/_events/build", { headers: { "last-event-id": "42" } }),
+    );
+    expect((await readFrames(res, 1))[0]).toContain("event: gap");
+  });
+
+  // m-12: an unparseable id used to skip the replay block entirely — no replay and
+  // no gap, so a client whose id was mangled was told nothing at all.
+  it("signals a gap when Last-Event-ID cannot be parsed", async () => {
+    const ps = newPubSub();
+    ps.publish("build", "a");
+    const res = await ps.handler(
+      new Request("http://h/_events/build", { headers: { "last-event-id": "abc" } }),
+    );
+    expect((await readFrames(res, 1))[0]).toContain("event: gap");
+  });
+
+  it("rejects a non-GET request", async () => {
+    const ps = newPubSub();
+    const res = await ps.handler(new Request("http://h/_events/build", { method: "POST" }));
+    expect(res.status).toBe(405);
+    expect(res.headers.get("allow")).toBe("GET");
+    expect(ps.topicCount()).toBe(0);
+  });
+
+  it("rejects a request with no topic", async () => {
+    const ps = newPubSub();
+    expect((await ps.handler(new Request("http://h/"))).status).toBe(404);
+    expect(ps.topicCount()).toBe(0);
+  });
+
+  it("serves only the allow-listed topics when one is configured", async () => {
+    const ps = newPubSub({ topics: ["build"] });
+    expect((await ps.handler(new Request("http://h/_events/evil"))).status).toBe(404);
+    expect(ps.topicCount()).toBe(0);
+    const ok = await ps.handler(new Request("http://h/_events/build"));
+    expect(ok.status).toBe(200);
+    await ok.body?.cancel();
+  });
+
+  // I-6: any GET /_events/<random> allocated a topic that was never reclaimed.
+  it("drops topic state once the last subscriber leaves and nothing is retained", async () => {
+    const ps = newPubSub();
+    const res = await ps.handler(new Request("http://h/_events/ghost"));
+    expect(ps.topicCount()).toBe(1);
+    await res.body?.cancel();
+    expect(ps.subscriberCount("ghost")).toBe(0);
+    expect(ps.topicCount()).toBe(0);
+  });
+});
+
+describe("newPubSub handler — a stream that breaks", () => {
+  // m-13: `unsubscribe` was assigned only after the replay loop, so send's catch
+  // called it on undefined and then subscribed anyway; the catch also never closed
+  // the controller, leaving a dead stream open to swallow every later event.
+  it("releases the subscriber and closes the stream when the first send fails", () => {
+    const broker = newBroker();
+    broker.publish("build", "a");
+    const source = createSseSource(broker, "build", { replayFrom: 0 });
+
+    let closed = false;
+    const controller = {
+      enqueue() {
+        throw new TypeError("the client went away");
+      },
+      close() {
+        closed = true;
+      },
+      error() {},
+    } as unknown as ReadableStreamDefaultController<Uint8Array>;
+
+    source.start?.(controller);
+
+    expect(broker.subscriberCount("build")).toBe(0);
+    expect(closed).toBe(true);
+  });
+
+  // m-14: opt-in keepalive. Comment frames are ignored by the SSE parser but keep a
+  // half-open connection observable to proxies.
+  it("emits comment frames when a heartbeat interval is configured", async () => {
+    vi.useFakeTimers();
+    try {
+      const ps = newPubSub({ heartbeatMs: 1000 });
+      const res = await ps.handler(new Request("http://h/_events/build"));
+      const reader = (res.body as ReadableStream<Uint8Array>).getReader();
+      vi.advanceTimersByTime(2500);
+      expect(new TextDecoder().decode((await reader.read()).value)).toBe(": ping\n\n");
+      await reader.cancel();
+      expect(ps.subscriberCount("build")).toBe(0);
+    } finally {
+      vi.useRealTimers();
+    }
+  });
+});

package/src/handler.ts

@@ -0,0 +1,166 @@
+import { type Broker, type BrokerOptions, newBroker, type Unsubscribe } from "./broker.js";
+import { formatSseEvent } from "./sse.js";
+
+export type FetchHandler = (request: Request) => Promise<Response>;
+
+export interface PubSubOptions extends BrokerOptions {
+  /**
+   * When given, only these topic names are served; anything else answers 404.
+   * Without it any request path allocates a topic, so an open endpoint should
+   * set this.
+   */
+  topics?: readonly string[];
+  /**
+   * Interval in ms for `: ping` comment frames, which the SSE parser ignores but
+   * which keep a half-open connection visible to proxies. 0 (the default) means
+   * no heartbeat: a connection that dies silently is then only noticed when the
+   * client's own reconnect timer fires.
+   */
+  heartbeatMs?: number;
+}
+
+export interface PubSub {
+  handler: FetchHandler;
+  publish(topic: string, data: unknown, event?: string): void;
+  subscriberCount(topic: string): number;
+  /** How many topics currently hold state; a topic with no subscribers and no retained events is dropped. */
+  topicCount(): number;
+}
+
+/** The topic is the final non-empty path segment: /_events/build -> "build". */
+function topicOf(request: Request): string {
+  const segments = new URL(request.url).pathname.split("/").filter(Boolean);
+  return segments.at(-1) ?? "";
+}
+
+export interface SseSourceOptions {
+  /** Replay events after this id; undefined for a fresh subscription. */
+  replayFrom?: number;
+  /** Send a `gap` before anything else — the client's Last-Event-ID was unusable. */
+  forceGap?: boolean;
+  /** See {@link PubSubOptions.heartbeatMs}. */
+  heartbeatMs?: number;
+}
+
+/**
+ * The `ReadableStream` source behind one subscription.
+ *
+ * Exported so tests can drive it with a controller whose `enqueue` fails, which
+ * is the one path a real stream cannot be pushed down from outside.
+ */
+export function createSseSource(
+  broker: Broker,
+  topic: string,
+  { replayFrom, forceGap = false, heartbeatMs = 0 }: SseSourceOptions = {},
+): UnderlyingSource<Uint8Array> {
+  const encoder = new TextEncoder();
+  let unsubscribe: Unsubscribe | undefined;
+  let heartbeat: ReturnType<typeof setInterval> | undefined;
+  let broken = false;
+
+  return {
+    start(controller) {
+      /** Tear the subscription down and end the stream, once. */
+      const stop = () => {
+        if (broken) return;
+        broken = true;
+        if (heartbeat !== undefined) clearInterval(heartbeat);
+        unsubscribe?.();
+        unsubscribe = undefined;
+        try {
+          controller.close();
+        } catch {
+          // Already closed or errored; nothing left to do.
+        }
+      };
+
+      const write = (frame: () => string) => {
+        if (broken) return;
+        try {
+          // Formatting happens inside the guard: it is given caller data, and a
+          // throw here used to escape this catch entirely.
+          controller.enqueue(encoder.encode(frame()));
+        } catch {
+          // The client went away, or the frame could not be produced.
+          stop();
+        }
+      };
+
+      // Subscribe first, so the teardown above can release it even if the very
+      // first replay frame fails.
+      unsubscribe = broker.subscribe(topic, (e) => write(() => formatSseEvent(e)));
+
+      if (forceGap || replayFrom !== undefined) {
+        const from = replayFrom ?? 0;
+        const { events, complete } =
+          replayFrom === undefined
+            ? { events: [], complete: false }
+            : broker.replay(topic, replayFrom);
+        // Tell the client its history is incomplete rather than handing it a
+        // partial replay that looks whole; it can reload instead of patching.
+        if (!complete) write(() => formatSseEvent({ id: from, event: "gap", data: { from } }));
+        for (const e of events) write(() => formatSseEvent(e));
+      }
+
+      if (heartbeatMs > 0) {
+        heartbeat = setInterval(() => write(() => ": ping\n\n"), heartbeatMs);
+      }
+    },
+
+    cancel() {
+      if (heartbeat !== undefined) clearInterval(heartbeat);
+      broken = true;
+      unsubscribe?.();
+      unsubscribe = undefined;
+    },
+  };
+}
+
+export function newPubSub(options: PubSubOptions = {}): PubSub {
+  const { topics, heartbeatMs, ...brokerOptions } = options;
+  const broker = newBroker(brokerOptions);
+  const allowed = topics === undefined ? undefined : new Set(topics);
+
+  const handler: FetchHandler = async (request) => {
+    if (request.method !== "GET") {
+      return new Response("method not allowed", { status: 405, headers: { allow: "GET" } });
+    }
+
+    const topic = topicOf(request);
+    if (topic === "" || (allowed !== undefined && !allowed.has(topic))) {
+      return new Response("no such topic", { status: 404 });
+    }
+
+    const header = request.headers.get("last-event-id");
+    const parsed = header === null ? Number.NaN : Number(header);
+    const usable = header !== null && Number.isSafeInteger(parsed) && parsed >= 0;
+    // An id we cannot read is not a fresh client: it had history and lost it, so
+    // it gets a gap rather than silence.
+    const forceGap = header !== null && !usable;
+
+    const stream = new ReadableStream<Uint8Array>(
+      createSseSource(broker, topic, {
+        ...(usable ? { replayFrom: parsed } : {}),
+        forceGap,
+        ...(heartbeatMs === undefined ? {} : { heartbeatMs }),
+      }),
+    );
+
+    return new Response(stream, {
+      status: 200,
+      headers: {
+        "content-type": "text/event-stream",
+        "cache-control": "no-cache",
+        connection: "keep-alive",
+        "x-accel-buffering": "no", // defeat proxy buffering that would stall delivery
+      },
+    });
+  };
+
+  return {
+    handler,
+    publish: (topic, data, event) => void broker.publish(topic, data, event),
+    subscriberCount: (topic) => broker.subscriberCount(topic),
+    topicCount: () => broker.topicCount(),
+  };
+}

package/src/index.ts

@@ -0,0 +1,7 @@
+export type { Broker, BrokerEvent, BrokerOptions, Subscriber, Unsubscribe } from "./broker.js";
+export { newBroker } from "./broker.js";
+export type { PubSubClient, PubSubClientOptions, SubscribeOptions } from "./client.js";
+export { newPubSubClient } from "./client.js";
+export type { FetchHandler, PubSub, PubSubOptions } from "./handler.js";
+export { newPubSub } from "./handler.js";
+export { formatSseEvent } from "./sse.js";

package/src/sse.test.ts

@@ -0,0 +1,56 @@
+import { describe, expect, it } from "vitest";
+import { formatSseEvent } from "./sse.js";
+
+describe("formatSseEvent", () => {
+  it("frames id, event name and data", () => {
+    expect(formatSseEvent({ id: 7, event: "rebuilt", data: { a: 1 } })).toBe(
+      'id: 7\nevent: rebuilt\ndata: {"a":1}\n\n',
+    );
+  });
+
+  it("omits the event line when no name is given", () => {
+    expect(formatSseEvent({ id: 1, data: 5 })).toBe("id: 1\ndata: 5\n\n");
+  });
+
+  // (3) an unframed newline terminates the event early and truncates the payload
+  it("emits one data line per newline in the payload", () => {
+    const frame = formatSseEvent({ id: 2, data: "line one\nline two" });
+    expect(frame).toBe('id: 2\ndata: "line one\\nline two"\n\n');
+  });
+
+  it("splits a multi-line serialized payload across data lines", () => {
+    const frame = formatSseEvent({ id: 3, data: { raw: "a\nb" }, event: "e" });
+    // JSON.stringify escapes the newline, so exactly one data line results
+    expect(frame.split("\n").filter((l) => l.startsWith("data:"))).toHaveLength(1);
+    expect(frame.endsWith("\n\n")).toBe(true);
+  });
+});
+
+describe("formatSseEvent — total on any input", () => {
+  // C-1: JSON.stringify returns undefined (not a string) for these, so `.split` threw
+  // and the throw escaped every guard in the handler and the broker.
+  it("frames a payload JSON cannot represent as null instead of throwing", () => {
+    const circular: Record<string, unknown> = {};
+    circular.self = circular;
+    expect(formatSseEvent({ id: 1, event: "reload", data: undefined })).toBe(
+      "id: 1\nevent: reload\ndata: null\n\n",
+    );
+    expect(formatSseEvent({ id: 2, data: () => {} })).toBe("id: 2\ndata: null\n\n");
+    expect(formatSseEvent({ id: 3, data: Symbol("s") })).toBe("id: 3\ndata: null\n\n");
+    expect(formatSseEvent({ id: 4, data: 1n })).toBe("id: 4\ndata: null\n\n");
+    expect(formatSseEvent({ id: 5, data: circular })).toBe("id: 5\ndata: null\n\n");
+  });
+
+  // m-10: a newline in the event name used to inject whole frames onto the wire.
+  it("cannot be made to inject a frame through the event name", () => {
+    const frame = formatSseEvent({ id: 1, event: "a\ndata: injected\r\nevent: x", data: 0 });
+    expect(frame.split("\n").filter((l) => l.startsWith("data:"))).toEqual(["data: 0"]);
+    expect(frame).toBe("id: 1\nevent: adata: injectedevent: x\ndata: 0\n\n");
+  });
+
+  // m-9: the doc comment used to promise special handling for a pre-serialized
+  // string; it never happened. A string is JSON-encoded like anything else.
+  it("JSON-encodes a string payload like any other value", () => {
+    expect(formatSseEvent({ id: 1, data: "hi" })).toBe('id: 1\ndata: "hi"\n\n');
+  });
+});

package/src/sse.ts

@@ -0,0 +1,36 @@
+import type { BrokerEvent } from "./broker.js";
+
+/**
+ * JSON for the wire. Total by construction: `JSON.stringify` returns `undefined`
+ * rather than a string for `undefined`, a function or a symbol, and throws on a
+ * BigInt or a circular object. Any of those is framed as `null` — the event still
+ * reaches the client with its id and name, which is what an empty signal is for.
+ */
+function serialize(data: unknown): string {
+  try {
+    return JSON.stringify(data) ?? "null";
+  } catch {
+    return "null";
+  }
+}
+
+/**
+ * Format one WHATWG Server-Sent Event frame, terminated by the blank line that
+ * ends an event.
+ *
+ * `data` is always JSON-serialized, strings included (a string payload arrives
+ * back through `JSON.parse` as the same string, never half-decoded). JSON escapes
+ * newlines, so the body is a single line in practice; every line is prefixed
+ * anyway, because an unframed newline would end the event and truncate it.
+ *
+ * CR and LF are stripped from the event name: it is caller-supplied, and a
+ * newline there would inject whole frames onto the wire.
+ */
+export function formatSseEvent(e: BrokerEvent): string {
+  const lines = serialize(e.data)
+    .split("\n")
+    .map((l) => `data: ${l}\n`)
+    .join("");
+  const name = e.event === undefined ? "" : `event: ${e.event.replace(/[\r\n]/g, "")}\n`;
+  return `id: ${e.id}\n${name}${lines}\n`;
+}