@dokebi/sse 0.4.0 → 0.4.2

package/dist/gateway.js

@@ -1,16 +1,16 @@
 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;
-const key = (tenant, value) => `${tenant}\u0000${value}`;
 function add(map, name, entry) {
     const set = map.get(name);
     if (set)
@@ -26,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.');
@@ -49,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)
@@ -100,11 +130,11 @@ export class Gateway {
     web;
     options;
     bus;
+    busPayloadBytes;
     api;
     #entries = new Map();
+    /** tenant → its streams, by member and by room (see TenantIndex). */
     #tenants = new Map();
-    #members = new Map();
-    #rooms = new Map();
     /** onOpen/onClose calls in progress, awaited by drain (bounded by the drain deadline). */
     #tasks = new Set();
     /** Repeated hot-path events: the first at once, then one summary per interval (D-0047). */
@@ -124,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;
@@ -138,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;
@@ -171,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',
@@ -181,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,
         });
@@ -206,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);
@@ -233,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);
@@ -256,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;
             }
         }
@@ -274,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');
@@ -333,6 +438,7 @@ export class Gateway {
             reason: undefined,
             closed: false,
             stream: undefined,
+            endTimer: undefined,
         };
         entry.stream = Object.freeze({
             id: entry.id,
@@ -347,18 +453,24 @@ 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)),
             close: () => this.#end(entry, 'SERVER_CLOSED'),
         });
         this.#entries.set(entry.id, entry);
-        add(this.#tenants, entry.tenant, entry);
-        add(this.#members, key(entry.tenant, entry.member), entry);
+        let index = this.#tenants.get(entry.tenant);
+        if (!index) {
+            index = { all: new Set(), members: new Map(), rooms: new Map() };
+            this.#tenants.set(entry.tenant, index);
+        }
+        index.all.add(entry);
+        add(index.members, entry.member, entry);
         for (const room of rooms)
             this.#join(entry, room);
         return entry;
@@ -368,8 +480,10 @@ export class Gateway {
             return;
         if (entry.rooms.size >= this.options.maxRooms)
             throw new SseError('ROOM_LIMIT', `A stream may be in ${this.options.maxRooms} rooms.`);
+        // An open entry is always indexed under its tenant (#add before any join, #closed after).
+        const index = this.#tenants.get(entry.tenant);
         entry.rooms.add(room);
-        add(this.#rooms, key(entry.tenant, room), entry);
+        add(index.rooms, room, entry);
         if (this.context.logger.isEnabled('debug'))
             this.context.logger.log('debug', 'SSE room joined', {
                 stream: entry.id,
@@ -380,7 +494,9 @@ export class Gateway {
     #leave(entry, room) {
         if (!entry.rooms.delete(room))
             return;
-        remove(this.#rooms, key(entry.tenant, room), entry);
+        const index = this.#tenants.get(entry.tenant);
+        if (index)
+            remove(index.rooms, room, entry);
         if (this.context.logger.isEnabled('debug'))
             this.context.logger.log('debug', 'SSE room left', {
                 stream: entry.id,
@@ -417,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) {
@@ -437,22 +564,66 @@ 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);
-        remove(this.#tenants, entry.tenant, entry);
-        remove(this.#members, key(entry.tenant, entry.member), entry);
-        for (const room of entry.rooms)
-            remove(this.#rooms, key(entry.tenant, room), entry);
+        const index = this.#tenants.get(entry.tenant);
+        if (index) {
+            index.all.delete(entry);
+            remove(index.members, entry.member, entry);
+            for (const room of entry.rooms)
+                remove(index.rooms, room, entry);
+            if (!index.all.size)
+                this.#tenants.delete(entry.tenant);
+        }
         if (this.context.logger.isEnabled('debug'))
             this.context.logger.log('debug', 'SSE stream closed', {
                 stream: entry.id,
@@ -480,11 +651,14 @@ export class Gateway {
         return task.finally(() => this.#tasks.delete(task));
     }
     #select(target) {
+        const index = this.#tenants.get(target.tenant);
+        if (!index)
+            return undefined;
         if (target.room !== undefined)
-            return this.#rooms.get(key(target.tenant, target.room));
+            return index.rooms.get(target.room);
         if (target.member !== undefined)
-            return this.#members.get(key(target.tenant, target.member));
-        return this.#tenants.get(target.tenant);
+            return index.members.get(target.member);
+        return index.all;
     }
     /** Writes one event to the matching streams of this process; returns how many took it. */
     #deliver(target, event, id, json) {
@@ -493,8 +667,14 @@ export class Gateway {
             let written = 0;
             const shared = { id, event, json, chunk: undefined };
             for (const tenant of [...this.#tenants.keys()])
-                if (tenant.startsWith(target.tenantPrefix))
-                    written += this.#writeAll(this.#select({ ...target, tenant }), target, shared);
+                if (tenant.startsWith(target.tenantPrefix)) {
+                    const exact = {
+                        tenant,
+                        ...(target.member === undefined ? {} : { member: target.member }),
+                        ...(target.room === undefined ? {} : { room: target.room }),
+                    };
+                    written += this.#writeAll(this.#select(exact), exact, shared);
+                }
             return written;
         }
         const set = this.#select(target);
@@ -504,14 +684,22 @@ export class Gateway {
     }
     /**
      * Plain streams share one buffer, made at the first plain recipient; sealed streams each get
-     * their own frame (D-0062, like sealed WebSocket broadcasts).
+     * their own frame (D-0062, like sealed WebSocket broadcasts). Every candidate is checked against
+     * the whole target, tenant first, right before the write: the index narrows, it never decides
+     * alone who gets an event (ISSUE-0006 A01).
      */
     #writeAll(set, target, shared) {
         let written = 0;
         for (const entry of set ?? []) {
-            if (target.room !== undefined &&
-                target.member !== undefined &&
-                entry.member !== target.member)
+            if (entry.tenant !== target.tenant) {
+                // Unreachable while the index is right; a defect, never a reason to cross tenants.
+                this.#throttle.log('error', 'SSE index returned a stream of another tenant; skipped', 'SSE_INDEX_MISMATCH', undefined, { stream: entry.id, path: entry.route.path });
+                continue;
+            }
+            // #select picked the room (or member) index; the rest of the target narrows here.
+            if (target.member !== undefined && entry.member !== target.member)
+                continue;
+            if (target.room !== undefined && !entry.rooms.has(target.room))
                 continue;
             if (!entry.seal)
                 shared.chunk ??= Buffer.from(frame(shared.id, shared.event, shared.json));
@@ -520,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 {
@@ -554,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'))
@@ -571,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;
@@ -624,7 +839,8 @@ export class Gateway {
         }
         let count = 0;
         for (const entry of set)
-            if ((filter.member === undefined || entry.member === filter.member) &&
+            if ((filter.tenant === undefined || entry.tenant === filter.tenant) &&
+                (filter.member === undefined || entry.member === filter.member) &&
                 (filter.room === undefined || entry.rooms.has(filter.room)) &&
                 (filter.path === undefined || entry.route.path === filter.path))
                 count++;
@@ -653,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
@@ -711,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;
 }>;