@dokebi/sse 0.4.0 → 0.4.2

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.0',
-    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;

package/dist/retry.js

@@ -0,0 +1,25 @@
+/**
+ * Which failures of the event bus may pass when the request is retried (D-0107 §6): the bus
+ * refused at its pending limit (`busy`), or the bus or its NATS connection is down, closed or
+ * draining (`unavailable`). Recognised by `plugin` and `code` (another copy of the package
+ * counts). Anything else (an invalid payload or event name) is a defect and answers 500.
+ */
+const BUSY = new Set(['OVERLOADED']);
+const UNAVAILABLE = new Set([
+    'TRANSPORT_FAILED',
+    'DEPENDENCY_UNAVAILABLE',
+    'BUS_DRAINING',
+    'CLOSED',
+]);
+export function transientBusFailure(cause) {
+    if (cause === null || typeof cause !== 'object')
+        return undefined;
+    const { plugin, code } = cause;
+    if (plugin !== 'dokebi-event-bus' || typeof code !== 'string')
+        return undefined;
+    if (BUSY.has(code))
+        return 'busy';
+    if (UNAVAILABLE.has(code))
+        return 'unavailable';
+    return undefined;
+}

package/dist/transport.js

@@ -21,7 +21,10 @@ export function sseTransport(api, logger) {
                 },
             });
             if (logger.isEnabled('debug'))
-                logger.log('debug', 'SSE route mounted by the realtime point', { path: scope.path });
+                logger.log('debug', 'SSE route mounted by the realtime point', {
+                    path: scope.path,
+                    routeId: typeof route.config?.id === 'string' ? route.config.id : null,
+                });
         },
         handle(namespace) {
             if (typeof namespace !== 'string' || !NAMESPACE.test(namespace))
@@ -29,7 +32,7 @@ export function sseTransport(api, logger) {
             const prefix = `${namespace}:`;
             return Object.freeze({
                 namespace,
-                publish: (target, event, data) => {
+                publish: (target, event, data, options) => {
                     if (target === null || typeof target !== 'object')
                         return Promise.reject(new SseError('INVALID_TARGET', 'A namespace target is { tenant?, member?, room? }.'));
                     const { tenant, member, room } = target;
@@ -37,7 +40,7 @@ export function sseTransport(api, logger) {
                         ...(tenant === undefined ? { tenantPrefix: prefix } : { tenant: prefix + tenant }),
                         ...(member === undefined ? {} : { member }),
                         ...(room === undefined ? {} : { room }),
-                    }, event, data);
+                    }, event, data, options);
                 },
             });
         },

package/dist/types.d.ts

@@ -2,6 +2,11 @@ import type { Awaitable } from '@dokebi/core';
 import type { FastifyRequest } from 'fastify';
 /** Who a stream belongs to, as `authenticate` decided. Extra fields are kept on `stream.identity`. */
 export interface SseIdentity {
+    /** Local renewable authorization, e.g. request.auth.live(); never published on the bus. */
+    readonly authorization?: {
+        valid(): boolean;
+        subscribe(invalidated: () => void): () => void;
+    };
     readonly tenant: string;
     readonly member: string;
     /** Rooms the stream starts in (counted against maxRooms). */
@@ -47,18 +52,33 @@ export interface SseStream<TIdentity extends SseIdentity = SseIdentity> {
     readonly closed: boolean;
     /**
      * Sends one event to this client only. False when the stream is closed (or was just ended as a
-     * slow consumer). Throws INVALID_EVENT, INVALID_DATA or EVENT_TOO_LARGE.
+     * slow consumer). Throws INVALID_EVENT, INVALID_DATA, EVENT_TOO_LARGE or INVALID_EVENT_ID.
      */
-    send(event: string, data?: unknown): boolean;
+    send(event: string, data?: unknown, options?: SseSendOptions): boolean;
     /** Joins a room of this stream's tenant (this connection only). Throws ROOM_LIMIT, INVALID_ROOM. */
     join(room: string): void;
     leave(room: string): void;
     /** Ends the stream (`SERVER_CLOSED`). The browser's EventSource reconnects after `retry`. */
     close(): void;
 }
+/**
+ * The route config of an SSE route (D-0140): only `id` for now. It becomes the Fastify route's
+ * `config`, so `dokebi describe` lists it as `routes[].id`, per-route hooks of dokebi-web
+ * (`web.routeHook`, audit hooks) see it, and a request reads it as `request.routeOptions.config.id`.
+ */
+export interface SseRouteConfig {
+    /**
+     * The route id of dokebi-web (D-0077 A), for example `'live'` or `'API-12'`: 1 to 64 letters,
+     * digits, `.`, `_` or `-`, starting with a letter. Checked at start like a web route's
+     * (INVALID_ROUTE_CONFIG); the same id on two routes of one app fails it (DUPLICATE_ROUTE_ID).
+     */
+    readonly id?: string;
+}
 export interface SseRoute<TIdentity extends SseIdentity = SseIdentity> {
     /** The GET path of the stream. */
     readonly path: string;
+    /** `{ id }` (D-0140); any other key is INVALID_ROUTE. */
+    readonly config?: SseRouteConfig;
     /** Fastify route constraints, for example `{ dokebiApp: 'shop' }` of @dokebi/app. */
     readonly constraints?: Readonly<Record<string, unknown>>;
     /**
@@ -98,6 +118,15 @@ export interface SsePrefixTarget {
     readonly member?: string;
     readonly room?: string;
 }
+/**
+ * The event id the client sends back as `Last-Event-ID` when it reconnects. Left out, the plugin
+ * numbers events in this process (unique, but meaningless to another worker). Give an id of your
+ * own durable order (a message's sequence in its channel) so a client that reconnects to any
+ * worker can be sent what it missed from the database: 1 to 64 of A-Z a-z 0-9 and -.
+ */
+export interface SseSendOptions {
+    readonly id?: string;
+}
 export interface SsePublishResult {
     /** The event id every recipient sees as `lastEventId`. */
     readonly id: string;
@@ -120,7 +149,7 @@ export interface SseApi {
      * INVALID_TARGET, INVALID_EVENT, INVALID_DATA, EVENT_TOO_LARGE, BUS_UNAVAILABLE (nothing sent)
      * or BUS_PUBLISH_FAILED (sent here, other processes unknown; the error has `id` and `local`).
      */
-    publish(target: SseTarget | SsePrefixTarget, event: string, data?: unknown): Promise<SsePublishResult>;
+    publish(target: SseTarget | SsePrefixTarget, event: string, data?: unknown, options?: SseSendOptions): Promise<SsePublishResult>;
     /** Open streams of this process (worker) that match. */
     connections(filter?: SseFilter): number;
     /** The bus name, when publications cross processes. */
@@ -136,7 +165,7 @@ export interface SseNamespaceTarget {
 export interface SseNamespaceHandle {
     readonly namespace: string;
     /** `publish` with the tenant (or every tenant) of this namespace. */
-    publish(target: SseNamespaceTarget, event: string, data?: unknown): Promise<SsePublishResult>;
+    publish(target: SseNamespaceTarget, event: string, data?: unknown, options?: SseSendOptions): Promise<SsePublishResult>;
 }
 /** The events the plugin itself sends; application event names may not start with `dokebi-`. */
 export declare const RELOAD_EVENT = "dokebi-reload";

package/options.schema.json

@@ -12,6 +12,7 @@
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
       "deprecated": true,
+      "x-dokebi-alias-of": "eventBus",
       "description": "Deprecated name of eventBus; use that key."
     },
     "busEvent": {
@@ -31,6 +32,7 @@
       "minimum": 100,
       "maximum": 3600000,
       "default": 3000,
+      "x-dokebi-reloadable": true,
       "description": "The retry: hint (browser reconnect delay), also the browser client's minimum backoff."
     },
     "heartbeatMs": {
@@ -38,6 +40,7 @@
       "minimum": 10,
       "maximum": 3600000,
       "default": 15000,
+      "x-dokebi-reloadable": true,
       "description": "How often a ': ping' comment is written to every stream. Proxy idle timeouts must be longer."
     },
     "maxConnections": {
@@ -45,6 +48,7 @@
       "minimum": 1,
       "maximum": 1000000,
       "default": 1024,
+      "x-dokebi-reloadable": true,
       "description": "Open streams per process (per cluster worker); more get 503 CAPACITY."
     },
     "maxBufferedBytes": {
@@ -52,6 +56,7 @@
       "minimum": 1,
       "maximum": 67108864,
       "default": 1048576,
+      "x-dokebi-reloadable": true,
       "description": "Bytes a stream may have waiting to be sent; past it the stream is ended (warn SLOW_CONSUMER)."
     },
     "maxRooms": {
@@ -66,6 +71,7 @@
       "minimum": 1,
       "maximum": 16777216,
       "default": 65536,
+      "x-dokebi-reloadable": true,
       "description": "Largest JSON data of one event in bytes (EVENT_TOO_LARGE). Keep it below the bus maxPayloadBytes."
     },
     "shutdownTimeoutMs": {
@@ -80,7 +86,68 @@
       "minimum": 1,
       "maximum": 600000,
       "deprecated": true,
+      "x-dokebi-alias-of": "shutdownTimeoutMs",
       "description": "Deprecated name of shutdownTimeoutMs; use that key."
+    },
+    "endTimeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 600000,
+      "default": 5000,
+      "description": "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": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "busy": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 3600000,
+          "default": 1000,
+          "description": "Retry-After (ms, sent in whole seconds) of the 503 SSE_BUS_BUSY: the bus refused a publication at its pending limit."
+        },
+        "unavailable": {
+          "type": "integer",
+          "minimum": 1000,
+          "maximum": 3600000,
+          "default": 5000,
+          "description": "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": {
+      "type": "integer",
+      "minimum": 100,
+      "maximum": 600000,
+      "default": 5000,
+      "description": "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": {
+      "type": "integer",
+      "minimum": 100,
+      "maximum": 86400000,
+      "default": 60000,
+      "description": "The retry: sent with dokebi-reload (a route whose version changed): a client that ignores the reload reconnects this slowly (D-0114)."
+    },
+    "busWatchIntervalMs": {
+      "type": "integer",
+      "minimum": 100,
+      "maximum": 60000,
+      "default": 1000,
+      "description": "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": {
+      "type": "integer",
+      "minimum": 1000,
+      "maximum": 3600000,
+      "default": 10000,
+      "description": "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)."
     }
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dokebi/sse",
-  "version": "0.4.0",
+  "version": "0.4.2",
   "description": "Server-sent events for @dokebi/web: authenticated streams, rooms, cross-worker fan-out over @dokebi/event-bus, and a browser client",
   "keywords": [
     "dokebi",
@@ -49,8 +49,8 @@
     "test": "node -e \"require('node:fs').rmSync('.tmp/tests',{recursive:true,force:true})\" && tsc -p tsconfig.test.json && node --experimental-eventsource --test \".tmp/tests/tests/*.test.js\""
   },
   "peerDependencies": {
-    "@dokebi/core": "^0.4.0",
-    "@dokebi/web": "^0.4.0",
+    "@dokebi/core": "^0.4.2",
+    "@dokebi/web": "^0.4.3",
     "@dokebi/event-bus": "^0.4.0",
     "fastify": "^5.12.7",
     "react": ">=18",
@@ -68,12 +68,12 @@
     }
   },
   "devDependencies": {
-    "@dokebi/cluster": "0.4.0",
-    "@dokebi/config": "0.4.0",
-    "@dokebi/event-bus": "0.4.0",
-    "@dokebi/health": "0.4.0",
-    "@dokebi/nats": "0.4.0",
-    "@dokebi/web": "0.4.0",
+    "@dokebi/cluster": "0.4.1",
+    "@dokebi/config": "0.4.2",
+    "@dokebi/event-bus": "0.4.2",
+    "@dokebi/health": "0.4.1",
+    "@dokebi/nats": "0.4.1",
+    "@dokebi/web": "0.4.3",
     "react": "19.3.0",
     "react-test-renderer": "19.3.0",
     "vite": "8.3.4",
@@ -82,11 +82,11 @@
   "dokebi": {
     "schemaVersion": 2,
     "id": "dokebi-sse",
-    "core": "^0.4.0",
+    "core": "^0.4.2",
     "dependencies": [
       {
         "name": "dokebi-web",
-        "version": "^0.4.0"
+        "version": "^0.4.3"
       },
       {
         "name": "dokebi-event-bus",