@dokebi/sse 0.0.0-stage → 0.4.0

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export type { SseErrorCode } from './errors.js';
+export { SseError } from './errors.js';
+export type { Options as SseOptions } from './options.js';
+export { parseOptions } from './options.js';
+export { createPlugin, dependency } from './plugin.js';
+export * from './types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { SseError } from './errors.js';
+export { parseOptions } from './options.js';
+export { createPlugin, dependency } from './plugin.js';
+export * from './types.js';

package/dist/install.d.ts

@@ -0,0 +1,18 @@
+interface InstallContext {
+    readonly options: Readonly<Record<string, unknown>>;
+}
+interface Diagnostic {
+    readonly code: string;
+    readonly severity: 'error' | 'warning';
+    readonly optionPath?: readonly string[];
+    readonly hint?: string;
+}
+/** `eventBus` set: publications cross processes through dokebi-event-bus, so it is required. */
+export declare function planInstall(context: InstallContext): {
+    requires: string[];
+};
+export declare function check(context: InstallContext): {
+    requires: string[];
+    diagnostics: Diagnostic[];
+};
+export {};

package/dist/install.js

@@ -0,0 +1,26 @@
+// Install lifecycle module (`dokebi.installModule`). It runs isolated in the CLI, so it imports
+// 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) {
+    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';
+}
+/** `eventBus` set: publications cross processes through dokebi-event-bus, so it is required. */
+export function planInstall(context) {
+    return { requires: usesBus(context.options) ? [EVENT_BUS] : [] };
+}
+export function check(context) {
+    const diagnostics = [];
+    if (usesBus(context.options) === false &&
+        context.options?.allowInCluster === true)
+        diagnostics.push({
+            code: 'SSE_SINGLE_PROCESS',
+            severity: 'warning',
+            optionPath: ['allowInCluster'],
+            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

@@ -0,0 +1,42 @@
+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 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). */
+    readonly allowInCluster: boolean;
+    /** The `retry:` hint sent first on every stream (how long a browser waits before reconnecting). */
+    readonly retryMs: number;
+    /** How often a `: ping` comment is written to every stream (keeps proxies from closing it). */
+    readonly heartbeatMs: number;
+    /** Open streams per process (per worker); more are refused with 503 CAPACITY. */
+    readonly maxConnections: number;
+    /** Bytes a stream may have waiting to be sent; past it the stream is ended (SLOW_CONSUMER). */
+    readonly maxBufferedBytes: number;
+    /** Rooms one stream may be in. */
+    readonly maxRooms: number;
+    /** 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 shutdownTimeoutMs: number;
+}
+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

@@ -0,0 +1,51 @@
+import { defineOptions, option as o } from '@dokebi/core';
+import { SseError } from './errors.js';
+const int = (minimum, maximum, fallback, description) => o.integer({ minimum, maximum, default: fallback, description });
+/*
+ * 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) {
+    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 },
+        });
+    }
+    // `eventBus` is always a key (undefined when unset), as before the declaration.
+    return Object.freeze({ ...result.value, eventBus: result.value.eventBus });
+}

package/dist/plugin.d.ts

@@ -0,0 +1,6 @@
+import { type PluginDependency } from '@dokebi/core';
+import type { SseApi } from './types.js';
+/** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-sse']`. */
+export declare const createPlugin: import("@dokebi/core").PluginFactory<SseApi>;
+/** Declares dokebi-sse as a required provider; it is created from this package when absent. */
+export declare const dependency: PluginDependency<SseApi>;

package/dist/plugin.js

@@ -0,0 +1,98 @@
+import { definePlugin, optionalDependency, providerDependency, } from '@dokebi/core';
+// Always installed with this plugin (peer, required in the manifest): the provider's own file
+// holds the name, package and range (D-0063 §6).
+import { dependency as web } from '@dokebi/web/dependency';
+import { realtime } from '@dokebi/web/points';
+import { SseError } from './errors.js';
+import { Gateway } from './gateway.js';
+import { options as declaration } from './options.js';
+import { sseTransport } from './transport.js';
+/** Only when `bus` is set; created from `app.config['dokebi-event-bus']` when not registered. */
+const events = providerDependency({
+    name: 'dokebi-event-bus',
+    version: '^0.4.0',
+    packageName: '@dokebi/event-bus',
+    load: () => import('@dokebi/event-bus'),
+});
+const health = optionalDependency({ name: 'dokebi-health', version: '^0.4.0' });
+/**
+ * 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 configuredDriver(config, bus) {
+    const options = config?.['dokebi-event-bus'];
+    const value = options?.buses?.[bus];
+    const driver = value?.driver ?? value?.transport;
+    return typeof driver === 'string' ? driver : undefined;
+}
+class SseRuntime {
+    options;
+    #gateway;
+    constructor(options) {
+        this.options = options;
+    }
+    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 (worker && !options.allowInCluster) {
+            const driver = options.eventBus === undefined
+                ? 'none'
+                : (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.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('LOCAL_IN_CLUSTER', 'SSE publications would reach only this worker: use a nats bus (dokebi-sse.eventBus).');
+            }
+        }
+        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.eventBus ?? null,
+            busEvent: options.busEvent,
+            cluster: worker ? 'worker' : 'none',
+            ms: Math.round(performance.now() - started),
+        });
+        return gateway.api;
+    }
+    start() {
+        this.#gateway?.start();
+    }
+    async drain(context) {
+        await this.#gateway?.drain(context.drainSignal);
+    }
+}
+/** Factory input: `{ app, options? }`. Options default to `app.config['dokebi-sse']`. */
+export const createPlugin = definePlugin({
+    name: 'dokebi-sse',
+    version: '0.4.0',
+    core: '^0.4.0',
+    // 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.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

@@ -0,0 +1,144 @@
+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 {
+    readonly tenant: string;
+    readonly member: string;
+    /** Rooms the stream starts in (counted against maxRooms). */
+    readonly rooms?: readonly string[];
+    /**
+     * Which realtime namespace of the app the stream joins (D-0061). Read and removed by
+     * @dokebi/app, which prefixes the tenant with it; this package ignores it.
+     */
+    readonly namespace?: string;
+}
+/** Why a stream ended, as `onClose` and the debug log report it. */
+export type SseCloseReason = 
+/** The client went away (tab closed, network lost, EventSource.close()). */
+'CLIENT_CLOSED'
+/** `stream.close()`. */
+ | 'SERVER_CLOSED'
+/** More than maxBufferedBytes waited to be sent. */
+ | 'SLOW_CONSUMER'
+/** The application is stopping; the stream got `dokebi-restart` first. */
+ | 'DRAIN'
+/** `onOpen` threw. */
+ | 'ON_OPEN_FAILED'
+/** The response failed (socket error). */
+ | 'WRITE_FAILED';
+/** One open event stream of this process. */
+export interface SseStream<TIdentity extends SseIdentity = SseIdentity> {
+    /** A random id of this stream (not an event id). */
+    readonly id: string;
+    readonly tenant: string;
+    readonly member: string;
+    /** The object `authenticate` returned. */
+    readonly identity: TIdentity;
+    /** The route path. */
+    readonly path: string;
+    /**
+     * The `Last-Event-ID` the client sent (EventSource does on its own reconnects), or the
+     * `lastEventId` query of a client that reopened by itself. The server keeps no history
+     * (at most once): this is for the application to resend what it can.
+     */
+    readonly lastEventId: string | undefined;
+    /** The rooms this stream is in now. */
+    readonly rooms: readonly string[];
+    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.
+     */
+    send(event: string, data?: unknown): 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;
+}
+export interface SseRoute<TIdentity extends SseIdentity = SseIdentity> {
+    /** The GET path of the stream. */
+    readonly path: string;
+    /** Fastify route constraints, for example `{ dokebiApp: 'shop' }` of @dokebi/app. */
+    readonly constraints?: Readonly<Record<string, unknown>>;
+    /**
+     * Browser origins allowed besides the page's own host. EventSource sends `Origin` on
+     * cross-origin requests; a request whose Origin host differs from the request host and is not
+     * listed gets 403. Listed origins get CORS headers with credentials. `'*'` allows every origin
+     * without credentials (cookies are not sent then).
+     */
+    readonly origins?: readonly string[] | '*';
+    /**
+     * The client code version this route accepts (D-0033). A client whose `dokebiVersion` query
+     * (or `x-dokebi-version` header) differs gets `event: dokebi-reload` and the stream ends.
+     */
+    readonly version?: string;
+    /** Who is asking; undefined answers 401. Runs on every (re)connect. */
+    authenticate(request: FastifyRequest): Awaitable<TIdentity | undefined>;
+    /**
+     * Called once the stream is open and already receives publications. Rooms joined here (or in
+     * `authenticate`) are this connection's only: a reconnect starts without them.
+     */
+    onOpen?(stream: SseStream<TIdentity>): Awaitable<void>;
+    onClose?(stream: SseStream<TIdentity>, reason: SseCloseReason): Awaitable<void>;
+}
+/** Whom a publication is for: a tenant, one member of it, a room of it, or a member in a room. */
+export interface SseTarget {
+    readonly tenant: string;
+    readonly member?: string;
+    readonly room?: string;
+}
+/**
+ * Every tenant whose name starts with `tenantPrefix` (D-0061: a realtime namespace of @dokebi/app
+ * is the prefix `<namespace>:`), or one member and/or room of each of them. Each process matches
+ * it against its own streams, so it costs one pass over that process's tenants.
+ */
+export interface SsePrefixTarget {
+    readonly tenantPrefix: string;
+    readonly member?: string;
+    readonly room?: string;
+}
+export interface SsePublishResult {
+    /** The event id every recipient sees as `lastEventId`. */
+    readonly id: string;
+    /** Streams of this process the event was written to. */
+    readonly local: number;
+}
+/** Narrows `connections()`; every field is optional. */
+export interface SseFilter {
+    readonly tenant?: string;
+    readonly member?: string;
+    readonly room?: string;
+    readonly path?: string;
+}
+export interface SseApi {
+    /** Adds an event-stream route. Setup only. */
+    route<TIdentity extends SseIdentity = SseIdentity>(route: SseRoute<TIdentity>): void;
+    /**
+     * Sends one event to the matching streams of every process on the bus (this one included,
+     * once). At most once: no acknowledgement, no replay, nothing is resent. Fails with
+     * 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>;
+    /** Open streams of this process (worker) that match. */
+    connections(filter?: SseFilter): number;
+    /** 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";
+export declare const OPEN_EVENT = "dokebi-open";

package/dist/types.js

@@ -0,0 +1,4 @@
+/** The events the plugin itself sends; application event names may not start with `dokebi-`. */
+export const RELOAD_EVENT = 'dokebi-reload';
+export const RESTART_EVENT = 'dokebi-restart';
+export const OPEN_EVENT = 'dokebi-open';

package/dist/wire.d.ts

@@ -0,0 +1,17 @@
+/** Event names: like WebSocket message types (D-0033 router), `dokebi-` kept for the plugin. */
+export declare const EVENT: RegExp;
+/** Event ids: the publishing process prefix, `-`, a base-36 counter. */
+export declare const ID: RegExp;
+export declare function checkEvent(event: unknown): string;
+/** The JSON text of `data` on one line, within maxEventBytes. `undefined` is sent as null. */
+export declare function encodeData(data: unknown, maxBytes: number): string;
+/** True when `json` (from the bus) can be written as a `data:` line as it is. */
+export declare function isLine(text: string): boolean;
+export declare function frame(id: string | undefined, event: string, json: string): string;
+export declare const PING: Buffer<ArrayBuffer>;
+export declare const HEADERS: Readonly<{
+    'content-type': "text/event-stream; charset=utf-8";
+    'cache-control': "no-cache, no-transform";
+    'x-accel-buffering': "no";
+    connection: "keep-alive";
+}>;

package/dist/wire.js

@@ -0,0 +1,44 @@
+import { SseError } from './errors.js';
+/** Event names: like WebSocket message types (D-0033 router), `dokebi-` kept for the plugin. */
+export const EVENT = /^[A-Za-z][A-Za-z0-9._:-]{0,63}$/;
+/** Event ids: the publishing process prefix, `-`, a base-36 counter. */
+export const ID = /^[A-Za-z0-9-]{1,64}$/;
+/** Text that may sit on one SSE field line (no line breaks, no NUL). */
+const LINE = /^[^\r\n\0]*$/;
+export function checkEvent(event) {
+    if (typeof event !== 'string' || !EVENT.test(event) || event.startsWith('dokebi-'))
+        throw new SseError('INVALID_EVENT', 'Event names start with a letter, hold up to 64 of A-Z a-z 0-9 . _ : - and do not start with dokebi-.');
+    return event;
+}
+/** The JSON text of `data` on one line, within maxEventBytes. `undefined` is sent as null. */
+export function encodeData(data, maxBytes) {
+    let json;
+    try {
+        json = data === undefined ? 'null' : JSON.stringify(data);
+    }
+    catch (cause) {
+        throw new SseError('INVALID_DATA', 'Event data is not JSON (a cycle or a BigInt).', { cause });
+    }
+    if (json === undefined)
+        throw new SseError('INVALID_DATA', 'Event data is not JSON (a function or a symbol).');
+    // JSON.stringify escapes CR and LF, so the text always fits on one `data:` line.
+    if (json.length > maxBytes || Buffer.byteLength(json) > maxBytes)
+        throw new SseError('EVENT_TOO_LARGE', `Event data is larger than maxEventBytes (${maxBytes}).`);
+    return json;
+}
+/** True when `json` (from the bus) can be written as a `data:` line as it is. */
+export function isLine(text) {
+    return LINE.test(text);
+}
+export function frame(id, event, json) {
+    return `${id === undefined ? '' : `id: ${id}\n`}event: ${event}\ndata: ${json}\n\n`;
+}
+export const PING = Buffer.from(': ping\n\n');
+export const HEADERS = Object.freeze({
+    'content-type': 'text/event-stream; charset=utf-8',
+    // no-transform: proxies and CDNs must not compress or rewrite the stream (compression buffers).
+    'cache-control': 'no-cache, no-transform',
+    // nginx: do not buffer this response.
+    'x-accel-buffering': 'no',
+    connection: 'keep-alive',
+});

package/options.schema.json

@@ -0,0 +1,86 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "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,
+      "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": {
+      "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 LOCAL_IN_CLUSTER. The bus driver is read from dokebi-event-bus.buses in the application config."
+    },
+    "retryMs": {
+      "type": "integer",
+      "minimum": 100,
+      "maximum": 3600000,
+      "default": 3000,
+      "description": "The retry: hint (browser reconnect delay), also the browser client's minimum backoff."
+    },
+    "heartbeatMs": {
+      "type": "integer",
+      "minimum": 10,
+      "maximum": 3600000,
+      "default": 15000,
+      "description": "How often a ': ping' comment is written to every stream. Proxy idle timeouts must be longer."
+    },
+    "maxConnections": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 1000000,
+      "default": 1024,
+      "description": "Open streams per process (per cluster worker); more get 503 CAPACITY."
+    },
+    "maxBufferedBytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 67108864,
+      "default": 1048576,
+      "description": "Bytes a stream may have waiting to be sent; past it the stream is ended (warn SLOW_CONSUMER)."
+    },
+    "maxRooms": {
+      "type": "integer",
+      "minimum": 0,
+      "maximum": 1024,
+      "default": 32,
+      "description": "Rooms one stream may be in."
+    },
+    "maxEventBytes": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 16777216,
+      "default": 65536,
+      "description": "Largest JSON data of one event in bytes (EVENT_TOO_LARGE). Keep it below the bus maxPayloadBytes."
+    },
+    "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."
+    }
+  }
+}