@dokebi/sse 0.4.1 → 0.4.2

package/dist/gateway.js

@@ -1,14 +1,15 @@
 import { randomBytes, randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
 import { diagnostics } from '@dokebi/core/libraries';
+// D-0089: the before-hijack steps (the session save, auth cookies) of @dokebi/web, run before the head.
+import { runBeforeHijack } from '@dokebi/web/points';
 import { SseError } from './errors.js';
+import { transientBusFailure } from './retry.js';
 import { OPEN_EVENT, RELOAD_EVENT, RESTART_EVENT, } from './types.js';
 import { checkEvent, EVENT, encodeData, frame, HEADERS, ID, isLine, PING } from './wire.js';
-/** A client that ignores `dokebi-reload` comes back this slowly (EventSource honours `retry:`). */
-const RELOAD_RETRY_MS = 60_000;
-/** How often the bus state is read for health and the warn/info log of a change. */
-const BUS_WATCH_MS = 1000;
 const MAX_TEXT = 256;
+/** Room for everything of a bus message but its data: the target (3 x 256 characters, escaped), ids. */
+const ENVELOPE_ROOM = 8192;
 const text = (value) => typeof value === 'string' && value.length > 0 && value.length <= MAX_TEXT;
 function add(map, name, entry) {
     const set = map.get(name);
@@ -25,6 +26,19 @@ function remove(map, name, entry) {
     if (!set.size)
         map.delete(name);
 }
+/** The app's own event id (`options.id`), checked; undefined lets the plugin number the event. */
+function eventId(options) {
+    if (options === undefined)
+        return undefined;
+    if (options === null || typeof options !== 'object')
+        throw new SseError('INVALID_EVENT_ID', 'Send options are an object such as { id: "42" }.');
+    const { id } = options;
+    if (id === undefined)
+        return undefined;
+    if (typeof id !== 'string' || !ID.test(id))
+        throw new SseError('INVALID_EVENT_ID', 'An event id is 1 to 64 of A-Z a-z 0-9 and -.');
+    return id;
+}
 function checkRoom(room) {
     if (!text(room))
         throw new SseError('INVALID_ROOM', 'Rooms are strings of 1 to 256 characters.');
@@ -48,6 +62,23 @@ function checkTarget(target) {
         ...(value.room === undefined ? {} : { room: value.room }),
     });
 }
+/**
+ * The route config (D-0140): `{ id }` only, handed to dokebi-web as the Fastify route config.
+ * The id value is checked by dokebi-web at start, the same check as a web route's (one rule).
+ */
+function parseConfig(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === null || typeof value !== 'object' || Array.isArray(value))
+        throw new SseError('INVALID_ROUTE', "SSE route config is an object such as { id: 'live' }.");
+    const values = value;
+    const keys = Object.keys(values).filter((key) => values[key] !== undefined);
+    const other = keys.find((key) => key !== 'id');
+    if (other !== undefined)
+        throw new SseError('INVALID_ROUTE', `SSE route config takes only id, not ${JSON.stringify(other.slice(0, 64))}.`);
+    // Typed as the route config declares it; a value that is not a valid id fails the start.
+    return keys.length ? Object.freeze({ id: values.id }) : undefined;
+}
 /** Allow-list entries must be exact http(s) origins such as `https://app.example.com`. */
 function parseOrigins(value) {
     if (value === undefined)
@@ -99,6 +130,7 @@ export class Gateway {
     web;
     options;
     bus;
+    busPayloadBytes;
     api;
     #entries = new Map();
     /** tenant → its streams, by member and by room (see TenantIndex). */
@@ -122,12 +154,18 @@ export class Gateway {
     #subscription;
     #health;
     #busUp;
-    constructor(context, web, options, bus, health) {
+    constructor(context, web, options, bus, health, 
+    /** The bus's maxPayloadBytes as the app configuration says now; undefined when unknown. */
+    busPayloadBytes = () => undefined) {
         this.context = context;
         this.web = web;
         this.options = options;
         this.bus = bus;
-        this.#throttle = new diagnostics.Repeats({ logger: context.logger });
+        this.busPayloadBytes = busPayloadBytes;
+        this.#throttle = new diagnostics.Repeats({
+            logger: context.logger,
+            intervalMs: this.options.logRepeatWindowMs,
+        });
         if (health) {
             this.#health = health.register('sse', { required: false });
             const handle = this.#health;
@@ -136,7 +174,7 @@ export class Gateway {
         const self = this;
         this.api = Object.freeze({
             route: (route) => this.#route(route),
-            publish: (target, event, data) => this.#publish(target, event, data),
+            publish: (target, event, data, options) => this.#publish(target, event, data, options),
             connections: (filter) => this.#count(filter),
             get bus() {
                 return self.options.eventBus;
@@ -169,9 +207,11 @@ export class Gateway {
             (route.constraints !== undefined &&
                 (typeof route.constraints !== 'object' || route.constraints === null)))
             throw new SseError('INVALID_ROUTE', 'Invalid SSE route.');
+        const config = parseConfig(route.config);
         const registered = {
             route: Object.freeze({ ...route }),
             origins: parseOrigins(route.origins),
+            id: typeof config?.id === 'string' ? config.id : null,
         };
         this.web.route({
             method: 'GET',
@@ -179,11 +219,14 @@ export class Gateway {
             // A HEAD request would open a stream whose body Node discards: answer only GET.
             exposeHeadRoute: false,
             ...(route.constraints ? { constraints: { ...route.constraints } } : {}),
+            // D-0140: dokebi-web records and checks `config.id` (describe, duplicates, route hooks).
+            ...(config ? { config: { ...config } } : {}),
             handler: (request, reply) => this.#open(request, reply, registered),
         });
         this.#routes++;
         this.context.logger.log('debug', 'SSE route registered', {
             path: route.path,
+            routeId: registered.id,
             version: route.version ?? null,
             origins: registered.origins === '*' ? '*' : registered.origins ? registered.origins.size : null,
         });
@@ -204,23 +247,48 @@ export class Gateway {
             if (logger.isEnabled('debug'))
                 logger.log('debug', 'SSE origin refused', {
                     path: route.path,
+                    routeId: registered.id,
                     origin: String(request.headers.origin).slice(0, 200),
                 });
             return reply.code(403).send({ error: 'ORIGIN_FORBIDDEN' });
         }
+        // A listed foreign origin reads the refusals too: the browser client's probe is a
+        // credentialed cross-origin fetch, and without these headers the browser turns a 401 into a
+        // network error, so the client would reconnect forever instead of stopping.
+        const refuse = (status, body, headers = {}) => reply
+            .code(status)
+            .headers({ ...allowed, ...headers })
+            .send(body);
         let refused = this.#refusal();
         if (refused) {
-            logger.log('debug', 'SSE stream refused', { path: route.path, reason: refused });
-            return reply
-                .code(503)
-                .header('retry-after', '5')
-                .send({ error: 'UNAVAILABLE', reason: refused });
+            logger.log('debug', 'SSE stream refused', {
+                path: route.path,
+                routeId: registered.id,
+                reason: refused,
+            });
+            return refuse(503, { error: 'UNAVAILABLE', reason: refused }, { 'retry-after': '5' });
         }
         const identity = await route.authenticate(request);
-        if (!identity) {
+        let revoked;
+        try {
+            revoked = identity?.authorization?.valid() === false;
+        }
+        catch (error) {
+            // As on every write (#write): a lease that cannot answer is a server failure, not a 401
+            // (which would stop the browser client for good).
+            this.#throttle.log('error', 'SSE authorization failed', 'SSE_AUTHORIZATION_FAILED', error, {
+                path: route.path,
+                routeId: registered.id,
+            });
+            return refuse(500, { error: 'AUTHORIZATION_FAILED' });
+        }
+        if (!identity || revoked) {
             if (logger.isEnabled('debug'))
-                logger.log('debug', 'SSE stream unauthorized', { path: route.path });
-            return reply.code(401).send({ error: 'UNAUTHORIZED' });
+                logger.log('debug', 'SSE stream unauthorized', {
+                    path: route.path,
+                    routeId: registered.id,
+                });
+            return refuse(401, { error: 'UNAUTHORIZED' });
         }
         // An invalid identity is an application bug: dokebi-web answers 500 and logs it.
         const rooms = this.#identity(identity);
@@ -231,16 +299,45 @@ export class Gateway {
                 .code(204)
                 .headers(allowed ?? {})
                 .send();
+        // The reply is hijacked below, so Fastify writes none of its headers and runs no onSend hook:
+        // the session save and auth cookies happen now (D-0089), or the stream is refused.
+        const started = performance.now();
+        let committed;
+        try {
+            const timeoutMs = this.options.beforeStreamTimeoutMs;
+            const waiting = runBeforeHijack(request, reply, timeoutMs, () => new Error(`Work before the stream did not finish within ${timeoutMs} ms (beforeStreamTimeoutMs)`));
+            if (waiting)
+                committed = await waiting;
+        }
+        catch (error) {
+            this.#throttle.log('error', 'SSE stream refused: saving the request state failed', 'SSE_COMMIT_FAILED', error, { path: route.path });
+            return refuse(500, { error: 'COMMIT_FAILED' });
+        }
+        if (committed !== undefined && logger.isEnabled('debug'))
+            logger.log('debug', 'SSE request state saved before the stream', {
+                path: route.path,
+                steps: committed,
+                ms: Math.round(performance.now() - started),
+            });
         refused = this.#refusal();
         if (refused) {
-            logger.log('debug', 'SSE stream refused', { path: route.path, reason: refused });
-            return reply
-                .code(503)
-                .header('retry-after', '5')
-                .send({ error: 'UNAVAILABLE', reason: refused });
+            logger.log('debug', 'SSE stream refused', {
+                path: route.path,
+                routeId: registered.id,
+                reason: refused,
+            });
+            return refuse(503, { error: 'UNAVAILABLE', reason: refused }, { 'retry-after': '5' });
         }
         const res = reply.raw;
-        const headers = { ...HEADERS, ...allowed };
+        // Set-Cookie on the reply (authenticate, a hook, the steps above) goes out with the stream.
+        const cookies = reply.getHeader('set-cookie');
+        const headers = {
+            ...HEADERS,
+            ...allowed,
+            ...(cookies === undefined
+                ? {}
+                : { 'set-cookie': typeof cookies === 'number' ? String(cookies) : cookies }),
+        };
         // D-0062: a stream of a seal host seals the data of every event, its first ones included.
         const seal = this.web.sealOf(request);
         const data = (json) => (seal ? seal.encode(json) : json);
@@ -254,7 +351,7 @@ export class Gateway {
                 });
                 reply.hijack();
                 res.writeHead(200, headers);
-                res.end(`retry: ${RELOAD_RETRY_MS}\n${frame(undefined, RELOAD_EVENT, data(JSON.stringify({ version: route.version })))}`);
+                res.end(`retry: ${this.options.reloadRetryMs}\n${frame(undefined, RELOAD_EVENT, data(JSON.stringify({ version: route.version })))}`);
                 return;
             }
         }
@@ -272,6 +369,16 @@ export class Gateway {
         res.write(`retry: ${this.options.retryMs}\n${frame(undefined, OPEN_EVENT, data(JSON.stringify({ retryMs: this.options.retryMs })))}`);
         const entry = this.#add(res, identity, route, rooms, lastEventId, seal);
         res.once('close', () => this.#closed(entry));
+        if (identity.authorization) {
+            // A lease that cannot be subscribed to could not be revoked later: the stream ends now.
+            try {
+                entry.unsubscribeAuthorization = identity.authorization.subscribe(() => this.#end(entry, 'SERVER_CLOSED'));
+            }
+            catch (error) {
+                this.#throttle.log('error', 'SSE authorization subscription failed; stream ended', 'SSE_AUTHORIZATION_FAILED', error, { path: route.path, stream: entry.id });
+                this.#end(entry, 'SERVER_CLOSED');
+            }
+        }
         res.on('error', (error) => {
             entry.reason ??= 'WRITE_FAILED';
             const code = diagnostics.errorCode(error, 'UNKNOWN');
@@ -331,6 +438,7 @@ export class Gateway {
             reason: undefined,
             closed: false,
             stream: undefined,
+            endTimer: undefined,
         };
         entry.stream = Object.freeze({
             id: entry.id,
@@ -345,10 +453,11 @@ export class Gateway {
             get closed() {
                 return entry.closed || entry.reason !== undefined;
             },
-            send: (event, data) => {
+            send: (event, data, options) => {
                 checkEvent(event);
+                const id = eventId(options) ?? this.#nextId();
                 const json = encodeData(data, this.options.maxEventBytes);
-                return this.#event(entry, this.#nextId(), event, json);
+                return this.#event(entry, id, event, json);
             },
             join: (room) => this.#join(entry, checkRoom(room)),
             leave: (room) => this.#leave(entry, checkRoom(room)),
@@ -424,6 +533,17 @@ export class Gateway {
     #write(entry, chunk) {
         if (entry.closed || entry.reason !== undefined)
             return false;
+        try {
+            if (entry.identity.authorization?.valid() === false) {
+                this.#end(entry, 'SERVER_CLOSED');
+                return false;
+            }
+        }
+        catch (error) {
+            this.#throttle.log('error', 'SSE authorization failed', 'SSE_AUTHORIZATION_FAILED', error);
+            this.#end(entry, 'SERVER_CLOSED');
+            return false;
+        }
         const res = entry.res;
         // ServerResponse.writableLength counts what waits in the response and in its socket.
         if (res.writableLength + chunk.byteLength > this.options.maxBufferedBytes) {
@@ -444,15 +564,54 @@ export class Gateway {
         if (entry.closed || entry.reason !== undefined)
             return;
         entry.reason = reason;
-        if (destroy)
+        if (destroy) {
             entry.res.destroy();
-        else
-            entry.res.end();
+            return;
+        }
+        entry.res.end();
+        // end() sends its last chunk behind the bytes still waiting; a client that stopped reading
+        // never takes them, so 'close' would not come and the stream would keep its slot. Bounded.
+        if (entry.closed)
+            return;
+        const endTimeoutMs = this.options.endTimeoutMs;
+        entry.endTimer = setTimeout(() => {
+            entry.endTimer = undefined;
+            if (entry.closed)
+                return;
+            this.#throttle.log('warn', 'SSE ended stream destroyed; client not reading', 'STREAM_END_TIMEOUT', undefined, {
+                stream: entry.id,
+                path: entry.route.path,
+                reason,
+                bufferedBytes: entry.res.writableLength,
+                endTimeoutMs,
+            });
+            entry.res.destroy();
+        }, endTimeoutMs);
+        entry.endTimer.unref();
+        if (this.context.logger.isEnabled('debug'))
+            this.context.logger.log('debug', 'SSE stream ending', {
+                stream: entry.id,
+                reason,
+                bufferedBytes: entry.res.writableLength,
+                endTimeoutMs,
+            });
     }
     #closed(entry) {
         if (entry.closed)
             return;
         entry.closed = true;
+        if (entry.endTimer) {
+            clearTimeout(entry.endTimer);
+            entry.endTimer = undefined;
+        }
+        // A failing unsubscribe must not keep the stream indexed (it would count against
+        // maxConnections) nor escape from the response's 'close' event.
+        try {
+            entry.unsubscribeAuthorization?.();
+        }
+        catch (error) {
+            this.#throttle.log('error', 'SSE authorization unsubscribe failed', 'SSE_AUTHORIZATION_FAILED', error, { path: entry.route.path, stream: entry.id });
+        }
         const reason = entry.reason ?? 'CLIENT_CLOSED';
         entry.reason = reason;
         this.#entries.delete(entry.id);
@@ -549,22 +708,26 @@ export class Gateway {
         }
         return written;
     }
-    async #publish(target, event, data) {
+    async #publish(target, event, data, options) {
         if (this.#shut)
             throw new SseError('CLOSED', 'dokebi-sse is closed: the application has stopped.');
         const checked = checkTarget(target);
         checkEvent(event);
+        const chosen = eventId(options);
         const json = encodeData(data, this.options.maxEventBytes);
         const bus = this.bus;
         if (bus && bus.state !== 'ready') {
-            const error = new SseError('BUS_UNAVAILABLE', `Event bus ${this.options.eventBus} is ${bus.state}; the event was not sent.`);
+            // Transient: the request may pass once the bus is back (503 + Retry-After, D-0107 §6).
+            const error = new SseError('BUS_UNAVAILABLE', `Event bus ${this.options.eventBus} is ${bus.state}; the event was not sent.`, { retryAfterMs: this.options.busRetryAfterMs.unavailable });
             this.#throttle.log('error', 'SSE publish refused; bus unavailable', 'BUS_UNAVAILABLE', error, {
                 bus: this.options.eventBus,
                 state: bus.state,
             });
             throw error;
         }
-        const id = this.#nextId();
+        const id = chosen ?? this.#nextId();
+        if (bus)
+            this.#checkBusSize(checked, event, id, json);
         const local = this.#closing ? 0 : this.#deliver(checked, event, id, json);
         if (bus) {
             try {
@@ -583,8 +746,16 @@ export class Gateway {
                     id,
                     local,
                     busCode: diagnostics.errorCode(cause, 'UNKNOWN'),
+                    transient: transientBusFailure(cause) ?? false,
+                });
+                // A full or down bus is transient (503 + Retry-After); anything else stays 500 (D-0107 §6).
+                const transient = transientBusFailure(cause);
+                throw new SseError('BUS_PUBLISH_FAILED', 'The event reached this process, but publishing it on the bus failed; other processes may not have it.', {
+                    cause,
+                    id,
+                    local,
+                    ...(transient ? { retryAfterMs: this.options.busRetryAfterMs[transient] } : {}),
                 });
-                throw new SseError('BUS_PUBLISH_FAILED', 'The event reached this process, but publishing it on the bus failed; other processes may not have it.', { cause, id, local });
             }
         }
         if (this.context.logger.isEnabled('debug'))
@@ -600,6 +771,21 @@ export class Gateway {
             });
         return Object.freeze({ id, local });
     }
+    /**
+     * The bus message (the data JSON inside a JSON envelope, escaped again) must fit the bus's
+     * maxPayloadBytes, or the bus refuses it after this process already wrote the event: refused
+     * here instead, before any stream gets it (EVENT_TOO_LARGE). Measured only when the data could
+     * be too large (escaping at most doubles it), so the usual event costs nothing more.
+     */
+    #checkBusSize(target, event, id, json) {
+        const limit = this.busPayloadBytes();
+        if (limit === undefined || 2 * Buffer.byteLength(json) + ENVELOPE_ROOM <= limit)
+            return;
+        const bytes = Buffer.byteLength(JSON.stringify({ v: 1, id, origin: this.#origin, target, event, data: json }));
+        if (bytes <= limit)
+            return;
+        throw new SseError('EVENT_TOO_LARGE', `The event's bus message is ${bytes} bytes; the event bus takes ${limit} (maxPayloadBytes). Nothing was sent.`);
+    }
     /** A publication from the bus: delivered here unless this process published it. */
     #fromBus(payload) {
         const message = payload;
@@ -683,16 +869,36 @@ export class Gateway {
             });
         }
     }
-    start() {
-        this.#frozen = true;
+    #ping() {
         this.#heartbeat = setInterval(() => {
             for (const entry of this.#entries.values())
                 this.#write(entry, PING);
         }, this.options.heartbeatMs);
         this.#heartbeat.unref();
+    }
+    /**
+     * 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) {
+        const restart = this.#heartbeat !== undefined && next.heartbeatMs !== this.options.heartbeatMs;
+        this.options = next;
+        if (restart) {
+            clearInterval(this.#heartbeat);
+            this.#ping();
+        }
+        this.context.logger.log('debug', 'SSE options reloaded', {
+            code: 'SSE_RELOADED',
+            heartbeatMs: next.heartbeatMs,
+            maxConnections: next.maxConnections,
+        });
+    }
+    start() {
+        this.#frozen = true;
+        this.#ping();
         if (this.bus) {
             this.#busState();
-            this.#watch = setInterval(() => this.#busState(), BUS_WATCH_MS);
+            this.#watch = setInterval(() => this.#busState(), this.options.busWatchIntervalMs);
             this.#watch.unref();
         }
         else
@@ -741,7 +947,9 @@ export class Gateway {
             for (const entry of this.#entries.values())
                 entry.res.destroy();
         }
-        while (this.#tasks.size && !signal.aborted)
+        // A destroyed response emits 'close' later, and only then is its onClose a task: wait for
+        // the streams to be gone as well as for the tasks, or a cut stream's onClose outlives drain.
+        while ((this.#entries.size || this.#tasks.size) && !signal.aborted)
             await delay(10);
         this.#throttle.flush();
         logger.log('debug', 'SSE drain finished', {

package/dist/options.d.ts

@@ -22,16 +22,46 @@ export interface Options {
     readonly maxEventBytes: number;
     /** How long drain waits for streams to end after `dokebi-restart` before cutting them. */
     readonly shutdownTimeoutMs: number;
+    /**
+     * How long a stream the server ended may take to send what it still holds before it is
+     * destroyed (a client that stopped reading would otherwise keep its slot, D-0107 §2).
+     */
+    readonly endTimeoutMs: number;
+    /**
+     * The Retry-After of the 503 a route answers when a publish fails because the bus is full
+     * (`busy`, SSE_BUS_BUSY) or down or draining (`unavailable`, SSE_BUS_UNAVAILABLE), D-0107 §6.
+     */
+    readonly busRetryAfterMs: {
+        readonly busy: number;
+        readonly unavailable: number;
+    };
+    /** The longest wait for the work before a stream (a session save), D-0114. */
+    readonly beforeStreamTimeoutMs: number;
+    /** The `retry:` of the `dokebi-reload` frame (a client that ignores it reconnects this slowly). */
+    readonly reloadRetryMs: number;
+    /** How often the bus state is read for health and its log. */
+    readonly busWatchIntervalMs: number;
+    /** Window of the repeated stream failure logs. */
+    readonly logRepeatWindowMs: number;
 }
 export declare const options: import("@dokebi/core").OptionsDeclaration<{
     readonly allowInCluster: boolean;
+    readonly beforeStreamTimeoutMs: number;
     readonly busEvent: string;
+    readonly busRetryAfterMs: {
+        readonly busy: number;
+        readonly unavailable: number;
+    };
+    readonly busWatchIntervalMs: number;
+    readonly endTimeoutMs: number;
     readonly eventBus?: string;
     readonly heartbeatMs: number;
+    readonly logRepeatWindowMs: number;
     readonly maxBufferedBytes: number;
     readonly maxConnections: number;
     readonly maxEventBytes: number;
     readonly maxRooms: number;
+    readonly reloadRetryMs: number;
     readonly retryMs: number;
     readonly shutdownTimeoutMs: number;
 }>;

package/dist/options.js

@@ -1,6 +1,8 @@
 import { defineOptions, option as o } from '@dokebi/core';
 import { SseError } from './errors.js';
-const int = (minimum, maximum, fallback, description) => o.integer({ minimum, maximum, default: fallback, description });
+const int = (minimum, maximum, fallback, description, more = {}) => o.integer({ minimum, maximum, default: fallback, description, ...more });
+/** D-0154: applied while the app runs (read per stream or per event; the ping timer restarts). */
+const live = { reloadable: true };
 /*
  * Options of dokebi-sse (D-0063 §3): one declaration is the parser and, at build time,
  * options.schema.json.
@@ -22,14 +24,26 @@ export const options = defineOptions({
         default: false,
         description: 'Start in a node:cluster worker without a nats bus (a deliberate single-worker cluster). Otherwise that start fails with LOCAL_IN_CLUSTER. The bus driver is read from dokebi-event-bus.buses in the application config.',
     }),
-    retryMs: int(100, 3_600_000, 3000, "The retry: hint (browser reconnect delay), also the browser client's minimum backoff."),
-    heartbeatMs: int(10, 3_600_000, 15000, "How often a ': ping' comment is written to every stream. Proxy idle timeouts must be longer."),
-    maxConnections: int(1, 1_000_000, 1024, 'Open streams per process (per cluster worker); more get 503 CAPACITY.'),
-    maxBufferedBytes: int(1, 67_108_864, 1_048_576, 'Bytes a stream may have waiting to be sent; past it the stream is ended (warn SLOW_CONSUMER).'),
+    retryMs: int(100, 3_600_000, 3000, "The retry: hint (browser reconnect delay), also the browser client's minimum backoff.", live),
+    heartbeatMs: int(10, 3_600_000, 15000, "How often a ': ping' comment is written to every stream. Proxy idle timeouts must be longer.", live),
+    maxConnections: int(1, 1_000_000, 1024, 'Open streams per process (per cluster worker); more get 503 CAPACITY.', live),
+    maxBufferedBytes: int(1, 67_108_864, 1_048_576, 'Bytes a stream may have waiting to be sent; past it the stream is ended (warn SLOW_CONSUMER).', live),
     maxRooms: int(0, 1024, 32, 'Rooms one stream may be in.'),
-    maxEventBytes: int(1, 16_777_216, 65_536, 'Largest JSON data of one event in bytes (EVENT_TOO_LARGE). Keep it below the bus maxPayloadBytes.'),
+    maxEventBytes: int(1, 16_777_216, 65_536, 'Largest JSON data of one event in bytes (EVENT_TOO_LARGE). Keep it below the bus maxPayloadBytes.', live),
     shutdownTimeoutMs: int(1, 600_000, 2000, 'How long drain waits for streams to end after dokebi-restart before cutting them.'),
     closeTimeoutMs: o.alias('shutdownTimeoutMs'),
+    endTimeoutMs: int(1, 600_000, 5000, 'How long a stream the server ended (stream.close(), revoked authorization, drain) may take to send its waiting bytes before it is destroyed (warn STREAM_END_TIMEOUT); frees the slot of a client that stopped reading.'),
+    busRetryAfterMs: o.object({
+        busy: int(1000, 3_600_000, 1000, 'Retry-After (ms, sent in whole seconds) of the 503 SSE_BUS_BUSY: the bus refused a publication at its pending limit.'),
+        unavailable: int(1000, 3_600_000, 5000, 'Retry-After (ms, sent in whole seconds) of the 503 SSE_BUS_UNAVAILABLE: the bus or its NATS connection is down or draining.'),
+    }, {
+        default: { busy: 1000, unavailable: 5000 },
+        description: 'Retry-After of the retryable 503 a route answers when a publish fails for a transient bus reason (D-0107); size it near how long the bus takes to recover.',
+    }),
+    beforeStreamTimeoutMs: int(100, 600_000, 5000, 'The longest wait for the work that must finish before a stream starts (the session save and auth cookies, D-0089); slower refuses the stream with 500 COMMIT_FAILED (D-0114).'),
+    reloadRetryMs: int(100, 86_400_000, 60_000, 'The retry: sent with dokebi-reload (a route whose version changed): a client that ignores the reload reconnects this slowly (D-0114).'),
+    busWatchIntervalMs: int(100, 60_000, 1000, 'How often the event bus state is read for the health check and its warn/info log; a bus outage shows within this long (D-0114).'),
+    logRepeatWindowMs: int(1000, 3_600_000, 10_000, 'Window of the repeated stream failure logs (a failed before-stream step, a failed write) in ms: the first is logged in full, the rest of the window are counted (D-0114).'),
 });
 /**
  * Validates the plugin options (no accessors or Proxies are evaluated) and fills in defaults.

package/dist/plugin.js

@@ -1,12 +1,19 @@
 import { definePlugin, optionalDependency, providerDependency, } from '@dokebi/core';
-// Always installed with this plugin (peer, required in the manifest): the provider's own file
-// holds the name, package and range (D-0063 §6).
-import { dependency as web } from '@dokebi/web/dependency';
 import { realtime } from '@dokebi/web/points';
 import { SseError } from './errors.js';
 import { Gateway } from './gateway.js';
 import { options as declaration } from './options.js';
 import { sseTransport } from './transport.js';
+/**
+ * dokebi-web 0.4.3 or later: the shared before-hijack steps (`@dokebi/web/points`). A local
+ * descriptor instead of '@dokebi/web/dependency' (whose range stays ^0.4.0), as in dokebi-auth.
+ */
+const web = providerDependency({
+    name: 'dokebi-web',
+    version: '^0.4.3',
+    packageName: '@dokebi/web',
+    load: () => import('@dokebi/web'),
+});
 /** Only when `bus` is set; created from `app.config['dokebi-event-bus']` when not registered. */
 const events = providerDependency({
     name: 'dokebi-event-bus',
@@ -26,6 +33,18 @@ function configuredDriver(config, bus) {
     const driver = value?.driver ?? value?.transport;
     return typeof driver === 'string' ? driver : undefined;
 }
+/**
+ * The maxPayloadBytes of a bus as the application config says (default 1048576 when the bus is
+ * configured without it); undefined when the bus options were given in code only.
+ */
+function configuredPayloadBytes(config, bus) {
+    const options = config?.['dokebi-event-bus'];
+    const value = options?.buses?.[bus];
+    if (value === undefined || value === null || typeof value !== 'object')
+        return undefined;
+    const bytes = value.maxPayloadBytes;
+    return bytes === undefined ? 1_048_576 : typeof bytes === 'number' ? bytes : undefined;
+}
 class SseRuntime {
     options;
     #gateway;
@@ -57,7 +76,11 @@ class SseRuntime {
         const bus = options.eventBus === undefined
             ? undefined
             : context.getDependency(events).bus(options.eventBus);
-        const gateway = new Gateway(context, context.getDependency(web), options, bus, context.getOptionalDependency(health));
+        const gateway = new Gateway(context, context.getDependency(web), options, bus, context.getOptionalDependency(health), 
+        // Read at each check: the bus limit reloads (D-0154).
+        options.eventBus === undefined
+            ? undefined
+            : () => configuredPayloadBytes(context.app.config, options.eventBus));
         context.defer(() => gateway.close());
         this.#gateway = gateway;
         await gateway.subscribe();
@@ -74,6 +97,11 @@ class SseRuntime {
     start() {
         this.#gateway?.start();
     }
+    /** D-0154: the stream limits and the ping interval (see Gateway.reconfigure). */
+    reload({ options }) {
+        const next = Object.freeze({ ...options, eventBus: options.eventBus });
+        return { apply: () => this.#gateway?.reconfigure(next) };
+    }
     async drain(context) {
         await this.#gateway?.drain(context.drainSignal);
     }
@@ -81,8 +109,8 @@ class SseRuntime {
 /** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-sse']`. */
 export const createPlugin = definePlugin({
     name: 'dokebi-sse',
-    version: '0.4.1',
-    core: '^0.4.0',
+    version: '0.4.2',
+    core: '^0.4.2',
     // The declaration (not parseOptions) so core logs OPTION_DEPRECATED for old keys (bus, closeTimeoutMs).
     options: declaration,
     contributes: [realtime],

package/dist/retry.d.ts

@@ -0,0 +1 @@
+export declare function transientBusFailure(cause: unknown): 'busy' | 'unavailable' | undefined;