@statewalker/webrun-http-events 0.1.0

package/src/broker.test.ts

@@ -0,0 +1,192 @@
+import { describe, expect, it } from "vitest";
+import type { BrokerEvent } from "./broker.js";
+import { newBroker } from "./broker.js";
+
+describe("newBroker", () => {
+  it("delivers a published event to a subscriber on the same topic", () => {
+    const broker = newBroker();
+    const seen: unknown[] = [];
+    broker.subscribe("build", (e) => seen.push(e.data));
+    broker.publish("build", { changed: ["/a.html"] });
+    expect(seen).toEqual([{ changed: ["/a.html"] }]);
+  });
+
+  it("does not deliver across topics", () => {
+    const broker = newBroker();
+    const seen: unknown[] = [];
+    broker.subscribe("build", (e) => seen.push(e.data));
+    broker.publish("other", { changed: [] });
+    expect(seen).toEqual([]);
+  });
+
+  it("assigns monotonically increasing ids per topic", () => {
+    const broker = newBroker();
+    const a = broker.publish("t", 1);
+    const b = broker.publish("t", 2);
+    expect(b.id).toBeGreaterThan(a.id);
+  });
+
+  // (2) a publish with no subscribers must not throw and must still advance the id
+  it("advances the id when nobody is listening", () => {
+    const broker = newBroker();
+    const first = broker.publish("quiet", "a");
+    const second = broker.publish("quiet", "b");
+    expect(second.id).toBe(first.id + 1);
+    const { events } = broker.replay("quiet", first.id);
+    expect(events.map((e) => e.data)).toEqual(["b"]);
+  });
+});
+
+describe("newBroker — concurrency and lifecycle", () => {
+  // (5) S2 proved exactly one subscriber; a single-callback broker passes every such test
+  it("delivers to every subscriber on a topic", () => {
+    const broker = newBroker();
+    const a: unknown[] = [];
+    const b: unknown[] = [];
+    broker.subscribe("t", (e) => a.push(e.data));
+    broker.subscribe("t", (e) => b.push(e.data));
+    broker.publish("t", "x");
+    expect(a).toEqual(["x"]);
+    expect(b).toEqual(["x"]);
+    expect(broker.subscriberCount("t")).toBe(2);
+  });
+
+  // (1) a disconnecting subscriber must be dropped, or a long-lived server leaks
+  it("releases one subscriber's slot without disturbing the other", () => {
+    const broker = newBroker();
+    const a: unknown[] = [];
+    const b: unknown[] = [];
+    const offA = broker.subscribe("t", (e) => a.push(e.data));
+    broker.subscribe("t", (e) => b.push(e.data));
+    expect(broker.subscriberCount("t")).toBe(2);
+
+    broker.publish("t", "before");
+    offA();
+    broker.publish("t", "after");
+
+    expect(a).toEqual(["before"]);
+    expect(b).toEqual(["before", "after"]);
+    expect(broker.subscriberCount("t")).toBe(1);
+  });
+
+  it("tolerates a subscriber unsubscribing during delivery", () => {
+    const broker = newBroker();
+    const seen: unknown[] = [];
+    const off = broker.subscribe("t", () => off());
+    broker.subscribe("t", (e) => seen.push(e.data));
+    expect(broker.subscriberCount("t")).toBe(2);
+
+    expect(() => broker.publish("t", "x")).not.toThrow();
+
+    expect(seen).toEqual(["x"]);
+    expect(broker.subscriberCount("t")).toBe(1); // the self-unsubscriber removed itself
+  });
+
+  // Pins the `[...s.subscribers]` copy in publish(). Self-unsubscribe is safe in
+  // every engine, so it proves nothing; only removing a NOT-YET-VISITED entry does.
+  it("delivers to a not-yet-visited subscriber even if an earlier callback unsubscribes it", () => {
+    const broker = newBroker();
+    const seenC: unknown[] = [];
+    let offC!: () => void;
+    broker.subscribe("t", () => offC()); // A: runs first, unsubscribes C
+    broker.subscribe("t", () => {}); // B: filler, keeps C unvisited when A runs
+    offC = broker.subscribe("t", (e) => seenC.push(e.data)); // C
+    broker.publish("t", "x");
+    expect(seenC).toEqual(["x"]); // only true because publish snapshots up front
+  });
+});
+
+describe("newBroker — a failing subscriber", () => {
+  // C-1: a bare `for … fn(e)` lets the first throwing subscriber abort delivery to
+  // everyone after it and propagate the throw out of publish().
+  it("isolates a throwing subscriber from the others and from the publisher", () => {
+    const errors: unknown[] = [];
+    const broker = newBroker({ onSubscriberError: (err) => errors.push(err) });
+    const seen: unknown[] = [];
+    broker.subscribe("t", () => {
+      throw new Error("boom");
+    });
+    broker.subscribe("t", (e) => seen.push(e.data));
+
+    expect(() => broker.publish("t", "x")).not.toThrow();
+
+    expect(seen).toEqual(["x"]); // the second subscriber was not starved
+    expect(errors).toHaveLength(1);
+  });
+});
+
+describe("newBroker — replay completeness", () => {
+  // C-2: the ceiling. A client whose id came from a previous server epoch asks for
+  // events above the newest id ever issued; reporting `complete` there tells a stale
+  // page it is current, and onGap never fires.
+  it("reports an incomplete history when afterId is above the newest id", () => {
+    const broker = newBroker();
+    broker.publish("t", "a");
+    broker.publish("t", "b");
+    expect(broker.replay("t", 42)).toEqual({ events: [], complete: false });
+  });
+
+  it("treats an unknown topic as complete only for a client with no history", () => {
+    const broker = newBroker();
+    expect(broker.replay("absent", 0)).toEqual({ events: [], complete: true });
+    expect(broker.replay("absent", 7)).toEqual({ events: [], complete: false });
+  });
+
+  // m-8: with an empty ring every replay used to report complete, disabling the contract.
+  it("retains nothing with bufferSize 0, so only a level client is complete", () => {
+    const broker = newBroker({ bufferSize: 0 });
+    broker.publish("t", "a");
+    broker.publish("t", "b");
+    expect(broker.replay("t", 0).complete).toBe(false);
+    expect(broker.replay("t", 1).complete).toBe(false);
+    expect(broker.replay("t", 2)).toEqual({ events: [], complete: true });
+    expect(broker.replay("t", 3).complete).toBe(false);
+  });
+
+  it("is complete at the first retained event and incomplete one event earlier", () => {
+    const broker = newBroker({ bufferSize: 2 });
+    for (const d of ["a", "b", "c"]) broker.publish("t", d); // ids 1..3; the ring holds 2,3
+    const at = broker.replay("t", 1);
+    expect(at.complete).toBe(true);
+    expect(at.events.map((e) => e.data)).toEqual(["b", "c"]);
+    expect(broker.replay("t", 0).complete).toBe(false); // id 1 was evicted
+  });
+});
+
+describe("newBroker — subscribe's shape", () => {
+  // I-3: the lastEventId parameter discarded `complete` (the C-2 miss, on the public
+  // interface) and reached replay through `this`, so a destructured subscribe threw.
+  it("takes exactly two arguments, never replays, and does not depend on `this`", () => {
+    const { subscribe, publish, subscriberCount } = newBroker();
+    publish("t", "before");
+
+    const seen: unknown[] = [];
+    const loose = subscribe as unknown as (...args: unknown[]) => () => void;
+    const off = loose("t", (e: BrokerEvent) => seen.push(e.data), 0);
+
+    expect(seen).toEqual([]); // no replay on subscribe: callers use replay() and read `complete`
+    expect(subscribe.length).toBe(2);
+    publish("t", "after");
+    expect(seen).toEqual(["after"]);
+    off();
+    expect(subscriberCount("t")).toBe(0);
+  });
+
+  // I-6: an entry created by a touch that left nothing behind must not outlive it.
+  it("drops a topic once it has no subscribers and nothing retained", () => {
+    const broker = newBroker();
+    const off = broker.subscribe("ghost", () => {});
+    expect(broker.topicCount()).toBe(1);
+    off();
+    expect(broker.topicCount()).toBe(0);
+  });
+
+  it("keeps a topic that still has retained events", () => {
+    const broker = newBroker();
+    const off = broker.subscribe("t", () => {});
+    broker.publish("t", "a");
+    off();
+    expect(broker.topicCount()).toBe(1);
+    expect(broker.replay("t", 0).events.map((e) => e.data)).toEqual(["a"]);
+  });
+});

package/src/broker.ts

@@ -0,0 +1,121 @@
+export type BrokerEvent = { id: number; event?: string; data: unknown };
+export type Subscriber = (e: BrokerEvent) => void;
+export type Unsubscribe = () => void;
+
+export interface Broker {
+  /**
+   * Deliver `data` to every subscriber of `topic` and retain it for replay.
+   *
+   * Delivery is synchronous and each subscriber is isolated: one that throws is
+   * reported to `onSubscriberError` and cannot starve the others or the caller.
+   *
+   * Publishing from inside a subscriber (a reentrant publish) is NOT supported:
+   * the inner event is delivered to completion before the outer one finishes, so
+   * subscribers observe ids out of order and a client's Last-Event-ID can move
+   * backwards. Publish from a fresh task instead.
+   */
+  publish(topic: string, data: unknown, event?: string): BrokerEvent;
+  /** Register `fn` for future events on `topic`. Use {@link Broker.replay} for history. */
+  subscribe(topic: string, fn: Subscriber): Unsubscribe;
+  /**
+   * Events retained after `afterId`, plus whether that is the whole story.
+   * `complete: false` means the caller's history cannot be reconstructed — either
+   * the events it wants were evicted, or its `afterId` is above anything this
+   * broker has issued (a client left over from a previous process).
+   */
+  replay(topic: string, afterId: number): { events: BrokerEvent[]; complete: boolean };
+  subscriberCount(topic: string): number;
+  /** How many topics currently hold state. Topics with no subscribers and no retained events are dropped. */
+  topicCount(): number;
+}
+
+export interface BrokerOptions {
+  /** How many recent events to retain per topic for Last-Event-ID replay. */
+  bufferSize?: number;
+  /**
+   * Called when a subscriber throws. Delivery continues either way; without this
+   * the failure would be invisible.
+   */
+  onSubscriberError?: (error: unknown, e: BrokerEvent) => void;
+}
+
+type TopicState = {
+  nextId: number;
+  /** Bounded ring of recent events, oldest first. */
+  buffer: BrokerEvent[];
+  subscribers: Set<Subscriber>;
+};
+
+export function newBroker({ bufferSize = 64, onSubscriberError }: BrokerOptions = {}): Broker {
+  const topics = new Map<string, TopicState>();
+
+  const state = (topic: string): TopicState => {
+    let s = topics.get(topic);
+    if (!s) {
+      s = { nextId: 1, buffer: [], subscribers: new Set() };
+      topics.set(topic, s);
+    }
+    return s;
+  };
+
+  /** Drop a topic that holds nothing, so request-driven names cannot accumulate. */
+  const prune = (topic: string, s: TopicState): void => {
+    if (topics.get(topic) === s && s.subscribers.size === 0 && s.buffer.length === 0) {
+      topics.delete(topic);
+    }
+  };
+
+  const replay: Broker["replay"] = (topic, afterId) => {
+    const s = topics.get(topic);
+    // An absent topic has issued nothing: only a caller with no history is current.
+    if (!s) return { events: [], complete: afterId <= 0 };
+    const events = s.buffer.filter((e) => e.id > afterId);
+    const latest = s.nextId - 1;
+    // An empty ring retains nothing, so nothing before `nextId` can be reconstructed.
+    const oldest = s.buffer[0]?.id ?? s.nextId;
+    // Incomplete below, when the requested point predates the oldest retained event,
+    // and above, when it names an id this broker never issued.
+    return { events, complete: afterId >= oldest - 1 && afterId <= latest };
+  };
+
+  return {
+    publish(topic, data, event) {
+      const s = state(topic);
+      const e: BrokerEvent = { id: s.nextId++, data, ...(event === undefined ? {} : { event }) };
+      s.buffer.push(e);
+      if (s.buffer.length > bufferSize) s.buffer.shift();
+      // Copy before iterating: a subscriber may unsubscribe during delivery.
+      for (const fn of [...s.subscribers]) {
+        try {
+          fn(e);
+        } catch (error) {
+          try {
+            onSubscriberError?.(error, e);
+          } catch {
+            // A reporter that throws must not starve the remaining subscribers either.
+          }
+        }
+      }
+      return e;
+    },
+
+    subscribe(topic, fn) {
+      const s = state(topic);
+      s.subscribers.add(fn);
+      return () => {
+        s.subscribers.delete(fn);
+        prune(topic, s);
+      };
+    },
+
+    replay,
+
+    subscriberCount(topic) {
+      return topics.get(topic)?.subscribers.size ?? 0;
+    },
+
+    topicCount() {
+      return topics.size;
+    },
+  };
+}

package/src/client.test.ts

@@ -0,0 +1,216 @@
+import { describe, expect, it, vi } from "vitest";
+import { newPubSubClient } from "./client.js";
+
+/** Minimal EventSource stand-in; vitest runs under Node, which has no DOM one. */
+class FakeEventSource {
+  static instances: FakeEventSource[] = [];
+  listeners = new Map<string, Set<(e: MessageEvent) => void>>();
+  closed = false;
+  constructor(public url: string) {
+    FakeEventSource.instances.push(this);
+  }
+  addEventListener(type: string, fn: (e: MessageEvent) => void) {
+    let s = this.listeners.get(type);
+    if (!s) {
+      s = new Set();
+      this.listeners.set(type, s);
+    }
+    s.add(fn);
+  }
+  removeEventListener(type: string, fn: (e: MessageEvent) => void) {
+    this.listeners.get(type)?.delete(fn);
+  }
+  close() {
+    this.closed = true;
+  }
+  emit(type: string, data: string, lastEventId = "1") {
+    for (const fn of this.listeners.get(type) ?? []) {
+      fn({ type, data, lastEventId } as MessageEvent);
+    }
+  }
+  /** A bare Event, as `error` and `open` are dispatched. */
+  emitBare(type: string) {
+    for (const fn of this.listeners.get(type) ?? []) {
+      fn({ type } as MessageEvent);
+    }
+  }
+  listenerTypes() {
+    return [...this.listeners]
+      .filter(([, fns]) => fns.size > 0)
+      .map(([type]) => type)
+      .sort();
+  }
+}
+
+describe("newPubSubClient", () => {
+  it("opens one EventSource per topic at the right URL", () => {
+    FakeEventSource.instances.length = 0;
+    const client = newPubSubClient("http://h/_events", {
+      EventSourceImpl: FakeEventSource as unknown as typeof EventSource,
+    });
+    client.subscribe("build", () => {});
+    expect(FakeEventSource.instances).toHaveLength(1);
+    expect(FakeEventSource.instances[0]!.url).toBe("http://h/_events/build");
+  });
+
+  it("parses the JSON payload and reports the event id", () => {
+    FakeEventSource.instances.length = 0;
+    const client = newPubSubClient("http://h/_events", {
+      EventSourceImpl: FakeEventSource as unknown as typeof EventSource,
+    });
+    const seen: Array<[unknown, number]> = [];
+    client.subscribe("build", (data, e) => seen.push([data, e.id]));
+    FakeEventSource.instances[0]!.emit("message", '{"changed":["/a.html"]}', "4");
+    expect(seen).toEqual([[{ changed: ["/a.html"] }, 4]]);
+  });
+
+  it("closes the EventSource on unsubscribe", () => {
+    FakeEventSource.instances.length = 0;
+    const client = newPubSubClient("http://h/_events", {
+      EventSourceImpl: FakeEventSource as unknown as typeof EventSource,
+    });
+    const off = client.subscribe("build", () => {});
+    off();
+    expect(FakeEventSource.instances[0]!.closed).toBe(true);
+  });
+
+  // (4) the client half of the gap contract
+  it("routes a gap event to onGap and not to the subscriber", () => {
+    FakeEventSource.instances.length = 0;
+    const onGap = vi.fn();
+    const client = newPubSubClient("http://h/_events", {
+      EventSourceImpl: FakeEventSource as unknown as typeof EventSource,
+      onGap,
+    });
+    const seen: unknown[] = [];
+    client.subscribe("build", (d) => seen.push(d));
+    FakeEventSource.instances[0]!.emit("gap", '{"from":1}');
+    expect(onGap).toHaveBeenCalledWith("build");
+    expect(seen).toEqual([]);
+  });
+});
+
+describe("newPubSubClient — event names", () => {
+  const newClient = (options: Record<string, unknown> = {}) => {
+    FakeEventSource.instances.length = 0;
+    return newPubSubClient("http://h/_events", {
+      EventSourceImpl: FakeEventSource as unknown as typeof EventSource,
+      ...options,
+    });
+  };
+
+  // I-4: per the SSE spec a frame with `event: X` dispatches only as type X, so the
+  // three hardcoded listeners silently dropped every other name — and one of them
+  // was "rebuilt", notebook vocabulary in a generic package.
+  it("listens for `message` and nothing else by default", () => {
+    const client = newClient();
+    client.subscribe("build", () => {});
+    expect(FakeEventSource.instances[0]!.listenerTypes()).toEqual([
+      "error",
+      "gap",
+      "message",
+      "open",
+    ]);
+  });
+
+  it("delivers an arbitrary named event to a subscriber that asked for it", () => {
+    const client = newClient();
+    const seen: Array<[unknown, string | undefined]> = [];
+    client.subscribe("build", (d, e) => seen.push([d, e.event]), { events: ["cell-done"] });
+    FakeEventSource.instances[0]!.emit("cell-done", '{"cell":3}', "9");
+    expect(seen).toEqual([[{ cell: 3 }, "cell-done"]]);
+  });
+
+  it("takes a default event-name set for every subscription on the client", () => {
+    const client = newClient({ events: ["message", "rebuilt"] });
+    const seen: unknown[] = [];
+    client.subscribe("build", (d) => seen.push(d));
+    FakeEventSource.instances[0]!.emit("rebuilt", '{"n":1}');
+    FakeEventSource.instances[0]!.emit("message", '{"n":2}');
+    expect(seen).toEqual([{ n: 1 }, { n: 2 }]);
+  });
+
+  it("removes every listener it added on unsubscribe", () => {
+    const client = newClient();
+    const off = client.subscribe("build", () => {}, { events: ["message", "cell-done"] });
+    off();
+    expect(FakeEventSource.instances[0]!.listenerTypes()).toEqual([]);
+  });
+});
+
+describe("newPubSubClient — a dead subscription", () => {
+  // I-5: a real EventSource that gets a non-2xx or a wrong content-type closes for
+  // good. With no error listener the page looked healthy and never updated again.
+  it("reports a stream error through onError", () => {
+    FakeEventSource.instances.length = 0;
+    const onError = vi.fn();
+    const onOpen = vi.fn();
+    const client = newPubSubClient("http://h/_events", {
+      EventSourceImpl: FakeEventSource as unknown as typeof EventSource,
+      onError,
+      onOpen,
+    });
+    client.subscribe("build", () => {});
+    FakeEventSource.instances[0]!.emitBare("open");
+    FakeEventSource.instances[0]!.emitBare("error");
+    expect(onOpen).toHaveBeenCalledWith("build");
+    expect(onError).toHaveBeenCalledWith("build", expect.objectContaining({ type: "error" }));
+  });
+});
+
+describe("newPubSubClient — reserved control names", () => {
+  // `gap`, `error` and `open` are the client's own control channels. Asking for one
+  // as a data event handed the gap frame to the data callback — re-opening the one
+  // invariant this package exists to protect, since a caller that mistakes a gap for
+  // a payload patches forward from a false baseline believing its history complete —
+  // and made a real transport error throw SyntaxError from JSON.parse(undefined).
+  const reserved = ["gap", "error", "open"];
+
+  it("refuses a reserved name in a subscription's event set, before opening anything", () => {
+    FakeEventSource.instances.length = 0;
+    const client = newPubSubClient("http://h/_events", {
+      EventSourceImpl: FakeEventSource as unknown as typeof EventSource,
+    });
+    for (const name of reserved) {
+      expect(() => client.subscribe("build", () => {}, { events: ["message", name] })).toThrow(
+        /reserved/,
+      );
+    }
+    expect(FakeEventSource.instances).toHaveLength(0); // nothing was opened and leaked
+  });
+
+  it("refuses a reserved name in the client-wide default set", () => {
+    for (const name of reserved) {
+      expect(() =>
+        newPubSubClient("http://h/_events", {
+          EventSourceImpl: FakeEventSource as unknown as typeof EventSource,
+          events: [name],
+        }),
+      ).toThrow(/reserved/);
+    }
+  });
+
+  it("keeps a gap off the data callback and a transport error harmless", () => {
+    FakeEventSource.instances.length = 0;
+    const onGap = vi.fn();
+    const onError = vi.fn();
+    const client = newPubSubClient("http://h/_events", {
+      EventSourceImpl: FakeEventSource as unknown as typeof EventSource,
+      onGap,
+      onError,
+    });
+    const seen: unknown[] = [];
+    expect(() =>
+      client.subscribe("build", (d) => seen.push(d), { events: ["gap", "error"] }),
+    ).toThrow(/reserved/);
+
+    client.subscribe("build", (d) => seen.push(d));
+    const source = FakeEventSource.instances[0]!;
+    source.emit("gap", '{"from":1}');
+    expect(() => source.emitBare("error")).not.toThrow();
+
+    expect(seen).toEqual([]); // no control frame ever reached the data callback
+    expect(onGap).toHaveBeenCalledWith("build");
+    expect(onError).toHaveBeenCalled();
+  });
+});

package/src/client.ts

@@ -0,0 +1,133 @@
+import type { Unsubscribe } from "./broker.js";
+
+/** The SSE event type a subscription listens for when nothing else is asked for. */
+const DEFAULT_EVENTS = ["message"] as const;
+
+/**
+ * Names this client owns. They are wired to `onGap`, `onError` and `onOpen`, never
+ * to a data callback: a `gap` delivered as data would have the caller patch forward
+ * from a false baseline believing its history complete, and `error`/`open` carry a
+ * bare `Event` with no `data` to parse.
+ */
+const RESERVED_EVENTS: readonly string[] = ["gap", "error", "open"];
+
+function checkEvents(events: readonly string[], where: string): readonly string[] {
+  for (const name of events) {
+    if (RESERVED_EVENTS.includes(name)) {
+      throw new TypeError(
+        `${where}: "${name}" is a reserved event name — it is delivered to ` +
+          `on${name[0]?.toUpperCase()}${name.slice(1)}, not to a subscriber`,
+      );
+    }
+  }
+  return events;
+}
+
+export interface PubSubClientOptions {
+  /** Injected for tests, and for runtimes with a non-global EventSource. */
+  EventSourceImpl?: typeof EventSource;
+  /**
+   * Default event names for every subscription on this client; `["message"]`
+   * unless given. A frame published with `event: X` is dispatched by the browser
+   * ONLY as type X — it does not also fire `message` — so a name that is not
+   * listed here is received by nobody.
+   *
+   * `gap`, `error` and `open` are RESERVED: they are this client's control
+   * channels, reported through `onGap`, `onError` and `onOpen`. Listing one here
+   * throws a `TypeError` rather than handing a control frame to a data callback.
+   */
+  events?: readonly string[];
+  /**
+   * Called when the server reports it could not replay the client's full
+   * history. The caller should re-sync from scratch rather than assume the
+   * events it did receive are complete.
+   *
+   * A gap is not the only way a subscription stops being trustworthy: a stream
+   * that fails permanently is reported through {@link PubSubClientOptions.onError}.
+   */
+  onGap?: (topic: string) => void;
+  /**
+   * Called when the stream errors. `EventSource` retries a dropped connection on
+   * its own, but a non-2xx response or a wrong content-type closes it FOR GOOD —
+   * the subscription is then dead and this is the only notice of it. Check
+   * `readyState === 2` (CLOSED) to tell the two apart, and resubscribe.
+   */
+  onError?: (topic: string, e: Event) => void;
+  /** Called when the stream opens, including after `EventSource`'s own reconnect. */
+  onOpen?: (topic: string) => void;
+}
+
+export interface SubscribeOptions {
+  /**
+   * Event names for this subscription, overriding the client's default set.
+   * `gap`, `error` and `open` are reserved; see {@link PubSubClientOptions.events}.
+   */
+  events?: readonly string[];
+}
+
+export interface PubSubClient {
+  subscribe(
+    topic: string,
+    cb: (data: unknown, e: { id: number; event?: string }) => void,
+    options?: SubscribeOptions,
+  ): Unsubscribe;
+  close(): void;
+}
+
+export function newPubSubClient(
+  baseUrl: string,
+  { EventSourceImpl, events, onGap, onError, onOpen }: PubSubClientOptions = {},
+): PubSubClient {
+  const Impl = EventSourceImpl ?? globalThis.EventSource;
+  if (!Impl) throw new Error("no EventSource available; pass options.EventSourceImpl");
+
+  const open = new Set<EventSource>();
+  const base = baseUrl.replace(/\/$/, "");
+  const defaultEvents =
+    events === undefined ? DEFAULT_EVENTS : checkEvents(events, "newPubSubClient");
+
+  return {
+    subscribe(topic, cb, options = {}) {
+      // Validated before anything is opened, so a rejected call leaks no EventSource.
+      const names =
+        options.events === undefined ? defaultEvents : checkEvents(options.events, "subscribe");
+
+      const source = new Impl(`${base}/${topic}`);
+      open.add(source);
+
+      const listeners: Array<[string, (e: Event) => void]> = [];
+      const on = (type: string, fn: (e: Event) => void) => {
+        listeners.push([type, fn]);
+        source.addEventListener(type, fn);
+      };
+
+      for (const name of names) {
+        on(name, (e) => {
+          const m = e as MessageEvent;
+          cb(JSON.parse(m.data), {
+            id: Number(m.lastEventId),
+            // `message` is the unnamed default; anything else names itself.
+            ...(name === "message" ? {} : { event: name }),
+          });
+        });
+      }
+      // The gap signal is the client half of the replay contract; it never
+      // reaches the subscriber, which would mistake it for a payload.
+      on("gap", () => onGap?.(topic));
+      on("error", (e) => onError?.(topic, e));
+      on("open", () => onOpen?.(topic));
+
+      return () => {
+        for (const [type, fn] of listeners) source.removeEventListener(type, fn);
+        listeners.length = 0;
+        source.close();
+        open.delete(source);
+      };
+    },
+
+    close() {
+      for (const s of open) s.close();
+      open.clear();
+    },
+  };
+}