@dokebi/sse 0.0.0-stage → 0.1.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;
+}
+/** `bus` 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,24 @@
+// 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) {
+    return (options !== null &&
+        typeof options === 'object' &&
+        typeof options.bus === 'string');
+}
+/** `bus` 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 bus, publications reach one worker only; set bus to a nats event bus',
+        });
+    return { requires: planInstall(context).requires, diagnostics };
+}

package/dist/log.d.ts

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

package/dist/log.js

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

package/dist/options.d.ts

@@ -0,0 +1,27 @@
+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;
+    /** 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 closeTimeoutMs: number;
+}
+/** Validates the plugin options (no accessors or Proxies are evaluated) and fills in defaults. */
+export declare function parseOptions(input: unknown): Options;

package/dist/options.js

@@ -0,0 +1,63 @@
+import { types } from 'node:util';
+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. */
+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;
+    }
+    return Object.freeze({
+        bus,
+        busEvent,
+        allowInCluster,
+        ...limits,
+    });
+}

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,90 @@
+import cluster from 'node:cluster';
+import { definePlugin, optionalDependency, providerDependency, } from '@dokebi/core';
+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'),
+});
+/** 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',
+    packageName: '@dokebi/event-bus',
+    load: () => import('@dokebi/event-bus'),
+});
+const health = optionalDependency({ name: 'dokebi-health', version: '^0.1.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.
+ */
+function configuredTransport(config, bus) {
+    const options = config?.['dokebi-event-bus'];
+    const transport = options?.buses?.[bus]?.transport;
+    return typeof transport === 'string' ? transport : undefined;
+}
+class SseRuntime {
+    options;
+    #gateway;
+    constructor(options) {
+        this.options = options;
+    }
+    async setup(context) {
+        const started = performance.now();
+        const { options } = this;
+        // 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
+                ? 'none'
+                : (configuredTransport(context.app.config, options.bus) ?? 'unknown');
+            if (transport !== '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 ' +
+                        '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).');
+            }
+        }
+        const bus = options.bus === undefined ? undefined : context.getDependency(events).bus(options.bus);
+        const gateway = new Gateway(context, context.getDependency(web), options, bus, context.getOptionalDependency(health));
+        context.defer(() => gateway.close());
+        this.#gateway = gateway;
+        await gateway.subscribe();
+        context.logger.log('debug', 'SSE setup finished', {
+            bus: options.bus ?? null,
+            busEvent: options.busEvent,
+            cluster: cluster.isWorker ? '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.1.0',
+    core: '^0.2.0',
+    options: parseOptions,
+    dependencies: ({ options }) => options.bus === undefined ? [web, health] : [web, events, health],
+    instance: ({ options }) => new SseRuntime(options),
+});
+/** 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',
+    load: () => import('./index.js'),
+});

package/dist/types.d.ts

@@ -0,0 +1,132 @@
+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;
+}
+/** 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,73 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "type": "object",
+  "additionalProperties": false,
+  "properties": {
+    "bus": {
+      "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."
+    },
+    "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 SSE_LOCAL_IN_CLUSTER. The bus transport 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."
+    },
+    "closeTimeoutMs": {
+      "type": "integer",
+      "minimum": 1,
+      "maximum": 600000,
+      "default": 2000,
+      "description": "How long drain waits for streams to end after dokebi-restart before cutting them."
+    }
+  }
+}