@statewalker/webrun-http-events 0.1.0 → 0.1.1

package/README.md

@@ -1,16 +1,51 @@
 # @statewalker/webrun-http-events
 
-Generic publish/subscribe over [Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html):
-a standard `FetchHandler` on the server side and a matching `EventSource` client on the page side.
+## What it is
 
-No runtime dependencies, no DOM APIs on the server half (it runs in a Worker, a ServiceWorker or
-Node), and no vocabulary of its own — topics and event names are yours.
+Publish/subscribe over
+[Server-Sent Events](https://html.spec.whatwg.org/multipage/server-sent-events.html).
+The server half is a standard `(Request) => Promise<Response>` handler that
+streams `text/event-stream`; the client half wraps `EventSource` and delivers
+parsed payloads per topic. Topics and event names are yours; the package has no
+vocabulary of its own.
+
+## Why it exists
+
+Pushing events from a worker, a ServiceWorker or a Node process to a page needs
+more than a stream of frames. A reconnecting `EventSource` has to get back what
+it missed, a client that cannot get it back has to be told so, a named event
+has to reach the listener that expects it, and a subscription that dies has to
+be reported. This package implements those rules once, on top of a plain fetch
+handler, so it runs wherever a `Request`/`Response` handler runs: behind a
+`@statewalker/webrun-http-browser` ServiceWorker, inside a `Duplex` from
+`@statewalker/webrun-http-streams`, or on a real HTTP server.
+
+## How to use
 
 ```sh
-npm install @statewalker/webrun-http-events
+pnpm add @statewalker/webrun-http-events
 ```
 
-## Server
+- **Peer dependencies:** none. **Runtime dependencies:** none.
+- **Entry point:** one, `.`. ESM only: `dist/index.mjs` with
+  `dist/index.d.mts`, built by tsdown. The `source` export condition points at
+  `src/index.ts`.
+- **Environment:** the server half (`newPubSub`, `newBroker`,
+  `formatSseEvent`) uses no DOM API and runs in a page, a Worker, a
+  ServiceWorker or Node. The client half (`newPubSubClient`) needs an
+  `EventSource`: the global one in a browser, or one passed as
+  `EventSourceImpl` elsewhere.
+
+| Export | What it is |
+| --- | --- |
+| `newPubSub(options?)` | `{ handler, publish, subscriberCount, topicCount }`. Types: `PubSub`, `PubSubOptions`, `FetchHandler`. |
+| `newPubSubClient(baseUrl, options?)` | `{ subscribe(topic, cb, options?), close() }`. Types: `PubSubClient`, `PubSubClientOptions`, `SubscribeOptions`. |
+| `newBroker(options?)` | The in-memory topic broker behind `newPubSub`: `publish`, `subscribe`, `replay`, `subscriberCount`, `topicCount`. Types: `Broker`, `BrokerEvent`, `BrokerOptions`, `Subscriber`, `Unsubscribe`. |
+| `formatSseEvent(event)` | Formats one `{ id, event?, data }` as an SSE frame. |
+
+## Examples
+
+### Server
 
 ```ts
 import { newPubSub } from "@statewalker/webrun-http-events";
@@ -24,24 +59,25 @@ export const fetch = (request: Request) => events.handler(request);
 events.publish("build", { changed: ["/index.html"] }, "rebuilt");
 ```
 
-`newPubSub(options)`:
-
-| option | meaning |
-| --- | --- |
-| `topics` | Allow-list of topic names. Without it, any request path allocates a topic — set it on a public endpoint. |
-| `bufferSize` | Events retained per topic for `Last-Event-ID` replay (default 64). |
-| `heartbeatMs` | Interval for `: ping` comment frames. 0 (default) means no heartbeat. |
-| `onSubscriberError` | Called when a subscriber throws; delivery to the others continues either way. |
+| `newPubSub` option | Default | Meaning |
+| --- | --- | --- |
+| `topics` | none | Allow-list of topic names. Without it any request path allocates a topic, so set it on a public endpoint. |
+| `bufferSize` | `64` | Events retained per topic for `Last-Event-ID` replay. |
+| `heartbeatMs` | `0` | Interval for `: ping` comment frames, which keep a half-open connection visible to proxies. `0` means no heartbeat. |
+| `onSubscriberError` | none | `(error, event)`, called when a subscriber throws. Delivery to the others continues either way. |
 
-The handler answers `405` to anything but `GET` and `404` to an unknown or empty topic.
+The handler answers `405 method not allowed` (with `allow: GET`) to anything
+but `GET`, and `404 no such topic` to an empty or unlisted topic. A stream
+response carries `cache-control: no-cache` and `x-accel-buffering: no`, which
+stops proxy buffering from stalling delivery.
 
-## Client
+### Client
 
 ```ts
 import { newPubSubClient } from "@statewalker/webrun-http-events";
 
 const client = newPubSubClient("/_events", {
-  events: ["message", "rebuilt"], // see "event names" below
+  events: ["message", "rebuilt"], // see "A named event fires only under its name"
   onGap: (topic) => location.reload(), // history could not be replayed: re-sync
   onError: (topic, e) => console.warn("subscription failed", topic, e),
 });
@@ -49,39 +85,118 @@ const client = newPubSubClient("/_events", {
 const off = client.subscribe("build", (data, { id, event }) => {
   console.log(id, event, data);
 });
+
+// later
+off(); // one subscription
+client.close(); // every subscription of this client
+```
+
+Each `subscribe` opens one `EventSource` on `<baseUrl>/<topic>`. Options:
+`events`, `onGap`, `onError`, `onOpen`, and `EventSourceImpl` for runtimes
+without a global `EventSource`. With no `EventSource` at all,
+`newPubSubClient` throws `no EventSource available; pass options.EventSourceImpl`.
+
+### Broker and frames without HTTP
+
+```ts
+import { formatSseEvent, newBroker } from "@statewalker/webrun-http-events";
+
+const broker = newBroker({ bufferSize: 2 });
+const off = broker.subscribe("t", (e) => console.log(e.id, e.data));
+broker.publish("t", 1);
+broker.publish("t", 2);
+broker.publish("t", 3);
+
+broker.replay("t", 0); // { events: [id 2, id 3], complete: false } — id 1 was evicted
+broker.replay("t", 1); // { events: [id 2, id 3], complete: true }
+
+formatSseEvent({ id: 1, event: "x", data: "hi" }); // 'id: 1\nevent: x\ndata: "hi"\n\n'
+off();
+```
+
+## Internals
+
+### A named event fires only under its name
+
+A frame published with a name (`publish(topic, data, "rebuilt")`) is
+dispatched by `EventSource` only under that name; it does not also fire
+`message`. So every name a page wants must be listed, per client (`events`) or
+per subscription (`subscribe(topic, cb, { events })`). The default is
+`["message"]`, which is what an unnamed `publish(topic, data)` produces.
+
+`gap`, `error` and `open` are reserved. They are the client's control channels,
+reported through `onGap`, `onError` and `onOpen`. Listing one as a data event
+throws, before any `EventSource` is opened:
+
+```
+TypeError: newPubSubClient: "gap" is a reserved event name — it is delivered to onGap, not to a subscriber
 ```
 
-### Event names
+A `gap` delivered as data would let the caller patch forward from a history it
+believes complete, and `error`/`open` carry a bare `Event` with no data to
+parse.
 
-A frame published with a name (`publish(topic, data, "rebuilt")`) is dispatched by `EventSource`
-**only** under that name — it does not also fire `message`. So every name a page wants must be
-listed, either per client (`events`) or per subscription (`client.subscribe(topic, cb, { events })`).
-The default is `["message"]`, which is what an unnamed `publish(topic, data)` produces.
+### Replay is all or nothing
 
-`gap`, `error` and `open` are **reserved**: they are the client's own control channels, reported
-through `onGap`, `onError` and `onOpen`. Listing one as a data event throws a `TypeError` — a gap
-delivered as data is exactly the failure the gap contract exists to prevent.
+Every event carries a per-topic id starting at 1. A reconnecting `EventSource`
+sends `Last-Event-ID`, and the server replays what it still retains. When it
+cannot reconstruct the client's history, it sends a `gap` frame first instead
+of a partial replay that would look whole:
 
-### Gaps
+- the requested events were evicted from the ring of `bufferSize`;
+- the id is above anything this server issued (a client left over from a
+  previous process);
+- the header is not a non-negative safe integer.
 
-Every event carries an id. A reconnecting `EventSource` sends `Last-Event-ID`, and the server
-replays what it still retains. When it cannot reconstruct the client's history — the events were
-evicted, the id predates a server restart, or the header was unreadable — it sends a `gap` event
-instead of a partial replay that would look whole. `onGap` means *you are not current*: reload or
-re-sync rather than patching forward.
+`onGap` means "you are not current": reload or re-sync rather than patch
+forward.
 
-### Permanent failure
+### A permanent failure is reported once
 
-`EventSource` reconnects on its own after a dropped connection, but a non-2xx response or a wrong
-content-type closes it for good. That is reported through `onError` (check `readyState === 2`); a
+`EventSource` reconnects on its own after a dropped connection, but a non-2xx
+response or a wrong content type closes it for good. That is reported through
+`onError`; check `readyState === 2` (CLOSED) to tell the two apart. A
 subscription that died is never resurrected by itself.
 
-## Notes
+### Delivery is synchronous and isolated
+
+`publish` delivers to every subscriber before it returns. A subscriber that
+throws is reported to `onSubscriberError` and does not starve the others or the
+publisher; a reporter that throws is swallowed for the same reason. A stream
+whose client went away, or whose frame cannot be produced, unsubscribes itself.
+
+Reentrant publishing (calling `publish` from inside a subscriber) is not
+supported. The inner event is delivered to completion first, so subscribers
+observe ids out of order and a client's `Last-Event-ID` can move backwards.
+Publish from a fresh task instead.
+
+A topic with no subscribers and no retained events is dropped, so topic names
+taken from request paths do not accumulate.
+
+### Framing
+
+`data` is always JSON-serialised, strings included, and every line is prefixed
+with `data: `. A payload JSON cannot represent (`undefined`, a function, a
+symbol, a BigInt, a circular object) is framed as `null`; the event still
+reaches the client with its id and name. CR and LF are stripped from event
+names, since a newline there would inject frames.
+
+### Dependencies
+
+Zero runtime dependencies; only platform APIs (`Request`, `Response`,
+`ReadableStream`, `TextEncoder`, `EventSource` on the client).
+`@statewalker/webrun-http-browser` is a dev dependency, used by the browser
+test.
+
+### Tests
 
-- Reentrant publishing — calling `publish` from inside a subscriber — is not supported: the inner
-  event is delivered to completion first, so subscribers observe ids out of order.
-- A payload JSON cannot represent (`undefined`, a function, a symbol, a BigInt, a circular object)
-  is framed as `null`; the event still reaches the client with its id and name.
+- `pnpm test`: builds with tsdown, then runs the unit tests with a fake
+  `EventSource` and in-process responses.
+- `pnpm run test:browser`: drives a real Chromium tab through a real
+  ServiceWorker (`@statewalker/webrun-http-browser`'s `sw-worker.js`) and a
+  real `text/event-stream` fetch, including past the 30 s ServiceWorker idle
+  window.
+- `pnpm run typecheck`.
 
 ## License
 

package/package.json

@@ -1,9 +1,18 @@
 {
   "name": "@statewalker/webrun-http-events",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "private": false,
   "type": "module",
   "description": "Generic publish/subscribe over Server-Sent Events: a standard FetchHandler and a matching client.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/statewalker/webrun-wire.git",
+    "directory": "packages/webrun-http-events"
+  },
+  "bugs": {
+    "url": "https://github.com/statewalker/webrun-wire/issues"
+  },
+  "homepage": "https://github.com/statewalker/webrun-wire/tree/main/packages/webrun-http-events#readme",
   "license": "MIT",
   "exports": {
     ".": {
@@ -22,7 +31,7 @@
     "tsdown": "^0.23.0",
     "typescript": "^7.0.2",
     "vitest": "^5.0.3",
-    "@statewalker/webrun-http-browser": "^0.6.3"
+    "@statewalker/webrun-http-browser": "^0.6.4"
   },
   "sideEffects": false,
   "publishConfig": {