@dokebi/sse 0.1.0 → 0.4.1

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:`). */
@@ -10,7 +10,6 @@ const RELOAD_RETRY_MS = 60_000;
 const BUS_WATCH_MS = 1000;
 const MAX_TEXT = 256;
 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)
@@ -102,11 +101,11 @@ export class Gateway {
     bus;
     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). */
     #throttle;
     /** Event ids: `<prefix>-<counter>`; the prefix tells processes apart, the counter only grows. */
     #prefix = randomBytes(4).toString('hex');
@@ -116,6 +115,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 +127,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 +139,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 +151,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 +274,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 +296,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,
                 });
@@ -354,8 +355,13 @@ export class Gateway {
             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;
@@ -365,8 +371,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,
@@ -377,7 +385,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,
@@ -401,7 +411,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 +427,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,
@@ -446,10 +456,15 @@ export class Gateway {
         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,
@@ -464,7 +479,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,
@@ -477,11 +492,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) {
@@ -490,8 +508,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);
@@ -501,14 +525,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));
@@ -518,14 +550,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 +578,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 +618,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;
         }
@@ -619,7 +653,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++;
@@ -637,13 +672,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 +699,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 +720,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 +730,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 +760,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.1',
+    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'),
 });