@dokebi/sse 0.4.1 → 0.4.3

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.1",
+  "version": "0.4.3",
   "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.1",
-    "@dokebi/event-bus": "0.4.1",
-    "@dokebi/health": "0.4.0",
-    "@dokebi/nats": "0.4.0",
-    "@dokebi/web": "0.4.2",
+    "@dokebi/cluster": "0.4.1",
+    "@dokebi/config": "0.4.4",
+    "@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",