@dokebi/sse 0.0.0-stage → 0.1.0

package/dist/client/index.js

@@ -0,0 +1,353 @@
+// `@dokebi/sse/client` — the browser side of @dokebi/sse. Browser only, no node: imports, and
+// nothing touches window, location or EventSource until connectEvents() runs (safe to import
+// during server rendering).
+//
+//   const events = connectEvents({ path: '/events', version: APP_VERSION })
+//   const off = events.on('order.changed', (order) => render(order))
+//
+// What EventSource can and cannot tell:
+// - It never exposes the HTTP status. A refused stream (401, 403, 503, a wrong content type)
+//   only fires `error` with readyState CLOSED, and the browser stops for good.
+// - A stream that ended or a network that dropped fires `error` with readyState CONNECTING; the
+//   browser reconnects by itself after the server's `retry:` and sends `Last-Event-ID`.
+// - It does not expose `retry:` either, so the server repeats it as `dokebi-open` data.
+// This client lets the browser handle the second case and handles the first itself: it closes
+// the EventSource, asks the same URL with `dokebiProbe=1` (the server answers 204, 401, 403 or
+// 503 without opening a stream) and stops on 401/403; anything else reopens with backoff and
+// jitter, never sooner than the server's `retry:`. A reopened EventSource cannot send
+// `Last-Event-ID`, so the last id seen goes in the `lastEventId` query, which the server reads.
+//
+// Seal hosts (D-0062): the server seals the `data` of every event of the stream (`E:<ts>:…`, the
+// key holds the stream path). Pass the seal bridge of @dokebi/seal (`currentSealBridge()` of
+// `@dokebi/seal/http`) as `seal`; it is undefined on a plain host, so the same page code runs on
+// both. With a bridge, plain data is refused; without one, sealed data is (fail closed).
+const CLOSED = 2;
+const RELOAD = 'dokebi-reload';
+const RESTART = 'dokebi-restart';
+const OPEN = 'dokebi-open';
+/** The `retryMs` of the server's own `{"retryMs":N}` data (dokebi-open, dokebi-restart). */
+function retryOf(text) {
+    const match = /^\{"retryMs":(\d{1,9})\}$/.exec(text);
+    return match ? Number(match[1]) : undefined;
+}
+/** Opens an event stream (browser only). */
+export function connectEvents(options) {
+    const Source = options.EventSource ?? globalThis.EventSource;
+    const reconnecting = options.reconnect !== false;
+    const minMs = options.reconnect === false ? 0 : Math.max(0, options.reconnect?.minMs ?? 1000);
+    const maxMs = options.reconnect === false ? 0 : Math.max(minMs, options.reconnect?.maxMs ?? 30_000);
+    const handlers = new Map();
+    const dispatchers = new Map();
+    const statusHandlers = new Set();
+    const errorHandlers = new Set();
+    let source;
+    let status = 'connecting';
+    let lastEventId;
+    let serverRetry = 0;
+    let attempt = 0;
+    let timer;
+    let stopped = false;
+    let paused = false;
+    /** The next open is this client's own (not the browser's): it carries lastEventId. */
+    let manual = false;
+    const base = options.url ?? options.path;
+    if (typeof base !== 'string' || !base)
+        throw new TypeError('connectEvents needs url or path');
+    const seal = options.seal;
+    if (seal !== undefined && typeof seal?.unsealFrame !== 'function')
+        throw new TypeError('connectEvents seal needs unsealFrame(frame, url)');
+    let streamPath;
+    function setStatus(next) {
+        if (status === next)
+            return;
+        status = next;
+        options.onStatus?.(next);
+        for (const handler of [...statusHandlers])
+            handler(next);
+    }
+    function report(error) {
+        if (!options.onError && !errorHandlers.size) {
+            console.warn(`[dokebi-sse] ${error.code}`, error.error ?? error.status ?? '');
+            return;
+        }
+        options.onError?.(error);
+        for (const handler of [...errorHandlers])
+            handler(error);
+    }
+    function address(extra) {
+        const page = globalThis.location?.href;
+        const url = new URL(base, page);
+        for (const [name, value] of Object.entries(options.query ?? {}))
+            if (value !== undefined && value !== null)
+                url.searchParams.set(name, String(value));
+        if (options.version !== undefined)
+            url.searchParams.set('dokebiVersion', options.version);
+        if (manual && lastEventId !== undefined)
+            url.searchParams.set('lastEventId', lastEventId);
+        for (const [name, value] of Object.entries(extra ?? {}))
+            url.searchParams.set(name, value);
+        // The key path of a sealed stream: what the browser sends, without the query.
+        streamPath = url.pathname;
+        return url.href;
+    }
+    /** The event's data as text: opened on a sealed stream; undefined (reported) when refused. */
+    function textOf(event, raw) {
+        const sealed = raw.startsWith('E:');
+        if (!seal) {
+            if (!sealed)
+                return raw;
+            report({ code: 'SEAL_BRIDGE_MISSING', event });
+            return undefined;
+        }
+        try {
+            if (!sealed)
+                throw new Error('plain data on a sealed stream');
+            return seal.unsealFrame(raw, streamPath ?? '/');
+        }
+        catch (error) {
+            report({ code: 'SEAL_FAILED', event, error });
+            return undefined;
+        }
+    }
+    function dispatcher(event) {
+        return (message) => {
+            if (message.lastEventId)
+                lastEventId = message.lastEventId;
+            const text = textOf(event, message.data);
+            if (text === undefined)
+                return;
+            let data;
+            try {
+                data = JSON.parse(text);
+            }
+            catch (error) {
+                report({ code: 'BAD_DATA', event, error });
+                return;
+            }
+            const meta = { event, id: message.lastEventId || undefined };
+            for (const handler of [...(handlers.get(event) ?? [])])
+                try {
+                    handler(data, meta);
+                }
+                catch (error) {
+                    report({ code: 'HANDLER_FAILED', event, error });
+                }
+        };
+    }
+    function clearTimer() {
+        if (timer !== undefined)
+            clearTimeout(timer);
+        timer = undefined;
+    }
+    function drop() {
+        if (!source)
+            return;
+        source.onopen = null;
+        source.onerror = null;
+        source.close();
+        source = undefined;
+    }
+    function open() {
+        clearTimer();
+        if (stopped || paused)
+            return;
+        if (!Source) {
+            stopped = true;
+            setStatus('closed');
+            report({ code: 'NO_EVENTSOURCE' });
+            return;
+        }
+        const es = new Source(address(), options.withCredentials ? { withCredentials: true } : undefined);
+        source = es;
+        es.onopen = () => {
+            if (source !== es)
+                return;
+            attempt = 0;
+            setStatus('open');
+        };
+        es.onerror = () => {
+            if (source === es)
+                failed(es);
+        };
+        es.addEventListener(OPEN, (message) => {
+            serverRetry = retryOf(textOf(OPEN, message.data) ?? '') ?? serverRetry;
+        });
+        es.addEventListener(RELOAD, (message) => {
+            // A reload that does not open on a sealed stream is not obeyed (it may not be the server's).
+            if (source === es && textOf(RELOAD, message.data) !== undefined)
+                reload();
+        });
+        es.addEventListener(RESTART, (message) => {
+            if (source !== es)
+                return;
+            serverRetry = retryOf(textOf(RESTART, message.data) ?? '') ?? serverRetry;
+            // The server is stopping (a deploy, a rolling restart): reopen, spread out by jitter so
+            // its clients do not all land on the other workers at the same moment.
+            drop();
+            setStatus('reconnecting');
+            later();
+        });
+        for (const [event, listener] of dispatchers)
+            es.addEventListener(event, listener);
+    }
+    function failed(es) {
+        if (es.readyState !== CLOSED) {
+            // The browser reconnects by itself (after `retry:`, with Last-Event-ID).
+            setStatus('reconnecting');
+            return;
+        }
+        drop();
+        if (!reconnecting) {
+            stopped = true;
+            setStatus('closed');
+            report({ code: 'CONNECTION_FAILED' });
+            return;
+        }
+        setStatus('reconnecting');
+        const fetcher = globalThis.fetch;
+        if (options.probe === false || !fetcher) {
+            report({ code: 'CONNECTION_FAILED' });
+            later();
+            return;
+        }
+        void probe(fetcher);
+    }
+    async function probe(fetcher) {
+        let answer;
+        try {
+            const response = await fetcher(address({ dokebiProbe: '1' }), {
+                credentials: options.withCredentials ? 'include' : 'same-origin',
+                cache: 'no-store',
+            });
+            answer = response.status;
+        }
+        catch (error) {
+            report({ code: 'CONNECTION_FAILED', error });
+            later();
+            return;
+        }
+        if (stopped || paused)
+            return;
+        if (answer === 401 || answer === 403) {
+            stopped = true;
+            clearTimer();
+            setStatus('closed');
+            report({ code: answer === 401 ? 'UNAUTHORIZED' : 'FORBIDDEN', status: answer });
+            return;
+        }
+        report({ code: answer === 503 ? 'UNAVAILABLE' : 'CONNECTION_FAILED', status: answer });
+        later();
+    }
+    /** Reopens after full-jitter backoff: between half and all of min(max, base · 2^attempt). */
+    function later() {
+        clearTimer();
+        if (stopped || paused)
+            return;
+        if (!reconnecting) {
+            stopped = true;
+            setStatus('closed');
+            return;
+        }
+        const floor = Math.max(minMs, serverRetry);
+        const ceiling = Math.min(Math.max(maxMs, floor), floor * 2 ** attempt);
+        attempt = Math.min(attempt + 1, 20);
+        manual = true;
+        timer = setTimeout(open, Math.round(ceiling / 2 + (Math.random() * ceiling) / 2));
+    }
+    function reload() {
+        stopped = true;
+        drop();
+        clearTimer();
+        setStatus('closed');
+        if (options.onReload)
+            options.onReload();
+        else
+            globalThis.location?.reload();
+    }
+    const page = globalThis;
+    // The back/forward cache keeps a hidden page's connections open; close it while hidden.
+    const onHide = (event) => {
+        if (!event.persisted || stopped)
+            return;
+        paused = true;
+        drop();
+        clearTimer();
+        setStatus('paused');
+    };
+    const onShow = (event) => {
+        if (!event.persisted || stopped || !paused)
+            return;
+        paused = false;
+        attempt = 0;
+        manual = true;
+        setStatus('connecting');
+        open();
+    };
+    page.addEventListener?.('pagehide', onHide);
+    page.addEventListener?.('pageshow', onShow);
+    const client = {
+        get status() {
+            return status;
+        },
+        get lastEventId() {
+            return lastEventId;
+        },
+        on(event, handler) {
+            if (typeof event !== 'string' || !event || typeof handler !== 'function')
+                throw new TypeError('on(event, handler) needs an event name and a function');
+            let set = handlers.get(event);
+            if (!set) {
+                set = new Set();
+                handlers.set(event, set);
+                const listener = dispatcher(event);
+                dispatchers.set(event, listener);
+                source?.addEventListener(event, listener);
+            }
+            const entry = handler;
+            set.add(entry);
+            return () => {
+                const current = handlers.get(event);
+                if (!current?.delete(entry) || current.size)
+                    return;
+                handlers.delete(event);
+                const listener = dispatchers.get(event);
+                dispatchers.delete(event);
+                if (listener)
+                    source?.removeEventListener(event, listener);
+            };
+        },
+        onStatus(handler) {
+            statusHandlers.add(handler);
+            return () => statusHandlers.delete(handler);
+        },
+        onError(handler) {
+            errorHandlers.add(handler);
+            return () => errorHandlers.delete(handler);
+        },
+        close() {
+            stopped = true;
+            paused = false;
+            drop();
+            clearTimer();
+            page.removeEventListener?.('pagehide', onHide);
+            page.removeEventListener?.('pageshow', onShow);
+            setStatus('closed');
+        },
+        reconnect() {
+            const wasStopped = stopped;
+            stopped = false;
+            paused = false;
+            attempt = 0;
+            manual = source !== undefined || manual;
+            drop();
+            if (wasStopped) {
+                page.addEventListener?.('pagehide', onHide);
+                page.addEventListener?.('pageshow', onShow);
+            }
+            setStatus('connecting');
+            open();
+        },
+    };
+    open();
+    return client;
+}

package/dist/client/react.d.ts

@@ -0,0 +1,18 @@
+import { type EventHandler, type EventsClient, type EventsOptions, type EventsStatus } from './index.js';
+export interface UseEvents {
+    readonly status: EventsStatus;
+    /** Undefined until the effect ran (the first render, server rendering). */
+    readonly client: EventsClient | undefined;
+}
+/** Connects (shared, ref-counted) in an effect and follows the stream's status. */
+export declare function useEvents(options: EventsOptions): UseEvents;
+/** Shares one stream with every useEvent(name, handler) below it. */
+export declare function EventsProvider(props: {
+    readonly options: EventsOptions;
+    readonly children?: unknown;
+}): unknown;
+/**
+ * Listens to one event of `events` (a useEvents result) or, without it, of the nearest
+ * EventsProvider. The latest handler is called; changing it does not resubscribe.
+ */
+export declare function useEvent<T = unknown>(name: string, handler: EventHandler<T>, events?: UseEvents): void;

package/dist/client/react.js

@@ -0,0 +1,96 @@
+// `@dokebi/sse/client/react` — React hooks. Streams are shared: every useEvents with the same
+// url/path/query/version/withCredentials uses one EventSource, counted by reference and closed
+// a tick after the last user unmounts (StrictMode's mount-unmount-mount keeps the same stream).
+//
+//   const events = useEvents({ path: '/events', version: APP_VERSION })
+//   useEvent('order.changed', (order) => setOrders((list) => [...list, order]), events)
+//
+//   <EventsProvider options={{ path: '/events' }}><Orders /></EventsProvider>
+//   function Orders() { useEvent('order.changed', (order) => ...) }   // from the provider
+import { createContext, createElement, useContext, useEffect, useRef, useState } from 'react';
+import { connectEvents, } from './index.js';
+const shared = new Map();
+function keyOf(options) {
+    return JSON.stringify([
+        options.url ?? null,
+        options.path ?? null,
+        options.query ?? null,
+        options.version ?? null,
+        options.withCredentials === true,
+        options.seal !== undefined,
+    ]);
+}
+/** The shared stream for these options; the first user's callbacks and reconnect settings win. */
+function acquire(options) {
+    const key = keyOf(options);
+    const found = shared.get(key);
+    if (found) {
+        if (found.timer !== undefined)
+            clearTimeout(found.timer);
+        found.timer = undefined;
+        found.refs++;
+        return found;
+    }
+    const entry = { key, client: connectEvents(options), refs: 1, timer: undefined };
+    shared.set(key, entry);
+    return entry;
+}
+function release(entry) {
+    if (--entry.refs > 0)
+        return;
+    entry.timer = setTimeout(() => {
+        if (entry.refs > 0)
+            return;
+        shared.delete(entry.key);
+        entry.client.close();
+    }, 0);
+}
+/** Connects (shared, ref-counted) in an effect and follows the stream's status. */
+export function useEvents(options) {
+    const latest = useRef(options);
+    latest.current = options;
+    const [client, setClient] = useState(undefined);
+    const [status, setStatus] = useState('connecting');
+    const key = keyOf(options);
+    // biome-ignore lint/correctness/useExhaustiveDependencies: key is what identifies the stream; the latest callbacks are read through the ref.
+    useEffect(() => {
+        const current = latest.current;
+        const entry = acquire({
+            ...current,
+            ...(current.onReload ? { onReload: () => latest.current.onReload?.() } : {}),
+            ...(current.onError ? { onError: (error) => latest.current.onError?.(error) } : {}),
+        });
+        setClient(entry.client);
+        setStatus(entry.client.status);
+        const off = entry.client.onStatus((next) => {
+            setStatus(next);
+            latest.current.onStatus?.(next);
+        });
+        return () => {
+            off();
+            release(entry);
+            setClient(undefined);
+        };
+    }, [key]);
+    return { status, client };
+}
+const EventsContext = createContext(undefined);
+/** Shares one stream with every useEvent(name, handler) below it. */
+export function EventsProvider(props) {
+    const events = useEvents(props.options);
+    return createElement(EventsContext.Provider, { value: events }, props.children);
+}
+/**
+ * Listens to one event of `events` (a useEvents result) or, without it, of the nearest
+ * EventsProvider. The latest handler is called; changing it does not resubscribe.
+ */
+export function useEvent(name, handler, events) {
+    const provided = useContext(EventsContext);
+    const source = events ?? provided;
+    if (!source)
+        throw new Error('useEvent needs a useEvents() result or an <EventsProvider>');
+    const latest = useRef(handler);
+    latest.current = handler;
+    const client = source.client;
+    useEffect(() => client?.on(name, (data, meta) => latest.current(data, meta)), [client, name]);
+}

package/dist/client/vue.d.ts

@@ -0,0 +1,15 @@
+import type { ShallowRef } from 'vue';
+import { type EventHandler, type EventsClient, type EventsOptions, type EventsStatus } from './index.js';
+export interface UseEvents {
+    readonly status: Readonly<ShallowRef<EventsStatus>>;
+    /** The client once connected (after mount); undefined before. */
+    readonly client: Readonly<ShallowRef<EventsClient | undefined>>;
+    /** Listens to one event; works before mount too (attached when the stream opens). */
+    on<T = unknown>(event: string, handler: EventHandler<T>): () => void;
+    close(): void;
+    reconnect(): void;
+}
+/** Opens the stream on mount (or at once outside a component) and closes it on scope dispose. */
+export declare function useEvents(options: EventsOptions): UseEvents;
+/** Listens to one event of `events` until the current scope ends (or the returned function). */
+export declare function useEvent<T = unknown>(events: Pick<UseEvents, 'on'> | EventsClient, event: string, handler: EventHandler<T>): () => void;

package/dist/client/vue.js

@@ -0,0 +1,64 @@
+// `@dokebi/sse/client/vue` — Vue 3 composables. The stream opens when the component mounts (never
+// during server rendering) and closes when its scope ends.
+//
+//   const events = useEvents({ path: '/events', version: APP_VERSION })
+//   useEvent(events, 'order.changed', (order) => orders.value.push(order))
+//   // template: events.status.value === 'open'
+import { getCurrentInstance, getCurrentScope, onMounted, onScopeDispose, shallowRef } from 'vue';
+import { connectEvents, } from './index.js';
+/** Opens the stream on mount (or at once outside a component) and closes it on scope dispose. */
+export function useEvents(options) {
+    const status = shallowRef('connecting');
+    const client = shallowRef(undefined);
+    const subscriptions = new Set();
+    let disposed = false;
+    const connect = () => {
+        if (client.value || disposed)
+            return;
+        const connected = connectEvents({
+            ...options,
+            onStatus: (next) => {
+                status.value = next;
+                options.onStatus?.(next);
+            },
+        });
+        client.value = connected;
+        status.value = connected.status;
+        for (const subscription of subscriptions)
+            subscription.off = connected.on(subscription.event, subscription.handler);
+    };
+    if (getCurrentInstance())
+        onMounted(connect);
+    else
+        connect();
+    if (getCurrentScope())
+        onScopeDispose(() => {
+            disposed = true;
+            client.value?.close();
+        });
+    return {
+        status,
+        client,
+        on(event, handler) {
+            const subscription = {
+                event,
+                handler: handler,
+                off: client.value?.on(event, handler),
+            };
+            subscriptions.add(subscription);
+            return () => {
+                subscriptions.delete(subscription);
+                subscription.off?.();
+            };
+        },
+        close: () => client.value?.close(),
+        reconnect: () => client.value?.reconnect(),
+    };
+}
+/** Listens to one event of `events` until the current scope ends (or the returned function). */
+export function useEvent(events, event, handler) {
+    const off = events.on(event, handler);
+    if (getCurrentScope())
+        onScopeDispose(off);
+    return off;
+}

package/dist/errors.d.ts

@@ -0,0 +1,12 @@
+export type SseErrorCode = 'INVALID_OPTIONS' | 'INVALID_ROUTE' | 'INVALID_IDENTITY' | 'INVALID_EVENT' | 'INVALID_DATA' | 'INVALID_TARGET' | 'INVALID_ROOM' | 'EVENT_TOO_LARGE' | 'ROOM_LIMIT' | 'FROZEN' | 'CLOSED' | 'BUS_UNAVAILABLE' | 'BUS_PUBLISH_FAILED' | 'SSE_LOCAL_IN_CLUSTER';
+/** Errors of @dokebi/sse; compare `code`, not the class (another copy of the package may throw). */
+export declare class SseError extends Error {
+    readonly code: SseErrorCode;
+    /** BUS_PUBLISH_FAILED: the event id and how many streams of this process already got it. */
+    readonly id?: string;
+    readonly local?: number;
+    constructor(code: SseErrorCode, message: string, options?: ErrorOptions & {
+        readonly id?: string;
+        readonly local?: number;
+    });
+}

package/dist/errors.js

@@ -0,0 +1,16 @@
+/** Errors of @dokebi/sse; compare `code`, not the class (another copy of the package may throw). */
+export class SseError extends Error {
+    code;
+    /** BUS_PUBLISH_FAILED: the event id and how many streams of this process already got it. */
+    id;
+    local;
+    constructor(code, message, options) {
+        super(message, options);
+        this.code = code;
+        this.name = 'SseError';
+        if (options?.id !== undefined)
+            this.id = options.id;
+        if (options?.local !== undefined)
+            this.local = options.local;
+    }
+}

package/dist/gateway.d.ts

@@ -0,0 +1,41 @@
+import type { PluginContext } from '@dokebi/core';
+import type { WebApi } from '@dokebi/web';
+import type { Options } from './options.js';
+import { type SseApi } from './types.js';
+/** The part of a dokebi-event-bus bus this plugin uses (never imported: the bus is optional). */
+export interface SseBus {
+    readonly state: string;
+    subscribe(event: string, handler: (payload: unknown) => void): {
+        readonly ready: Promise<void>;
+        unsubscribe(): Promise<void>;
+    };
+    publish(event: string, payload: unknown): Promise<{
+        readonly id: string;
+    }>;
+}
+/** The part of dokebi-health this plugin uses. */
+export interface SseHealth {
+    register(name: string, options?: {
+        readonly required?: boolean;
+    }): {
+        ready(): void;
+        fail(reason: string): void;
+        dispose(): void;
+    };
+}
+export declare class Gateway {
+    #private;
+    readonly context: PluginContext;
+    readonly web: WebApi;
+    readonly options: Options;
+    readonly bus: SseBus | undefined;
+    readonly api: SseApi;
+    constructor(context: PluginContext, web: WebApi, options: Options, bus: SseBus | undefined, health: SseHealth | undefined);
+    /** Subscribes to the bus (setup): every process on it delivers to its own matching streams. */
+    subscribe(): Promise<void>;
+    start(): void;
+    /** Sends `dokebi-restart` to every stream, ends them, and cuts the rest at the deadline. */
+    drain(signal: AbortSignal): Promise<void>;
+    /** Cleanup: after a failed start no drain ran, so streams may still be open. */
+    close(): void;
+}