@dokebi/sse 0.1.0 → 0.4.0

package/dist/gateway.js

@@ -1,7 +1,7 @@
 import { randomBytes, randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
+import { diagnostics } from '@dokebi/core/libraries';
 import { SseError } from './errors.js';
-import { errorCode, LogThrottle } from './log.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:`). */
@@ -107,6 +107,7 @@ export class Gateway {
     #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). */
     #throttle;
     /** Event ids: `<prefix>-<counter>`; the prefix tells processes apart, the counter only grows. */
     #prefix = randomBytes(4).toString('hex');
@@ -116,6 +117,8 @@ export class Gateway {
     #routes = 0;
     #frozen = false;
     #closing = false;
+    /** Cleanup ran (`close()`): the bus and the streams are gone, publish throws CLOSED. */
+    #shut = false;
     #heartbeat;
     #watch;
     #subscription;
@@ -126,7 +129,7 @@ export class Gateway {
         this.web = web;
         this.options = options;
         this.bus = bus;
-        this.#throttle = new LogThrottle(context.logger);
+        this.#throttle = new diagnostics.Repeats({ logger: context.logger });
         if (health) {
             this.#health = health.register('sse', { required: false });
             const handle = this.#health;
@@ -138,7 +141,7 @@ export class Gateway {
             publish: (target, event, data) => this.#publish(target, event, data),
             connections: (filter) => this.#count(filter),
             get bus() {
-                return self.options.bus;
+                return self.options.eventBus;
             },
         });
     }
@@ -150,7 +153,7 @@ export class Gateway {
         this.#subscription = subscription;
         await subscription.ready;
         this.context.logger.log('debug', 'SSE bus subscribed', {
-            bus: this.options.bus,
+            bus: this.options.eventBus,
             event: this.options.busEvent,
             origin: this.#origin,
         });
@@ -273,10 +276,10 @@ export class Gateway {
         res.once('close', () => this.#closed(entry));
         res.on('error', (error) => {
             entry.reason ??= 'WRITE_FAILED';
-            const code = errorCode(error, 'UNKNOWN');
+            const code = diagnostics.errorCode(error, 'UNKNOWN');
             // A client that went away mid-write is not a server failure.
             const gone = code === 'ECONNRESET' || code === 'EPIPE' || code === 'ERR_STREAM_DESTROYED';
-            this.#throttle.report(gone ? 'debug' : 'error', 'SSE stream write failed', 'STREAM_WRITE_FAILED', error, { path: route.path, reason: code });
+            this.#throttle.log(gone ? 'debug' : 'error', 'SSE stream write failed', 'STREAM_WRITE_FAILED', error, { path: route.path, reason: code });
         });
         if (logger.isEnabled('debug'))
             logger.log('debug', 'SSE stream opened', {
@@ -295,7 +298,7 @@ export class Gateway {
             await this.#task(Promise.resolve()
                 .then(() => onOpen(entry.stream))
                 .catch((error) => {
-                this.#throttle.report('error', 'SSE onOpen failed; stream ended', 'SSE_ON_OPEN_FAILED', error, {
+                this.#throttle.log('error', 'SSE onOpen failed; stream ended', 'SSE_ON_OPEN_FAILED', error, {
                     path: route.path,
                     stream: entry.id,
                 });
@@ -401,7 +404,7 @@ export class Gateway {
             chunk = Buffer.from(frame(id, event, entry.seal.encode(json)));
         }
         catch (error) {
-            this.#throttle.report('error', 'SSE event seal failed; stream ended', 'SEAL_ENCODE_FAILED', error, {
+            this.#throttle.log('error', 'SSE event seal failed; stream ended', 'SEAL_ENCODE_FAILED', error, {
                 stream: entry.id,
                 path: entry.route.path,
             });
@@ -417,7 +420,7 @@ export class Gateway {
         const res = entry.res;
         // ServerResponse.writableLength counts what waits in the response and in its socket.
         if (res.writableLength + chunk.byteLength > this.options.maxBufferedBytes) {
-            this.#throttle.report('warn', 'SSE slow consumer ended', 'SLOW_CONSUMER', undefined, {
+            this.#throttle.log('warn', 'SSE slow consumer ended', 'SLOW_CONSUMER', undefined, {
                 stream: entry.id,
                 path: entry.route.path,
                 bufferedBytes: res.writableLength,
@@ -464,7 +467,7 @@ export class Gateway {
             void this.#task(Promise.resolve()
                 .then(() => onClose(entry.stream, reason))
                 .catch((error) => {
-                this.#throttle.report('error', 'SSE onClose failed', 'SSE_ON_CLOSE_FAILED', error, {
+                this.#throttle.log('error', 'SSE onClose failed', 'SSE_ON_CLOSE_FAILED', error, {
                     path: entry.route.path,
                     stream: entry.id,
                     reason,
@@ -518,14 +521,16 @@ export class Gateway {
         return written;
     }
     async #publish(target, event, data) {
+        if (this.#shut)
+            throw new SseError('CLOSED', 'dokebi-sse is closed: the application has stopped.');
         const checked = checkTarget(target);
         checkEvent(event);
         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.bus} is ${bus.state}; the event was not sent.`);
-            this.#throttle.report('error', 'SSE publish refused; bus unavailable', 'BUS_UNAVAILABLE', error, {
-                bus: this.options.bus,
+            const error = new SseError('BUS_UNAVAILABLE', `Event bus ${this.options.eventBus} is ${bus.state}; the event was not sent.`);
+            this.#throttle.log('error', 'SSE publish refused; bus unavailable', 'BUS_UNAVAILABLE', error, {
+                bus: this.options.eventBus,
                 state: bus.state,
             });
             throw error;
@@ -544,11 +549,11 @@ export class Gateway {
                 });
             }
             catch (cause) {
-                this.#throttle.report('error', 'SSE bus publish failed', 'BUS_PUBLISH_FAILED', cause, {
-                    bus: this.options.bus,
+                this.#throttle.log('error', 'SSE bus publish failed', 'BUS_PUBLISH_FAILED', cause, {
+                    bus: this.options.eventBus,
                     id,
                     local,
-                    busCode: errorCode(cause, 'UNKNOWN'),
+                    busCode: diagnostics.errorCode(cause, 'UNKNOWN'),
                 });
                 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 });
             }
@@ -584,15 +589,15 @@ export class Gateway {
                 target = checkTarget(message.target);
             }
             catch (error) {
-                this.#throttle.report('error', 'SSE bus message rejected', 'BUS_MESSAGE_INVALID', error, {
-                    bus: this.options.bus,
+                this.#throttle.log('error', 'SSE bus message rejected', 'BUS_MESSAGE_INVALID', error, {
+                    bus: this.options.eventBus,
                 });
                 return;
             }
         }
         if (!message || !target) {
-            this.#throttle.report('error', 'SSE bus message rejected', 'BUS_MESSAGE_INVALID', undefined, {
-                bus: this.options.bus,
+            this.#throttle.log('error', 'SSE bus message rejected', 'BUS_MESSAGE_INVALID', undefined, {
+                bus: this.options.eventBus,
             });
             return;
         }
@@ -637,13 +642,13 @@ export class Gateway {
         if (up) {
             this.#health?.ready();
             if (!first)
-                this.context.logger.log('info', 'SSE bus available again', { bus: this.options.bus });
+                this.context.logger.log('info', 'SSE bus available again', { bus: this.options.eventBus });
         }
         else {
             this.#health?.fail('BUS_UNAVAILABLE');
             this.context.logger.log('warn', 'SSE bus unavailable; publications fail', {
                 code: 'BUS_UNAVAILABLE',
-                bus: this.options.bus,
+                bus: this.options.eventBus,
                 state: bus.state,
             });
         }
@@ -664,7 +669,7 @@ export class Gateway {
             this.#health?.ready();
         this.context.logger.log('debug', 'SSE gateway started', {
             routes: this.#routes,
-            bus: this.options.bus ?? null,
+            bus: this.options.eventBus ?? null,
             heartbeatMs: this.options.heartbeatMs,
             retryMs: this.options.retryMs,
             maxConnections: this.options.maxConnections,
@@ -685,8 +690,8 @@ export class Gateway {
                 await subscription.unsubscribe();
             }
             catch (error) {
-                this.#throttle.report('error', 'SSE bus unsubscribe failed', 'BUS_UNSUBSCRIBE_FAILED', error, {
-                    bus: this.options.bus,
+                this.#throttle.log('error', 'SSE bus unsubscribe failed', 'BUS_UNSUBSCRIBE_FAILED', error, {
+                    bus: this.options.eventBus,
                 });
             }
         const json = JSON.stringify({ retryMs: this.options.retryMs });
@@ -695,7 +700,7 @@ export class Gateway {
             this.#event(entry, undefined, RESTART_EVENT, json, restart);
             this.#end(entry, 'DRAIN');
         }
-        const deadline = performance.now() + this.options.closeTimeoutMs;
+        const deadline = performance.now() + this.options.shutdownTimeoutMs;
         while (this.#entries.size && performance.now() < deadline && !signal.aborted)
             await delay(10);
         if (this.#entries.size) {
@@ -725,6 +730,7 @@ export class Gateway {
     /** Cleanup: after a failed start no drain ran, so streams may still be open. */
     close() {
         this.#closing = true;
+        this.#shut = true;
         this.#timers();
         for (const entry of this.#entries.values())
             entry.res.destroy();

package/dist/install.d.ts

@@ -7,7 +7,7 @@ interface Diagnostic {
     readonly optionPath?: readonly string[];
     readonly hint?: string;
 }
-/** `bus` set: publications cross processes through dokebi-event-bus, so it is required. */
+/** `eventBus` set: publications cross processes through dokebi-event-bus, so it is required. */
 export declare function planInstall(context: InstallContext): {
     requires: string[];
 };

package/dist/install.js

@@ -2,11 +2,13 @@
 // nothing and only reads the plain options it is given. Invalid options are left to the schema.
 const EVENT_BUS = 'dokebi-event-bus';
 function usesBus(options) {
-    return (options !== null &&
-        typeof options === 'object' &&
-        typeof options.bus === 'string');
+    if (options === null || typeof options !== 'object')
+        return false;
+    const values = options;
+    // `bus` is the deprecated name of `eventBus` (D-0071), still accepted in 0.4.0.
+    return typeof values.eventBus === 'string' || typeof values.bus === 'string';
 }
-/** `bus` set: publications cross processes through dokebi-event-bus, so it is required. */
+/** `eventBus` set: publications cross processes through dokebi-event-bus, so it is required. */
 export function planInstall(context) {
     return { requires: usesBus(context.options) ? [EVENT_BUS] : [] };
 }
@@ -18,7 +20,7 @@ export function check(context) {
             code: 'SSE_SINGLE_PROCESS',
             severity: 'warning',
             optionPath: ['allowInCluster'],
-            hint: 'Without bus, publications reach one worker only; set bus to a nats event bus',
+            hint: 'Without eventBus, publications reach one worker only; set eventBus to a nats event bus',
         });
     return { requires: planInstall(context).requires, diagnostics };
 }

package/dist/options.d.ts

@@ -3,7 +3,7 @@ export interface Options {
      * The dokebi-event-bus bus (`buses.<name>`) that carries publications to the other workers and
      * servers. Unset: publish reaches the streams of this process only.
      */
-    readonly bus: string | undefined;
+    readonly eventBus: string | undefined;
     /** The bus event name publications travel under. */
     readonly busEvent: string;
     /** Lets a node:cluster worker start without a NATS bus (a deliberate single-worker cluster). */
@@ -21,7 +21,22 @@ export interface Options {
     /** Largest JSON `data` of one event, in bytes. */
     readonly maxEventBytes: number;
     /** How long drain waits for streams to end after `dokebi-restart` before cutting them. */
-    readonly closeTimeoutMs: number;
+    readonly shutdownTimeoutMs: number;
 }
-/** Validates the plugin options (no accessors or Proxies are evaluated) and fills in defaults. */
+export declare const options: import("@dokebi/core").OptionsDeclaration<{
+    readonly allowInCluster: boolean;
+    readonly busEvent: string;
+    readonly eventBus?: string;
+    readonly heartbeatMs: number;
+    readonly maxBufferedBytes: number;
+    readonly maxConnections: number;
+    readonly maxEventBytes: number;
+    readonly maxRooms: number;
+    readonly retryMs: number;
+    readonly shutdownTimeoutMs: number;
+}>;
+/**
+ * Validates the plugin options (no accessors or Proxies are evaluated) and fills in defaults.
+ * Fails with SseError `INVALID_OPTIONS` (paths in the message and `details.issues`, no values).
+ */
 export declare function parseOptions(input: unknown): Options;

package/dist/options.js

@@ -1,63 +1,51 @@
-import { types } from 'node:util';
+import { defineOptions, option as o } from '@dokebi/core';
 import { SseError } from './errors.js';
-const BUS = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
-/** The event-bus event name rule (dot-separated tokens starting with a letter). */
-const BUS_EVENT = /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)*$/;
-const LIMITS = {
-    retryMs: [3000, 100, 3_600_000],
-    heartbeatMs: [15000, 10, 3_600_000],
-    maxConnections: [1024, 1, 1_000_000],
-    maxBufferedBytes: [1_048_576, 1, 67_108_864],
-    maxRooms: [32, 0, 1024],
-    maxEventBytes: [65_536, 1, 16_777_216],
-    closeTimeoutMs: [2000, 1, 600_000],
-};
-const KEYS = new Set(['bus', 'busEvent', 'allowInCluster', ...Object.keys(LIMITS)]);
-function invalid(message) {
-    throw new SseError('INVALID_OPTIONS', message);
-}
-/** Validates the plugin options (no accessors or Proxies are evaluated) and fills in defaults. */
+const int = (minimum, maximum, fallback, description) => o.integer({ minimum, maximum, default: fallback, description });
+/*
+ * Options of dokebi-sse (D-0063 §3): one declaration is the parser and, at build time,
+ * options.schema.json.
+ */
+export const options = defineOptions({
+    eventBus: o.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: o.alias('eventBus'),
+    busEvent: o.string({
+        maxLength: 128,
+        // The event-bus event name rule (dot-separated tokens starting with a letter).
+        pattern: /^[A-Za-z][A-Za-z0-9_-]*(?:\.[A-Za-z0-9_-]+)*$/,
+        default: 'dokebi.sse',
+        description: 'The event-bus event name publications travel under.',
+    }),
+    allowInCluster: o.boolean({
+        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).'),
+    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.'),
+    shutdownTimeoutMs: int(1, 600_000, 2000, 'How long drain waits for streams to end after dokebi-restart before cutting them.'),
+    closeTimeoutMs: o.alias('shutdownTimeoutMs'),
+});
+/**
+ * Validates the plugin options (no accessors or Proxies are evaluated) and fills in defaults.
+ * Fails with SseError `INVALID_OPTIONS` (paths in the message and `details.issues`, no values).
+ */
 export function parseOptions(input) {
-    if (input === undefined)
-        input = {};
-    if (!input ||
-        typeof input !== 'object' ||
-        Array.isArray(input) ||
-        types.isProxy(input) ||
-        ![Object.prototype, null].includes(Object.getPrototypeOf(input)))
-        invalid('SSE options must be a plain object.');
-    const value = Object.create(null);
-    for (const key of Reflect.ownKeys(input)) {
-        const descriptor = Object.getOwnPropertyDescriptor(input, key);
-        if (typeof key !== 'string' ||
-            !descriptor ||
-            !('value' in descriptor) ||
-            !descriptor.enumerable)
-            invalid('SSE options must hold plain data properties.');
-        if (!KEYS.has(key))
-            invalid(`Unknown SSE option: ${key}`);
-        value[key] = descriptor.value;
-    }
-    const bus = value.bus;
-    if (bus !== undefined && (typeof bus !== 'string' || !BUS.test(bus)))
-        invalid('bus must be the name of a dokebi-event-bus bus.');
-    const busEvent = value.busEvent ?? 'dokebi.sse';
-    if (typeof busEvent !== 'string' || busEvent.length > 128 || !BUS_EVENT.test(busEvent))
-        invalid('busEvent must be an event-bus event name such as dokebi.sse.');
-    const allowInCluster = value.allowInCluster ?? false;
-    if (typeof allowInCluster !== 'boolean')
-        invalid('allowInCluster must be a boolean.');
-    const limits = {};
-    for (const [key, [fallback, min, max]] of Object.entries(LIMITS)) {
-        const number = value[key] ?? fallback;
-        if (typeof number !== 'number' || !Number.isSafeInteger(number) || number < min || number > max)
-            invalid(`${key} must be an integer from ${min} to ${max}.`);
-        limits[key] = number;
+    const result = options.check(input);
+    if (!result.ok) {
+        const shown = result.issues
+            .slice(0, 3)
+            .map((issue) => `${issue.path || 'options'} ${issue.message}`)
+            .join('; ');
+        throw new SseError('INVALID_OPTIONS', `Invalid SSE options: ${shown}`, {
+            details: { issues: result.issues },
+        });
     }
-    return Object.freeze({
-        bus,
-        busEvent,
-        allowInCluster,
-        ...limits,
-    });
+    // `eventBus` is always a key (undefined when unset), as before the declaration.
+    return Object.freeze({ ...result.value, eventBus: result.value.eventBus });
 }

package/dist/plugin.js

@@ -1,30 +1,30 @@
-import cluster from 'node:cluster';
 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 { parseOptions } from './options.js';
-const web = providerDependency({
-    name: 'dokebi-web',
-    version: '^0.2.0',
-    packageName: '@dokebi/web',
-    load: () => import('@dokebi/web'),
-});
+import { options as declaration } from './options.js';
+import { sseTransport } from './transport.js';
 /** Only when `bus` is set; created from `app.config['dokebi-event-bus']` when not registered. */
 const events = providerDependency({
     name: 'dokebi-event-bus',
-    version: '^0.1.0',
+    version: '^0.4.0',
     packageName: '@dokebi/event-bus',
     load: () => import('@dokebi/event-bus'),
 });
-const health = optionalDependency({ name: 'dokebi-health', version: '^0.1.0' });
+const health = optionalDependency({ name: 'dokebi-health', version: '^0.4.0' });
 /**
- * The transport of a bus as dokebi-event-bus options in the application config name it.
- * The event-bus API does not expose it, so options given to that plugin in code are unknown here.
+ * The driver of a bus as dokebi-event-bus options in the application config name it (`driver`, or
+ * its deprecated name `transport`, D-0071). The event-bus API does not expose it, so options given
+ * to that plugin in code are unknown here.
  */
-function configuredTransport(config, bus) {
+function configuredDriver(config, bus) {
     const options = config?.['dokebi-event-bus'];
-    const transport = options?.buses?.[bus]?.transport;
-    return typeof transport === 'string' ? transport : undefined;
+    const value = options?.buses?.[bus];
+    const driver = value?.driver ?? value?.transport;
+    return typeof driver === 'string' ? driver : undefined;
 }
 class SseRuntime {
     options;
@@ -35,32 +35,38 @@ class SseRuntime {
     async setup(context) {
         const started = performance.now();
         const { options } = this;
+        // core decides the role (D-0063 §4): a node:cluster worker is `worker`.
+        const worker = context.runtime.role === 'worker';
         // A publication must reach the streams of every worker. Without a NATS bus each worker
         // reaches only its own clients, which works by accident and fails silently in use.
-        if (cluster.isWorker && !options.allowInCluster) {
-            const transport = options.bus === undefined
+        if (worker && !options.allowInCluster) {
+            const driver = options.eventBus === undefined
                 ? 'none'
-                : (configuredTransport(context.app.config, options.bus) ?? 'unknown');
-            if (transport !== 'nats') {
+                : (configuredDriver(context.app.config, options.eventBus) ?? 'unknown');
+            if (driver !== 'nats') {
                 context.logger.log('error', 'SSE in a cluster worker without a NATS bus', {
                     code: 'SSE_LOCAL_IN_CLUSTER',
-                    bus: options.bus ?? null,
-                    transport,
-                    fix: 'Set dokebi-sse.bus to a dokebi-event-bus bus with transport nats (configured in ' +
+                    bus: options.eventBus ?? null,
+                    driver,
+                    fix: 'Set dokebi-sse.eventBus to a dokebi-event-bus bus with driver nats (configured in ' +
                         'dokebi-event-bus.buses), or allowInCluster: true for a deliberate single-worker cluster',
                 });
-                throw new SseError('SSE_LOCAL_IN_CLUSTER', 'SSE publications would reach only this worker: use a nats bus (dokebi-sse.bus).');
+                throw new SseError('LOCAL_IN_CLUSTER', 'SSE publications would reach only this worker: use a nats bus (dokebi-sse.eventBus).');
             }
         }
-        const bus = options.bus === undefined ? undefined : context.getDependency(events).bus(options.bus);
+        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));
         context.defer(() => gateway.close());
         this.#gateway = gateway;
         await gateway.subscribe();
+        // D-0063: the `sse` transport for dokebi-app (inert until a plugin collects the point).
+        context.contribute(realtime, sseTransport(gateway.api, context.logger));
         context.logger.log('debug', 'SSE setup finished', {
-            bus: options.bus ?? null,
+            bus: options.eventBus ?? null,
             busEvent: options.busEvent,
-            cluster: cluster.isWorker ? 'worker' : 'none',
+            cluster: worker ? 'worker' : 'none',
             ms: Math.round(performance.now() - started),
         });
         return gateway.api;
@@ -75,16 +81,18 @@ class SseRuntime {
 /** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-sse']`. */
 export const createPlugin = definePlugin({
     name: 'dokebi-sse',
-    version: '0.1.0',
-    core: '^0.2.0',
-    options: parseOptions,
-    dependencies: ({ options }) => options.bus === undefined ? [web, health] : [web, events, health],
-    instance: ({ options }) => new SseRuntime(options),
+    version: '0.4.0',
+    core: '^0.4.0',
+    // The declaration (not parseOptions) so core logs OPTION_DEPRECATED for old keys (bus, closeTimeoutMs).
+    options: declaration,
+    contributes: [realtime],
+    dependencies: ({ options }) => options.eventBus === undefined ? [web, health] : [web, events, health],
+    instance: ({ options }) => new SseRuntime(Object.freeze({ ...options, eventBus: options.eventBus })),
 });
 /** Declares dokebi-sse as a required provider; it is created from this package when absent. */
 export const dependency = providerDependency({
     name: 'dokebi-sse',
     packageName: '@dokebi/sse',
-    version: '^0.1.0',
+    version: '^0.4.0',
     load: () => import('./index.js'),
 });

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."
     }
   }
 }