@dokebi/sse 0.4.1 → 0.4.3

package/AI.md

@@ -1,4 +1,4 @@
-# AI guide — @dokebi/sse 0.4.0
+# AI guide — @dokebi/sse
 
 Server-sent events (SSE) for @dokebi/web apps. The server writes events to authenticated streams and, with `eventBus`, sends them through @dokebi/event-bus to the streams of other workers and servers too. The browser client is `./client` of the same package (plus `./client/vue`, `./client/react`, `./client/bundle`). At most once (no ACK, no resending, no retention). Node >=24.0.0, core ^0.4.0, @dokebi/web (required), @dokebi/event-bus (only with `eventBus`), @dokebi/health (check `sse` when present). The decision is [D-0060](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0060-sse.md); the human-oriented description is the [README](README.md).
 
@@ -21,14 +21,20 @@ npx dokebi add @dokebi/sse
 | `bus` | string | — | deprecated name of `eventBus`: warns `OPTION_DEPRECATED`; setting both is `INVALID_OPTIONS` |
 | `busEvent` | string | `dokebi.sse` | the bus event name |
 | `allowInCluster` | boolean | `false` | allow starting in a cluster worker without a NATS bus (only for a single worker) |
-| `retryMs` | integer | 3000 | the first `retry:` sent (browser reconnect delay); also the client backoff's minimum |
-| `heartbeatMs` | integer | 15000 | interval of the `: ping` comment. Keep it shorter than the proxy idle limit |
-| `maxConnections` | integer | 1024 | streams per process (worker). Beyond it 503 `CAPACITY` |
-| `maxBufferedBytes` | integer | 1048576 | bytes waiting to be sent on one stream. Beyond it the stream is cut with warn `SLOW_CONSUMER` |
+| `retryMs` (reloadable) | integer | 3000 | the first `retry:` sent (browser reconnect delay); also the client backoff's minimum |
+| `heartbeatMs` (reloadable) | integer | 15000 | interval of the `: ping` comment. Keep it shorter than the proxy idle limit |
+| `maxConnections` (reloadable) | integer | 1024 | streams per process (worker). Beyond it 503 `CAPACITY` |
+| `maxBufferedBytes` (reloadable) | integer | 1048576 | bytes waiting to be sent on one stream. Beyond it the stream is cut with warn `SLOW_CONSUMER` |
 | `maxRooms` | integer | 32 | rooms per stream |
-| `maxEventBytes` | integer | 65536 | bytes of an event's data (JSON). Keep it below the bus `maxPayloadBytes` |
+| `maxEventBytes` (reloadable) | integer | 65536 | bytes of an event's data (JSON). Keep it below the bus `maxPayloadBytes`: with `eventBus`, an event whose bus message (the data JSON inside the envelope, its quotes escaped again — up to about twice the data) is over the bus `maxPayloadBytes` of `dokebi-event-bus.buses.<eventBus>` is `EVENT_TOO_LARGE` before any stream gets it (before, this process wrote it and the bus refused it: `BUS_PUBLISH_FAILED`, other processes never had it) |
 | `shutdownTimeoutMs` | integer | 2000 | how long drain waits for streams to end after `dokebi-restart` (named `closeTimeoutMs` before 0.4.0) |
 | `closeTimeoutMs` | integer | — | deprecated name of `shutdownTimeoutMs` (D-0071) |
+| `busRetryAfterMs: { busy?, unavailable? }` | object | `{ busy: 1000, unavailable: 5000 }` | the `Retry-After` (ms, 1000 to 3600000, sent in whole seconds) of the retryable 503 a route answers when `publish` fails for a transient bus reason: `busy` for a bus at its pending limit, `unavailable` for a bus or NATS connection that is down, closed or draining ([D-0107](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0107-stream-and-render-bounds.md) §6). Size `unavailable` near how long your bus takes to come back |
+| `endTimeoutMs` | integer | 5000 | how long a stream the server ended (`stream.close()`, a revoked authorization, drain) may take to send what it still holds; then it is destroyed with warn `STREAM_END_TIMEOUT` and its `maxConnections` slot is free ([D-0107](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0107-stream-and-render-bounds.md)). 1 to 600000. Size it above the time your slowest wanted client needs to read `maxBufferedBytes` |
+| `beforeStreamTimeoutMs` | integer 100–600000 | 5000 | the longest wait for the before-hijack steps (the session save, auth cookies; below); slower refuses the stream with 500 `COMMIT_FAILED`. Size it above the slowest session store write you accept, below the client's connect timeout |
+| `reloadRetryMs` | integer 100–86400000 | 60000 | the `retry:` sent with `dokebi-reload`: a client that ignores the reload reconnects this slowly |
+| `busWatchIntervalMs` | integer 100–60000 | 1000 | how often the event bus state is read for the `sse` health check and its warn/info log; an outage shows within this long |
+| `logRepeatWindowMs` | integer 1000–3600000 | 10000 | window of the repeated stream failure logs (`SSE_COMMIT_FAILED` and the others of this gateway): the first is logged in full, the rest of the window are counted (`repeated`, `intervalMs`) |
 
 **Cluster check (`LOCAL_IN_CLUSTER`)**: in a node:cluster worker, the start fails with an error log (with `fix`) when there is no `eventBus` or its driver is not `nats`. The event-bus API does not report the driver, so **the app setting `dokebi-event-bus.buses.<eventBus>.driver` is read (and the old name `transport`)**. When the event-bus options were passed only in code, the driver is unknown (`unknown`) and the start is refused. Move them to the configuration file, or, if there really is only one worker, set `allowInCluster: true`.
 
@@ -39,8 +45,9 @@ import { createPlugin, dependency, type SseApi } from '@dokebi/sse';
 const sse = context.getDependency(dependency);          // created from this package when missing
 sse.route({
   path: '/events',                                       // GET only (no HEAD)
+  config: { id: 'events' },                              // optional: the route id (D-0140), as config.id of a web route
   constraints: { dokebiApp: 'shop' },                    // optional: @dokebi/app domain routing
-  origins: ['https://admin.example.com'],                // optional: allow other origins (CORS + credentials); '*' without credentials
+  origins: ['https://admin.example.com'],                // optional: allow other origins (CORS + credentials); '*' without credentials. @dokebi/cors does not answer streams (D-0148)
   version: APP_VERSION,                                  // optional: D-0033
   authenticate: (request) => ({ tenant, member, rooms: ['r1'] }),  // undefined → 401
   onOpen: (stream) => { stream.join(`user:${stream.member}`); stream.send('snapshot', data); },
@@ -51,12 +58,13 @@ sse.connections({ tenant, room });                       // the count on this wo
 ```
 
 - `route` works only in setup (`FROZEN` afterwards). `authenticate` and `onOpen` run on every reconnect.
+- Route id (D-0140): `config: { id }` becomes the Fastify config of the stream route, so `dokebi describe` lists it as `routes[].id`, `web.routes()` and the per-route hooks of dokebi-web (`web.routeHook`, an audit log's `onResponse`) see it, and a request reads it as `request.routeOptions.config.id`. The id is checked at start by dokebi-web exactly like a web route's: 1 to 64 letters, digits, `.`, `_` or `-`, starting with a letter (`INVALID_ROUTE_CONFIG`); the same id on two routes of one app (a web route, a socket or a stream) fails the start with `DUPLICATE_ROUTE_ID`. `config` takes only `id`: anything else (null, a string, another key such as `auth`) is `INVALID_ROUTE` at `route`. The refusal logs carry it as `routeId` (§7).
 - Targets: `{tenant}` everyone, `{tenant, member}` all tabs of one person, `{tenant, room}` a room, `{tenant, room, member}` that person in the room. Strings are 1 to 256 characters (any characters). A target only ever reaches streams of its own tenant.
 - Prefix targets (D-0061): with `tenantPrefix` instead of `tenant` (exactly one of them, otherwise `INVALID_TARGET`), every tenant whose name starts with that prefix (with the same `member` and `room` rules). Bus messages carry the same target, and each process scans its own tenant index once. @dokebi/app's namespaces `<ns>:` use it.
 - Event names: `^[A-Za-z][A-Za-z0-9._:-]{0,63}$`, not starting with `dokebi-` (reserved for the plugin). data is one line of JSON (`undefined` becomes `null`); functions, BigInt and cycles are `INVALID_DATA`.
-- `publish` order: check target, name and data → when the bus is not `ready`, `BUS_UNAVAILABLE` (nothing is sent anywhere, error log) → write to this process's streams → publish on the bus. A failed bus publish is `BUS_PUBLISH_FAILED` (`cause`, `id`, `local`; this process already received it, other places are unknown; the error log has the full error). Whether to send again is the caller's choice (duplicates possible).
+- `publish` order: check target, name and data → when the bus is not `ready`, `BUS_UNAVAILABLE` (nothing is sent anywhere, error log) → with a bus, its bus message must fit the bus `maxPayloadBytes` of the configuration, else `EVENT_TOO_LARGE` (nothing sent) → write to this process's streams → publish on the bus. A failed bus publish is `BUS_PUBLISH_FAILED` (`cause`, `id`, `local`; this process already received it, other places are unknown; the error log has the full error). Whether to send again is the caller's choice (duplicates possible). A transient bus failure — `BUS_UNAVAILABLE`, or `BUS_PUBLISH_FAILED` whose cause is the event bus's `OVERLOADED`, `TRANSPORT_FAILED`, `DEPENDENCY_UNAVAILABLE`, `BUS_DRAINING` or `CLOSED` (by `plugin` and `code`) — carries `status: 503` and `data.retryAfterMs` (`busRetryAfterMs`), so a route that lets it through answers 503 with `Retry-After`; any other failure (an invalid payload) answers 500 (D-0107 §6). An app that wraps the error in its own decides the status itself (keep the `cause`).
 - The sending process skips its own bus messages (`origin`): with a local or a NATS bus, that process's streams receive each event once.
-- `stream.send` writes to one connection only and returns true when written (false when closed or cut for being slow). Events get an `id` that increases in order within this process.
+- `stream.send` writes to one connection only and returns true when written (false when closed or cut for being slow). Events get an `id` that increases in order within this process, unless you give one: `stream.send(event, data, { id })` and `publish(target, event, data, { id })` (and `app.realtime().publish` of @dokebi/app) take an id of your own durable order, such as a message's sequence in its channel (1 to 64 of A-Z a-z 0-9 and -, else `INVALID_EVENT_ID`). Every process sends that same id, so a client that reconnects to any worker hands it back as `Last-Event-ID` (AI-M41: the plugin's own ids differ per worker and mean nothing to the database, so resume could not use them).
 - Rooms are per connection. After a reconnect they are empty, so join in `authenticate`'s `rooms` or in `onOpen`.
 - `parseOptions` (the options parser) and the API types (`SseApi`, `SseRoute`, `SseStream`, …) are exported too.
 
@@ -66,6 +74,7 @@ sse.connections({ tenant, room });                       // the count on this wo
 export default defineApp({
   events: (app) => [{
     path: '/events',
+    config: { id: 'shop.events' },                           // unique in the app with its routes and sockets
     authenticate: async (request) => {
       const user = await userOf(request);
       return user && { tenant: user.shop, member: user.id };   // namespace?: one of the app's list (default the first)
@@ -86,12 +95,13 @@ export default defineApp({
 ## 4. Connection lifetime
 
 - Response: 200 `text/event-stream; charset=utf-8`, `Cache-Control: no-cache, no-transform`, `X-Accel-Buffering: no`, `Connection: keep-alive`. The first lines are `retry: <retryMs>` and `event: dokebi-open` (data `{"retryMs":…}`). The Fastify response is hijacked and written directly, so no compression hook applies (dokebi-web does not compress).
-- Refusals: another origin (not listed) 403 `ORIGIN_FORBIDDEN`; before start or while stopping 503 (dokebi-web `STARTING`, `DRAINING`; this plugin `CLOSING`); full 503 `CAPACITY` (`Retry-After: 5`); no authentication 401. EventSource cannot see these statuses (the client below tells them apart with a probe).
+- Refusals: another origin (not listed) 403 `ORIGIN_FORBIDDEN`; before start or while stopping 503 (dokebi-web `STARTING`, `DRAINING`; this plugin `CLOSING`); full 503 `CAPACITY` (`Retry-After: 5`); no authentication 401; an `authorization.valid()` that throws 500 `AUTHORIZATION_FAILED` (error `SSE_AUTHORIZATION_FAILED`); the session save before the stream failed 500 `COMMIT_FAILED` (below). EventSource cannot see these statuses (the client below tells them apart with a probe). For a listed foreign origin (`origins`) the 401, 503 and 500 refusals carry the same CORS headers as the stream, so a page of that origin (and the client's probe) can read them; another origin's 403 carries none.
+- Cookies (D-0089): the stream hijacks the Fastify reply, so **no onSend hook runs**. Just before it writes the head (after origin, capacity, `authenticate` and the probe), the stream runs the before-hijack steps that plugins register for the work they otherwise do in onSend — the @dokebi/session save (or rolling refresh) and the @dokebi/auth cookies (a remember-me restore by a `required` guard rotates the token) — and waits for them, at most `beforeStreamTimeoutMs` (5 s). Then every `Set-Cookie` on the reply (those steps, a hook, a guard) is written with the stream head; browsers apply it on the SSE 200. A step that fails or times out refuses the stream: 500 `{ error: 'COMMIT_FAILED' }`, error `SSE_COMMIT_FAILED` (the full cause). After the head the request's session is final (a change throws `CLOSED`). The steps are matched by name only (`Symbol.for('dokebi.web.beforeHijack')` on the Fastify instance): this package imports neither plugin. (The `dokebiProbe` answer below is a normal reply and runs onSend instead.)
 - `?dokebiProbe=1`: checks only origin, capacity and authentication and answers 204 (no stream is opened). The browser client uses it to find out why a connection failed.
-- Version (D-0033): when the route's `version` differs from the query `dokebiVersion` (or the `x-dokebi-version` header), it sends `retry: 60000` + `event: dokebi-reload` (data `{"version":…}`) and ends.
-- The `Last-Event-ID` header (when the browser reconnects by itself) or the query `lastEventId` (when the client reopens itself) becomes `stream.lastEventId`. The server keeps no events.
-- Heartbeat: `: ping` every `heartbeatMs`. Slow receivers: when the waiting bytes plus a new event exceed `maxBufferedBytes`, that stream is cut (`SLOW_CONSUMER`; other streams are unaffected).
-- Drain (stop, rolling restart): refuse new streams → unsubscribe from the bus → send `event: dokebi-restart` (data `{"retryMs":…}`) to every stream → end them → cut the remaining connections after `shutdownTimeoutMs` (or the core drain deadline) → wait for onClose. It drains before dokebi-web.
+- Version (D-0033): when the route's `version` differs from the query `dokebiVersion` (or the `x-dokebi-version` header), it sends `retry: <reloadRetryMs>` (60000) + `event: dokebi-reload` (data `{"version":…}`) and ends.
+- The `Last-Event-ID` header (when the browser reconnects by itself) or the query `lastEventId` (when the client reopens itself) becomes `stream.lastEventId`. The server keeps no events: to resume, publish with ids of your own order (above), and in `onOpen` read `stream.lastEventId` and send from your database what came after it, with the same ids, before the live events reach that stream.
+- Heartbeat: `: ping` every `heartbeatMs`. Slow receivers: when the waiting bytes plus a new event exceed `maxBufferedBytes`, that stream is cut (`SLOW_CONSUMER`; other streams are unaffected). A stream the server ends with `end()` sends its last chunk behind the bytes still waiting; when its client stopped reading, `close` would never come and the stream would keep its slot, so after `endTimeoutMs` it is destroyed (warn `STREAM_END_TIMEOUT` with `bufferedBytes`; `onClose` gets the reason it was ended with).
+- Drain (stop, rolling restart): refuse new streams → unsubscribe from the bus → send `event: dokebi-restart` (data `{"retryMs":…}`) to every stream → end them → cut the remaining connections after `shutdownTimeoutMs`, `endTimeoutMs` or the core drain deadline, whichever comes first → wait for onClose. It drains before dokebi-web.
 - Health: with dokebi-health it registers the non-required check `sse`. When the bus is not `ready` the check is `failed` (`BUS_UNAVAILABLE`, warn log), and `ready` again when it returns (info log). It never drops readiness.
 
 ## 5. Browser client
@@ -115,7 +125,7 @@ events.close(); events.reconnect();
 - Importing touches neither window nor EventSource (SSR safe). It opens when you call `connectEvents`.
 - A listener is added to the EventSource only on the first `on` per event name. data is read as JSON (a failure is `BAD_DATA`).
 - `dokebi-reload` → `onReload` (default `location.reload()`); it does not reconnect.
-- `dokebi-restart` → close, then reopen after backoff with jitter (starting at `max(minMs, server retry)`, doubling up to `maxMs`, 50–100% of that value).
+- `dokebi-restart` → close, then reopen after backoff with jitter (starting at `max(minMs, server retry)`, doubling up to `maxMs`, 50–100% of that value). `minMs` and `maxMs` are at least 100 ms (the server's smallest `retryMs`); a value that is not a finite number takes the default.
 - When EventSource reconnects by itself (the stream ended, network): left alone (`reconnecting`; the browser sends `Last-Event-ID`).
 - When EventSource gave up (HTTP error, wrong format, readyState CLOSED): close and ask why with `?dokebiProbe=1`. 401 or 403 → `closed` (permanent); anything else reopens after backoff. When reopening itself it sends the last id as the `lastEventId` query (it knows only the ids of events it listens to).
 - bfcache: closes on `pagehide` (persisted) (`paused`) and reopens on `pageshow` (persisted).
@@ -136,13 +146,17 @@ On streams of a seal host (@dokebi/app `domains.<host>.seal: true`) or of a `sea
 
 ## 7. Logs (D-0047)
 
-debug: route registration, stream open and close (reason, ms, open count), refusal reasons, version refusals, room join and leave, publish (id, local), bus deliveries received, drain begin and end. warn: `SLOW_CONSUMER`, `BUS_UNAVAILABLE` (state change). error (the full error; repeats once per 10 seconds with `repeated`): `BUS_PUBLISH_FAILED`, `BUS_UNAVAILABLE` (publish refused), `BUS_MESSAGE_INVALID`, `SSE_ON_OPEN_FAILED`, `SSE_ON_CLOSE_FAILED`, `STREAM_WRITE_FAILED`, `BUS_UNSUBSCRIBE_FAILED`, `SSE_LOCAL_IN_CLUSTER`. A bad `authenticate` result (`INVALID_IDENTITY`) is logged by dokebi-web as 500 with `WEB_REQUEST_FAILED`.
+debug: route registration, stream open and close (reason, ms, open count), refusal reasons (`SSE stream unauthorized` for a 401, `SSE origin refused` for a 403, `SSE stream refused` for a 503; each with `path` and `routeId`, the route's `config.id` or null, D-0140), version refusals, room join and leave, publish (id, local), bus deliveries received, drain begin and end. `SSE stream ending` (reason, `bufferedBytes`, `endTimeoutMs`). warn: `SLOW_CONSUMER`, `STREAM_END_TIMEOUT` (an ended stream whose client stopped reading, destroyed), `BUS_UNAVAILABLE` (state change). error (the full error; repeats once per 10 seconds with `repeated`): `BUS_PUBLISH_FAILED`, `BUS_UNAVAILABLE` (publish refused), `BUS_MESSAGE_INVALID`, `SSE_ON_OPEN_FAILED`, `SSE_ON_CLOSE_FAILED`, `STREAM_WRITE_FAILED`, `BUS_UNSUBSCRIBE_FAILED`, `SSE_AUTHORIZATION_FAILED`, `SEAL_ENCODE_FAILED`, `SSE_LOCAL_IN_CLUSTER`, `SSE_COMMIT_FAILED` (D-0089). A bad `authenticate` result (`INVALID_IDENTITY`) is logged by dokebi-web as 500 with `WEB_REQUEST_FAILED`.
 
 ## 8. Errors
 
 `SseError` (branch on `code`; never `instanceof`).
 
 <!-- docs-check: complete-error-codes SseErrorCode -->
-Configuration and registration: `INVALID_OPTIONS`, `INVALID_ROUTE` (`path`, `origins` and so on), `FROZEN` (`route` after setup), `LOCAL_IN_CLUSTER` (§2; `SSE_LOCAL_IN_CLUSTER` before 0.4.0, D-0071). Connections: `INVALID_IDENTITY` (a bad `authenticate` result, 500). Sending: `INVALID_TARGET`, `INVALID_EVENT` (event name), `INVALID_DATA`, `EVENT_TOO_LARGE` (`maxEventBytes`), `INVALID_ROOM`, `ROOM_LIMIT` (`maxRooms`), `BUS_UNAVAILABLE`, `BUS_PUBLISH_FAILED` (`cause`, `id`, `local`, §3), `CLOSED` (`publish` after the app stopped).
+Configuration and registration: `INVALID_OPTIONS`, `INVALID_ROUTE` (`path`, `origins` and so on), `FROZEN` (`route` after setup), `LOCAL_IN_CLUSTER` (§2; `SSE_LOCAL_IN_CLUSTER` before 0.4.0, D-0071). Connections: `INVALID_IDENTITY` (a bad `authenticate` result, 500). Sending: `INVALID_TARGET`, `INVALID_EVENT` (event name), `INVALID_EVENT_ID` (an `options.id` that is not 1 to 64 of A-Z a-z 0-9 and -, or options that are not an object), `INVALID_DATA`, `EVENT_TOO_LARGE` (`maxEventBytes`), `INVALID_ROOM`, `ROOM_LIMIT` (`maxRooms`), `BUS_UNAVAILABLE`, `BUS_PUBLISH_FAILED` (`cause`, `id`, `local`, §3), `CLOSED` (`publish` after the app stopped).
 
 `SseError` is a `DokebiError` (D-0063): `plugin: 'dokebi-sse'` and a `fix` that says how to repair it. `INVALID_OPTIONS` carries per-path problems in `details.issues` (no values). The `defineOptions` declaration in `src/options.ts` is the parser, and the build writes `options.schema.json` from it (D-0063 §3; never edit it by hand).
+
+## Authorization lifetime (0.4.2)
+
+An authenticated identity may carry `authorization: { valid(): boolean; subscribe(invalidated: () => void): () => void }`. Use `await request.auth.live()` with session auth, or with a Bearer token (auth 0.4.1, D-0124: an account change ends the stream within `live.maxAgeMs`; an OAuth access token uses `oauth.live(request)`), and reject a missing lease for private streams. The gateway rejects invalid initial identities, subscribes to invalidation, checks validity before every write (heartbeats included) and ends revoked streams. Closing the stream unsubscribes. A `valid`, `subscribe` or unsubscribe that throws is logged at error `SSE_AUTHORIZATION_FAILED`; a failed `subscribe` ends the stream, since it could not be revoked later. Guards stay local; they are not sent through the event bus. Existing unguarded identities retain their behavior; authentication at connect time alone does not revoke an already-open private stream. Public guest streams may use a separate identity with no private member access.

package/README.md

@@ -32,6 +32,7 @@ Before 0.4.0 the key was `bus` (and `closeTimeoutMs` is now `shutdownTimeoutMs`)
 const events = context.get(sse);   // or context.getDependency(dependency)
 events.route({
   path: '/events',
+  config: { id: 'events' },                     // the route id (D-0140): describe, route hooks, refusal logs
   version: APP_VERSION,                         // a different one gets dokebi-reload (D-0033)
   authenticate: async (request) => {            // undefined → 401
     const user = await request.session.get('user');
@@ -48,14 +49,14 @@ await events.publish({ tenantPrefix: 'front:' }, 'notice', { text: 'Maintenance'
 
 | API | Meaning |
 |---|---|
-| `route({ path, constraints?, origins?, version?, authenticate, onOpen?, onClose? })` | setup only. A GET stream route |
+| `route({ path, config?, constraints?, origins?, version?, authenticate, onOpen?, onClose? })` | setup only. A GET stream route. `config: { id }` is its route id, checked like a web route's `config.id` (the same id twice in one app fails the start with `DUPLICATE_ROUTE_ID`) |
 | `publish(target, event, data)` | `{ id, local }`. To matching streams of every process (the sending process once). The target is `{ tenant }` or `{ tenantPrefix }` (exactly one) plus `member?` and `room?` |
 | `connections(filter?)` | the number of open streams of this process (worker). `{ tenant?, member?, room?, path? }` |
 | `stream.send(event, data)` · `join(room)` · `leave(room)` · `close()` | one connection only |
 
 **With @dokebi/app (D-0061):** an app's `events: (app) => [route, …]` attaches streams only to the app's domains (route constraint `dokebiApp`). The stream tenant is `<namespace>:<tenant>`; when `authenticate` returns `namespace`, it is chosen from the app's namespaces (outside the list: 401). Server code publishes to that space with `app.realtime(namespace).publish({ tenant?, member?, room? }, event, data)` (without a tenant it is `tenantPrefix: '<namespace>:'`). See "Realtime namespaces" in the @dokebi/app README.
 
-Branch on error `code`s: `INVALID_EVENT` (naming rule, `dokebi-` prefix), `INVALID_DATA`, `EVENT_TOO_LARGE`, `INVALID_TARGET`, `ROOM_LIMIT`, `BUS_UNAVAILABLE` (sent nowhere), `BUS_PUBLISH_FAILED` (sent to this process, other places unknown; with `id` and `local`).
+Branch on error `code`s: `INVALID_EVENT` (naming rule, `dokebi-` prefix), `INVALID_DATA`, `EVENT_TOO_LARGE`, `INVALID_TARGET`, `ROOM_LIMIT`, `BUS_UNAVAILABLE` (sent nowhere), `BUS_PUBLISH_FAILED` (sent to this process, other places unknown; with `id` and `local`). A bus that is down, draining or full makes them a retryable 503 with `Retry-After` (`busRetryAfterMs`); other bus failures stay 500 ([D-0107](https://git.nyx-zone.com/dokebi/framework/-/blob/main/docs/decisions/D-0107-stream-and-render-bounds.md) §6).
 
 ## Browser
 

package/dist/browser/sse-client.js

@@ -5,38 +5,38 @@ function r(e) {
 	return t ? Number(t[1]) : void 0;
 }
 function i(i) {
-	let a = i.EventSource ?? globalThis.EventSource, o = i.reconnect !== !1, s = i.reconnect === !1 ? 0 : Math.max(0, i.reconnect?.minMs ?? 1e3), c = i.reconnect === !1 ? 0 : Math.max(s, i.reconnect?.maxMs ?? 3e4), l = /* @__PURE__ */ new Map(), u = /* @__PURE__ */ new Map(), d = /* @__PURE__ */ new Set(), f = /* @__PURE__ */ new Set(), p, m = "connecting", h, g = 0, _ = 0, v, y = !1, b = !1, x = !1, S = i.url ?? i.path;
-	if (typeof S != "string" || !S) throw TypeError("connectEvents needs url or path");
-	let C = i.seal;
-	if (C !== void 0 && typeof C?.unsealFrame != "function") throw TypeError("connectEvents seal needs unsealFrame(frame, url)");
-	let w;
-	function T(e) {
-		if (m !== e) {
-			m = e, i.onStatus?.(e);
-			for (let t of [...d]) t(e);
+	let a = i.EventSource ?? globalThis.EventSource, o = i.reconnect !== !1, s = (e, t) => typeof e == "number" && Number.isFinite(e) ? Math.max(100, e) : t, c = i.reconnect === !1 ? 0 : s(i.reconnect?.minMs, 1e3), l = i.reconnect === !1 ? 0 : Math.max(c, s(i.reconnect?.maxMs, 3e4)), u = /* @__PURE__ */ new Map(), d = /* @__PURE__ */ new Map(), f = /* @__PURE__ */ new Set(), p = /* @__PURE__ */ new Set(), m, h = "connecting", g, _ = 0, v = 0, y, b = !1, x = !1, S = !1, C = 0, w = i.url ?? i.path;
+	if (typeof w != "string" || !w) throw TypeError("connectEvents needs url or path");
+	let T = i.seal;
+	if (T !== void 0 && typeof T?.unsealFrame != "function") throw TypeError("connectEvents seal needs unsealFrame(frame, url)");
+	let E;
+	function D(e) {
+		if (h !== e) {
+			h = e, i.onStatus?.(e);
+			for (let t of [...f]) t(e);
 		}
 	}
-	function E(e) {
-		if (!i.onError && !f.size) console.warn(`[dokebi-sse] ${e.code}`, e.error ?? e.status ?? "");
+	function O(e) {
+		if (!i.onError && !p.size) console.warn(`[dokebi-sse] ${e.code}`, e.error ?? e.status ?? "");
 		else {
 			i.onError?.(e);
-			for (let t of [...f]) t(e);
+			for (let t of [...p]) t(e);
 		}
 	}
-	function D(e) {
-		let t = globalThis.location?.href, n = new URL(S, t);
+	function k(e) {
+		let t = globalThis.location?.href, n = new URL(w, t);
 		for (let [e, t] of Object.entries(i.query ?? {})) t != null && n.searchParams.set(e, String(t));
-		i.version !== void 0 && n.searchParams.set("dokebiVersion", i.version), x && h !== void 0 && n.searchParams.set("lastEventId", h);
+		i.version !== void 0 && n.searchParams.set("dokebiVersion", i.version), S && g !== void 0 && n.searchParams.set("lastEventId", g);
 		for (let [t, r] of Object.entries(e ?? {})) n.searchParams.set(t, r);
-		return w = n.pathname, n.href;
+		return E = n.pathname, n.href;
 	}
-	function O(e, t) {
+	function A(e, t) {
 		let n = t.startsWith("E:");
-		if (C) try {
+		if (T) try {
 			if (!n) throw Error("plain data on a sealed stream");
-			return C.unsealFrame(t, w ?? "/");
+			return T.unsealFrame(t, E ?? "/");
 		} catch (t) {
-			E({
+			O({
 				code: "SEAL_FAILED",
 				event: e,
 				error: t
@@ -44,21 +44,21 @@ function i(i) {
 			return;
 		}
 		if (!n) return t;
-		E({
+		O({
 			code: "SEAL_BRIDGE_MISSING",
 			event: e
 		});
 	}
-	function k(e) {
+	function j(e) {
 		return (t) => {
-			t.lastEventId && (h = t.lastEventId);
-			let n = O(e, t.data);
+			t.lastEventId && (g = t.lastEventId);
+			let n = A(e, t.data);
 			if (n === void 0) return;
 			let r;
 			try {
 				r = JSON.parse(n);
 			} catch (t) {
-				E({
+				O({
 					code: "BAD_DATA",
 					event: e,
 					error: t
@@ -69,10 +69,10 @@ function i(i) {
 				event: e,
 				id: t.lastEventId || void 0
 			};
-			for (let t of [...l.get(e) ?? []]) try {
+			for (let t of [...u.get(e) ?? []]) try {
 				t(r, i);
 			} catch (t) {
-				E({
+				O({
 					code: "HANDLER_FAILED",
 					event: e,
 					error: t
@@ -80,120 +80,121 @@ function i(i) {
 			}
 		};
 	}
-	function A() {
-		v !== void 0 && clearTimeout(v), v = void 0;
+	function M() {
+		y !== void 0 && clearTimeout(y), y = void 0;
 	}
-	function j() {
-		p &&= (p.onopen = null, p.onerror = null, p.close(), void 0);
+	function N() {
+		C++, m &&= (m.onopen = null, m.onerror = null, m.close(), void 0);
 	}
-	function M() {
-		if (A(), y || b) return;
+	function P() {
+		if (M(), N(), b || x) return;
 		if (!a) {
-			y = !0, T("closed"), E({ code: "NO_EVENTSOURCE" });
+			b = !0, D("closed"), O({ code: "NO_EVENTSOURCE" });
 			return;
 		}
-		let o = new a(D(), i.withCredentials ? { withCredentials: !0 } : void 0);
-		p = o, o.onopen = () => {
-			p === o && (_ = 0, T("open"));
+		let o = new a(k(), i.withCredentials ? { withCredentials: !0 } : void 0);
+		m = o, o.onopen = () => {
+			m === o && (v = 0, D("open"));
 		}, o.onerror = () => {
-			p === o && N(o);
+			m === o && F(o);
 		}, o.addEventListener(n, (e) => {
-			g = r(O(n, e.data) ?? "") ?? g;
+			_ = r(A(n, e.data) ?? "") ?? _;
 		}), o.addEventListener(e, (t) => {
-			p === o && O(e, t.data) !== void 0 && I();
+			m === o && A(e, t.data) !== void 0 && R();
 		}), o.addEventListener(t, (e) => {
-			p === o && (g = r(O(t, e.data) ?? "") ?? g, j(), T("reconnecting"), F());
+			m === o && (_ = r(A(t, e.data) ?? "") ?? _, N(), D("reconnecting"), L());
 		});
-		for (let [e, t] of u) o.addEventListener(e, t);
+		for (let [e, t] of d) o.addEventListener(e, t);
 	}
-	function N(e) {
+	function F(e) {
 		if (e.readyState !== 2) {
-			T("reconnecting");
+			D("reconnecting");
 			return;
 		}
-		if (j(), !o) {
-			y = !0, T("closed"), E({ code: "CONNECTION_FAILED" });
+		if (N(), !o) {
+			b = !0, D("closed"), O({ code: "CONNECTION_FAILED" });
 			return;
 		}
-		T("reconnecting");
+		D("reconnecting");
 		let t = globalThis.fetch;
-		i.probe === !1 || !t ? (E({ code: "CONNECTION_FAILED" }), F()) : P(t);
+		i.probe === !1 || !t ? (O({ code: "CONNECTION_FAILED" }), L()) : I(t, C);
 	}
-	async function P(e) {
-		let t;
+	async function I(e, t) {
+		let n;
 		try {
-			t = (await e(D({ dokebiProbe: "1" }), {
+			n = (await e(k({ dokebiProbe: "1" }), {
 				credentials: i.withCredentials ? "include" : "same-origin",
 				cache: "no-store"
 			})).status;
 		} catch (e) {
-			E({
+			if (b || x || t !== C) return;
+			O({
 				code: "CONNECTION_FAILED",
 				error: e
-			}), F();
+			}), L();
 			return;
 		}
-		y || b || (t === 401 || t === 403 ? (y = !0, A(), T("closed"), E({
-			code: t === 401 ? "UNAUTHORIZED" : "FORBIDDEN",
-			status: t
-		})) : (E({
-			code: t === 503 ? "UNAVAILABLE" : "CONNECTION_FAILED",
-			status: t
-		}), F()));
+		b || x || t !== C || (n === 401 || n === 403 ? (b = !0, M(), D("closed"), O({
+			code: n === 401 ? "UNAUTHORIZED" : "FORBIDDEN",
+			status: n
+		})) : (O({
+			code: n === 503 ? "UNAVAILABLE" : "CONNECTION_FAILED",
+			status: n
+		}), L()));
 	}
-	function F() {
-		if (A(), y || b) return;
+	function L() {
+		if (M(), b || x) return;
 		if (!o) {
-			y = !0, T("closed");
+			b = !0, D("closed");
 			return;
 		}
-		let e = Math.max(s, g), t = Math.min(Math.max(c, e), e * 2 ** _);
-		_ = Math.min(_ + 1, 20), x = !0, v = setTimeout(M, Math.round(t / 2 + Math.random() * t / 2));
+		let e = Math.max(c, _), t = Math.min(Math.max(l, e), e * 2 ** v);
+		v = Math.min(v + 1, 20), S = !0, y = setTimeout(P, Math.round(t / 2 + Math.random() * t / 2));
 	}
-	function I() {
-		y = !0, j(), A(), T("closed"), i.onReload ? i.onReload() : globalThis.location?.reload();
+	function R() {
+		b = !0, N(), M(), D("closed"), i.onReload ? i.onReload() : globalThis.location?.reload();
 	}
-	let L = globalThis, R = (e) => {
-		e.persisted && !y && (b = !0, j(), A(), T("paused"));
-	}, z = (e) => {
-		e.persisted && !y && b && (b = !1, _ = 0, x = !0, T("connecting"), M());
+	let z = globalThis, B = (e) => {
+		e.persisted && !b && (x = !0, N(), M(), D("paused"));
+	}, V = (e) => {
+		e.persisted && !b && x && (x = !1, v = 0, S = !0, D("connecting"), P());
 	};
-	return L.addEventListener?.("pagehide", R), L.addEventListener?.("pageshow", z), M(), {
+	return z.addEventListener?.("pagehide", B), z.addEventListener?.("pageshow", V), P(), {
 		get status() {
-			return m;
+			return h;
 		},
 		get lastEventId() {
-			return h;
+			return g;
 		},
 		on(e, t) {
 			if (typeof e != "string" || !e || typeof t != "function") throw TypeError("on(event, handler) needs an event name and a function");
-			let n = l.get(e);
+			let n = u.get(e);
 			if (!n) {
-				n = /* @__PURE__ */ new Set(), l.set(e, n);
-				let t = k(e);
-				u.set(e, t), p?.addEventListener(e, t);
+				n = /* @__PURE__ */ new Set(), u.set(e, n);
+				let t = j(e);
+				d.set(e, t), m?.addEventListener(e, t);
 			}
 			let r = t;
 			return n.add(r), () => {
-				let t = l.get(e);
+				let t = u.get(e);
 				if (!t?.delete(r) || t.size) return;
-				l.delete(e);
-				let n = u.get(e);
-				u.delete(e), n && p?.removeEventListener(e, n);
+				u.delete(e);
+				let n = d.get(e);
+				d.delete(e), n && m?.removeEventListener(e, n);
 			};
 		},
 		onStatus(e) {
-			return d.add(e), () => d.delete(e);
+			return f.add(e), () => f.delete(e);
 		},
 		onError(e) {
-			return f.add(e), () => f.delete(e);
+			return p.add(e), () => p.delete(e);
 		},
 		close() {
-			y = !0, b = !1, j(), A(), L.removeEventListener?.("pagehide", R), L.removeEventListener?.("pageshow", z), T("closed");
+			b = !0, x = !1, N(), M(), z.removeEventListener?.("pagehide", B), z.removeEventListener?.("pageshow", V), D("closed");
 		},
 		reconnect() {
-			let e = y;
-			y = !1, b = !1, _ = 0, x = p !== void 0 || x, j(), e && (L.addEventListener?.("pagehide", R), L.addEventListener?.("pageshow", z)), T("connecting"), M();
+			let e = b;
+			b = !1, x = !1, v = 0, S = m !== void 0 || S, N(), e && (z.addEventListener?.("pagehide", B), z.addEventListener?.("pageshow", V)), D("connecting"), P();
 		}
 	};
 }

package/dist/client/index.js

@@ -22,6 +22,8 @@
 // `@dokebi/seal/http`) as `seal`; it is undefined on a plain host, so the same page code runs on
 // both. With a bridge, plain data is refused; without one, sealed data is (fail closed).
 const CLOSED = 2;
+/** The smallest reconnect delay, as the server's smallest `retryMs`. */
+const RECONNECT_FLOOR_MS = 100;
 const RELOAD = 'dokebi-reload';
 const RESTART = 'dokebi-restart';
 const OPEN = 'dokebi-open';
@@ -34,8 +36,13 @@ function retryOf(text) {
 export function connectEvents(options) {
     const Source = options.EventSource ?? globalThis.EventSource;
     const reconnecting = options.reconnect !== false;
-    const minMs = options.reconnect === false ? 0 : Math.max(0, options.reconnect?.minMs ?? 1000);
-    const maxMs = options.reconnect === false ? 0 : Math.max(minMs, options.reconnect?.maxMs ?? 30_000);
+    // At least the server's smallest `retry:` (100 ms): a minMs of 0 (or NaN) reopened at once,
+    // over and over, against a server that refuses before it sends `retry:`.
+    const delayOf = (value, fallback) => typeof value === 'number' && Number.isFinite(value)
+        ? Math.max(RECONNECT_FLOOR_MS, value)
+        : fallback;
+    const minMs = options.reconnect === false ? 0 : delayOf(options.reconnect?.minMs, 1000);
+    const maxMs = options.reconnect === false ? 0 : Math.max(minMs, delayOf(options.reconnect?.maxMs, 30_000));
     const handlers = new Map();
     const dispatchers = new Map();
     const statusHandlers = new Set();
@@ -50,6 +57,12 @@ export function connectEvents(options) {
     let paused = false;
     /** The next open is this client's own (not the browser's): it carries lastEventId. */
     let manual = false;
+    /**
+     * Counts opens and drops: a probe answer belongs to the stream that failed, and is dropped when
+     * reconnect(), pageshow or close() came while it was in flight (it would otherwise open a second
+     * EventSource beside the live one, or close it on a stale 401).
+     */
+    let generation = 0;
     const base = options.url ?? options.path;
     if (typeof base !== 'string' || !base)
         throw new TypeError('connectEvents needs url or path');
@@ -140,6 +153,7 @@ export function connectEvents(options) {
         timer = undefined;
     }
     function drop() {
+        generation++;
         if (!source)
             return;
         source.onopen = null;
@@ -149,6 +163,8 @@ export function connectEvents(options) {
     }
     function open() {
         clearTimer();
+        // Never two EventSources: their listeners would each deliver every event.
+        drop();
         if (stopped || paused)
             return;
         if (!Source) {
@@ -210,9 +226,9 @@ export function connectEvents(options) {
             later();
             return;
         }
-        void probe(fetcher);
+        void probe(fetcher, generation);
     }
-    async function probe(fetcher) {
+    async function probe(fetcher, asked) {
         let answer;
         try {
             const response = await fetcher(address({ dokebiProbe: '1' }), {
@@ -222,11 +238,14 @@ export function connectEvents(options) {
             answer = response.status;
         }
         catch (error) {
+            // A stale probe's failure belongs to a stream that was already replaced or closed.
+            if (stopped || paused || asked !== generation)
+                return;
             report({ code: 'CONNECTION_FAILED', error });
             later();
             return;
         }
-        if (stopped || paused)
+        if (stopped || paused || asked !== generation)
             return;
         if (answer === 401 || answer === 403) {
             stopped = true;

package/dist/client/react.js

@@ -54,7 +54,9 @@ export function useEvents(options) {
     const key = keyOf(options);
     // biome-ignore lint/correctness/useExhaustiveDependencies: key is what identifies the stream; the latest callbacks are read through the ref.
     useEffect(() => {
-        const current = latest.current;
+        // onStatus is followed through client.onStatus below (each user's latest callback): passed in
+        // the options too, the opening user's callback of its first render ran a second time per change.
+        const { onStatus: _onStatus, ...current } = latest.current;
         const entry = acquire({
             ...current,
             ...(current.onReload ? { onReload: () => latest.current.onReload?.() } : {}),

package/dist/errors.d.ts

@@ -1,5 +1,5 @@
 import { DokebiError } from '@dokebi/core';
-export type SseErrorCode = 'INVALID_OPTIONS' | 'INVALID_ROUTE' | 'INVALID_IDENTITY' | 'INVALID_EVENT' | 'INVALID_DATA' | 'INVALID_TARGET' | 'INVALID_ROOM' | 'EVENT_TOO_LARGE' | 'ROOM_LIMIT' | 'FROZEN' | 'CLOSED' | 'BUS_UNAVAILABLE' | 'BUS_PUBLISH_FAILED' | 'LOCAL_IN_CLUSTER';
+export type SseErrorCode = 'INVALID_OPTIONS' | 'INVALID_ROUTE' | 'INVALID_IDENTITY' | 'INVALID_EVENT' | 'INVALID_EVENT_ID' | 'INVALID_DATA' | 'INVALID_TARGET' | 'INVALID_ROOM' | 'EVENT_TOO_LARGE' | 'ROOM_LIMIT' | 'FROZEN' | 'CLOSED' | 'BUS_UNAVAILABLE' | 'BUS_PUBLISH_FAILED' | 'LOCAL_IN_CLUSTER';
 /** Errors of @dokebi/sse; compare `code`, not the class (another copy of the package may throw). */
 export declare class SseError extends DokebiError<SseErrorCode> {
     /** BUS_PUBLISH_FAILED: the event id and how many streams of this process already got it. */
@@ -10,5 +10,10 @@ export declare class SseError extends DokebiError<SseErrorCode> {
         readonly id?: string;
         readonly local?: number;
         readonly details?: unknown;
+        /**
+         * A transient bus failure (D-0107 §6): the error answers a retryable 503 with this
+         * Retry-After (`data.retryAfterMs`, options.dokebi-sse.busRetryAfterMs) instead of 500.
+         */
+        readonly retryAfterMs?: number;
     });
 }

package/dist/errors.js

@@ -1,9 +1,10 @@
 import { DokebiError } from '@dokebi/core';
 const FIX = {
     INVALID_OPTIONS: "Correct options.dokebi-sse in dokebi.yaml; details.issues names the paths and the plugin's options.schema.json lists what is allowed.",
-    INVALID_ROUTE: 'Give route a path starting with / (no query), an authenticate function, and optional onOpen/onClose functions, version text, constraints object and origins (* or exact https://host origins).',
+    INVALID_ROUTE: 'Give route a path starting with / (no query), an authenticate function, and optional onOpen/onClose functions, version text, constraints object, origins (* or exact https://host origins) and config ({ id } only, D-0140).',
     INVALID_IDENTITY: 'Return { tenant, member, rooms? } from authenticate, with strings of 1 to 256 characters (or undefined to refuse with 401).',
     INVALID_EVENT: 'Name events with a letter first and up to 64 of A-Z a-z 0-9 . _ : -, not starting with dokebi-.',
+    INVALID_EVENT_ID: 'Give options.id as 1 to 64 of A-Z a-z 0-9 and - (for example a message sequence, String(seq)), or leave it out to let the plugin number the event.',
     INVALID_DATA: 'Send data that JSON.stringify accepts (no BigInt, functions or cycles).',
     INVALID_TARGET: 'Target { tenant, member?, room? } or { tenantPrefix, member?, room? } with strings of 1 to 256 characters.',
     INVALID_ROOM: 'Rooms are strings of 1 to 256 characters.',
@@ -21,11 +22,19 @@ export class SseError extends DokebiError {
     id;
     local;
     constructor(code, message, options) {
+        const retryAfterMs = options?.retryAfterMs;
         super(code, message, {
             plugin: 'dokebi-sse',
             fix: FIX[code],
             ...(options?.cause === undefined ? {} : { cause: options.cause }),
             ...(options?.details === undefined ? {} : { details: options.details }),
+            ...(retryAfterMs === undefined
+                ? {}
+                : {
+                    status: 503,
+                    hint: 'Live updates are busy or down; try again shortly.',
+                    data: { retryAfterMs },
+                }),
         });
         this.name = 'SseError';
         if (options?.id !== undefined)

package/dist/gateway.d.ts

@@ -27,12 +27,21 @@ export declare class Gateway {
     #private;
     readonly context: PluginContext;
     readonly web: WebApi;
-    readonly options: Options;
+    options: Options;
     readonly bus: SseBus | undefined;
+    /** The bus's maxPayloadBytes as the app configuration says now; undefined when unknown. */
+    readonly busPayloadBytes: () => number | undefined;
     readonly api: SseApi;
-    constructor(context: PluginContext, web: WebApi, options: Options, bus: SseBus | undefined, health: SseHealth | undefined);
+    constructor(context: PluginContext, web: WebApi, options: Options, bus: SseBus | undefined, health: SseHealth | undefined, 
+    /** The bus's maxPayloadBytes as the app configuration says now; undefined when unknown. */
+    busPayloadBytes?: () => number | undefined);
     /** Subscribes to the bus (setup): every process on it delivers to its own matching streams. */
     subscribe(): Promise<void>;
+    /**
+     * D-0154: reloaded stream limits (retryMs, maxConnections, maxBufferedBytes, maxEventBytes) for
+     * the next stream or event, and the ping interval (the timer starts again).
+     */
+    reconfigure(next: Options): void;
     start(): void;
     /** Sends `dokebi-restart` to every stream, ends them, and cuts the rest at the deadline. */
     drain(signal: AbortSignal): Promise<void>;