@dokebi/sse 0.1.0 → 0.4.1

package/dist/transport.d.ts

@@ -0,0 +1,13 @@
+import type { Logger } from '@dokebi/core';
+import type { WebRealtimeTransport } from '@dokebi/web/points';
+import type { SseApi, SseNamespaceHandle, SseRoute } from './types.js';
+/** The `sse` transport contributed to `dokebi-web:realtime` (D-0063 §5). */
+export type SseTransport = WebRealtimeTransport<SseRoute, SseNamespaceHandle> & {
+    readonly kind: 'sse';
+};
+/**
+ * What dokebi-app needs to mount SSE routes of apps and modules and to publish per namespace,
+ * built on the public API: `mount` adds the scope's path, constraints and tenant rule to a
+ * route; `handle` prefixes targets with `<namespace>:`.
+ */
+export declare function sseTransport(api: SseApi, logger: Logger): SseTransport;

package/dist/transport.js

@@ -0,0 +1,45 @@
+import { SseError } from './errors.js';
+const NAMESPACE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/**
+ * What dokebi-app needs to mount SSE routes of apps and modules and to publish per namespace,
+ * built on the public API: `mount` adds the scope's path, constraints and tenant rule to a
+ * route; `handle` prefixes targets with `<namespace>:`.
+ */
+export function sseTransport(api, logger) {
+    return Object.freeze({
+        kind: 'sse',
+        mount(route, scope) {
+            if (route === null || typeof route !== 'object' || typeof route.authenticate !== 'function')
+                throw new SseError('INVALID_ROUTE', 'Invalid SSE route.');
+            api.route({
+                ...route,
+                path: scope.path,
+                constraints: { ...(route.constraints ?? {}), ...scope.constraints },
+                authenticate: async (request) => {
+                    const identity = await route.authenticate(request);
+                    return identity ? scope.identity(identity) : undefined;
+                },
+            });
+            if (logger.isEnabled('debug'))
+                logger.log('debug', 'SSE route mounted by the realtime point', { path: scope.path });
+        },
+        handle(namespace) {
+            if (typeof namespace !== 'string' || !NAMESPACE.test(namespace))
+                throw new SseError('INVALID_TARGET', 'A realtime namespace is a name of 1 to 64 characters.');
+            const prefix = `${namespace}:`;
+            return Object.freeze({
+                namespace,
+                publish: (target, event, data) => {
+                    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;
+                    return api.publish({
+                        ...(tenant === undefined ? { tenantPrefix: prefix } : { tenant: prefix + tenant }),
+                        ...(member === undefined ? {} : { member }),
+                        ...(room === undefined ? {} : { room }),
+                    }, event, data);
+                },
+            });
+        },
+    });
+}

package/dist/types.d.ts

@@ -126,6 +126,18 @@ export interface SseApi {
     /** The bus name, when publications cross processes. */
     readonly bus: string | undefined;
 }
+/** Whom a namespace publication is for (D-0061): a tenant of the namespace, or all of them. */
+export interface SseNamespaceTarget {
+    readonly tenant?: string;
+    readonly member?: string;
+    readonly room?: string;
+}
+/** The SSE operations on one realtime namespace (the tenants `<namespace>:<tenant>`). */
+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>;
+}
 /** The events the plugin itself sends; application event names may not start with `dokebi-`. */
 export declare const RELOAD_EVENT = "dokebi-reload";
 export declare const RESTART_EVENT = "dokebi-restart";

package/options.schema.json

@@ -3,11 +3,17 @@
   "type": "object",
   "additionalProperties": false,
   "properties": {
-    "bus": {
+    "eventBus": {
       "type": "string",
       "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
       "description": "A dokebi-event-bus bus (buses.<name>) that carries publications to every worker and server. Use a nats bus for more than one process. Unset: publish reaches this process only."
     },
+    "bus": {
+      "type": "string",
+      "pattern": "^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$",
+      "deprecated": true,
+      "description": "Deprecated name of eventBus; use that key."
+    },
     "busEvent": {
       "type": "string",
       "maxLength": 128,
@@ -18,7 +24,7 @@
     "allowInCluster": {
       "type": "boolean",
       "default": false,
-      "description": "Start in a node:cluster worker without a nats bus (a deliberate single-worker cluster). Otherwise that start fails with SSE_LOCAL_IN_CLUSTER. The bus transport is read from dokebi-event-bus.buses in the application config."
+      "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": {
       "type": "integer",
@@ -62,12 +68,19 @@
       "default": 65536,
       "description": "Largest JSON data of one event in bytes (EVENT_TOO_LARGE). Keep it below the bus maxPayloadBytes."
     },
-    "closeTimeoutMs": {
+    "shutdownTimeoutMs": {
       "type": "integer",
       "minimum": 1,
       "maximum": 600000,
       "default": 2000,
       "description": "How long drain waits for streams to end after dokebi-restart before cutting them."
+    },
+    "closeTimeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 600000,
+      "deprecated": true,
+      "description": "Deprecated name of shutdownTimeoutMs; use that key."
     }
   }
 }

package/package.json

@@ -1,9 +1,16 @@
 {
   "name": "@dokebi/sse",
-  "version": "0.1.0",
+  "version": "0.4.1",
+  "description": "Server-sent events for @dokebi/web: authenticated streams, rooms, cross-worker fan-out over @dokebi/event-bus, and a browser client",
+  "keywords": [
+    "dokebi",
+    "dokebi-plugin",
+    "web",
+    "sse",
+    "realtime"
+  ],
   "private": false,
   "type": "module",
-  "description": "Server-sent events for @dokebi/web: authenticated streams, rooms, cross-worker fan-out over @dokebi/event-bus, and a browser client",
   "license": "MIT",
   "main": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -37,14 +44,14 @@
     "node": ">=24.0.0"
   },
   "scripts": {
-    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.browser.json && vite build -c vite.client.config.ts --logLevel warn",
+    "build": "node -e \"require('node:fs').rmSync('dist',{recursive:true,force:true})\" && tsc -p tsconfig.json && tsc -p tsconfig.browser.json && vite build -c vite.client.config.ts --logLevel warn && node -e \"import('./dist/options.js').then(async (m) => { const { renderOptionsSchema } = await import('@dokebi/core'); process.stdout.write(renderOptionsSchema(m.options)); })\" > options.schema.json",
     "typecheck": "tsc -p tsconfig.test.json --noEmit",
-    "test": "tsc -p tsconfig.test.json && node --experimental-eventsource --test \".tmp/tests/tests/*.test.js\""
+    "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.2.0",
-    "@dokebi/web": "^0.2.0",
-    "@dokebi/event-bus": "^0.1.0",
+    "@dokebi/core": "^0.4.0",
+    "@dokebi/web": "^0.4.0",
+    "@dokebi/event-bus": "^0.4.0",
     "fastify": "^5.12.7",
     "react": ">=18",
     "vue": "^3.3.0"
@@ -61,12 +68,12 @@
     }
   },
   "devDependencies": {
-    "@dokebi/cluster": "0.1.2",
-    "@dokebi/config": "0.2.3",
-    "@dokebi/event-bus": "0.1.2",
-    "@dokebi/health": "0.1.2",
-    "@dokebi/nats": "0.1.2",
-    "@dokebi/web": "0.2.0",
+    "@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",
     "react": "19.3.0",
     "react-test-renderer": "19.3.0",
     "vite": "8.3.4",
@@ -75,27 +82,42 @@
   "dokebi": {
     "schemaVersion": 2,
     "id": "dokebi-sse",
-    "core": "^0.2.0",
+    "core": "^0.4.0",
     "dependencies": [
       {
         "name": "dokebi-web",
-        "version": "^0.2.0"
+        "version": "^0.4.0"
       },
       {
         "name": "dokebi-event-bus",
-        "version": "^0.1.0",
+        "version": "^0.4.0",
         "optional": true
       },
       {
         "name": "dokebi-health",
-        "version": "^0.1.0",
+        "version": "^0.4.0",
         "optional": true
       }
     ],
+    "contributes": [
+      "dokebi-web:realtime"
+    ],
     "installModule": "dist/install.js",
     "optionsSchema": "options.schema.json",
     "documentation": "AI.md"
   },
+  "dokebiCatalog": {
+    "kind": "plugin",
+    "summary": "Server-sent events (SSE) streams and rooms, delivery across workers, and a browser client",
+    "maturity": "preview",
+    "provides": [
+      "realtime.sse"
+    ],
+    "doesNot": [
+      "No ACK, redelivery or retention (at most once)"
+    ],
+    "recipes": []
+  },
   "publishConfig": {
     "access": "public",
     "registry": "https://registry.npmjs.org/"

package/dist/log.d.ts

@@ -1,25 +0,0 @@
-import type { LogFields, Logger, LogLevel } from '@dokebi/core';
-/**
- * The full text of a caught value for the `error` log field (D-0047): name, whole message and
- * stack, then each `cause` the same way. Only credentials in URLs (`//user:password@`) are
- * removed; a text over 16 KB is cut and marked.
- */
-export declare function errorText(error: unknown): string;
-/** A stable code of an error (hub, ws or errno code), or `fallback`. */
-export declare function errorCode(error: unknown, fallback: string): string;
-/**
- * Logs a repeating event once per interval (D-0047): the first occurrence at once, the following
- * ones of the same message and code (and `group`, when given) are counted and reported together
- * (`repeated`) when the interval ends. `group` must come from a bounded set (e.g. registered
- * handler types), never from client input, since each value keeps an entry for an interval. Hot paths (per message, per frame) can report every failure without a burst
- * flooding the log. Field and error text are built only for lines that are written.
- */
-export declare class LogThrottle {
-    #private;
-    readonly logger: Logger;
-    readonly intervalMs: number;
-    constructor(logger: Logger, intervalMs?: number);
-    report(level: LogLevel, message: string, code: string, error?: unknown, fields?: LogFields, group?: string): void;
-    /** Writes the counts still pending (on close), so a burst at shutdown is not lost. */
-    flush(): void;
-}

package/dist/log.js

@@ -1,102 +0,0 @@
-const CODE = /^[A-Z][A-Z0-9_]{0,63}$/;
-/**
- * The full text of a caught value for the `error` log field (D-0047): name, whole message and
- * stack, then each `cause` the same way. Only credentials in URLs (`//user:password@`) are
- * removed; a text over 16 KB is cut and marked.
- */
-export function errorText(error) {
-    const parts = [];
-    let current = error;
-    for (let depth = 0; current !== undefined && depth < 5; depth++) {
-        let text;
-        if (current instanceof Error)
-            text = current.stack ?? `${current.name}: ${current.message}`;
-        else if (typeof current === 'string')
-            text = current;
-        else {
-            try {
-                text = `NonError: ${JSON.stringify(current)}`;
-            }
-            catch {
-                text = `NonError: ${String(current)}`; // not serialisable (cycle, BigInt): its string form
-            }
-        }
-        parts.push(depth ? `Caused by: ${text}` : text);
-        current = current instanceof Error ? current.cause : undefined;
-    }
-    const text = parts.join('\n').replace(/\/\/[^\s/@]*@/g, '//***@');
-    return text.length > 16_384
-        ? `${text.slice(0, 16_384)}… [truncated ${text.length - 16_384} characters]`
-        : text;
-}
-/** A stable code of an error (hub, ws or errno code), or `fallback`. */
-export function errorCode(error, fallback) {
-    const code = error?.code;
-    return typeof code === 'string' && CODE.test(code) ? code : fallback;
-}
-/**
- * Logs a repeating event once per interval (D-0047): the first occurrence at once, the following
- * ones of the same message and code (and `group`, when given) are counted and reported together
- * (`repeated`) when the interval ends. `group` must come from a bounded set (e.g. registered
- * handler types), never from client input, since each value keeps an entry for an interval. Hot paths (per message, per frame) can report every failure without a burst
- * flooding the log. Field and error text are built only for lines that are written.
- */
-export class LogThrottle {
-    logger;
-    intervalMs;
-    #entries = new Map();
-    constructor(logger, intervalMs = 10_000) {
-        this.logger = logger;
-        this.intervalMs = intervalMs;
-    }
-    report(level, message, code, error, fields, group) {
-        if (!this.logger.isEnabled(level))
-            return;
-        const key = `${level}\u0000${code}\u0000${message}${group === undefined ? '' : `\u0000${group}`}`;
-        const entry = this.#entries.get(key);
-        if (entry) {
-            entry.count++;
-            entry.error = error;
-            entry.fields = fields;
-            return;
-        }
-        this.#write(level, message, code, error, fields, 0);
-        const value = {
-            count: 0,
-            error: undefined,
-            fields: undefined,
-            timer: setTimeout(() => this.#elapsed(key, value, level, message, code), this.intervalMs),
-        };
-        value.timer.unref();
-        this.#entries.set(key, value);
-    }
-    #elapsed(key, entry, level, message, code) {
-        if (!entry.count) {
-            this.#entries.delete(key);
-            return;
-        }
-        this.#write(level, message, code, entry.error, entry.fields, entry.count);
-        entry.count = 0;
-        entry.timer = setTimeout(() => this.#elapsed(key, entry, level, message, code), this.intervalMs);
-        entry.timer.unref();
-    }
-    #write(level, message, code, error, fields, repeated) {
-        this.logger.log(level, message, {
-            ...fields,
-            code,
-            ...(error === undefined ? {} : { error: errorText(error) }),
-            ...(repeated ? { repeated, intervalMs: this.intervalMs } : {}),
-        });
-    }
-    /** Writes the counts still pending (on close), so a burst at shutdown is not lost. */
-    flush() {
-        for (const [key, entry] of this.#entries) {
-            clearTimeout(entry.timer);
-            if (entry.count) {
-                const [level, code, message] = key.split('\u0000');
-                this.#write(level, message, code, entry.error, entry.fields, entry.count);
-            }
-        }
-        this.#entries.clear();
-    }
-}