@dokebi/sse 0.0.0-stage → 0.1.0

package/dist/gateway.js

@@ -0,0 +1,733 @@
+import { randomBytes, randomUUID } from 'node:crypto';
+import { setTimeout as delay } from 'node:timers/promises';
+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:`). */
+const RELOAD_RETRY_MS = 60_000;
+/** How often the bus state is read for health and the warn/info log of a change. */
+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)
+        set.add(entry);
+    else
+        map.set(name, new Set([entry]));
+}
+function remove(map, name, entry) {
+    const set = map.get(name);
+    if (!set)
+        return;
+    set.delete(entry);
+    if (!set.size)
+        map.delete(name);
+}
+function checkRoom(room) {
+    if (!text(room))
+        throw new SseError('INVALID_ROOM', 'Rooms are strings of 1 to 256 characters.');
+    return room;
+}
+function checkTarget(target) {
+    const value = target;
+    if (!value ||
+        typeof value !== 'object' ||
+        (value.tenant === undefined) === (value.tenantPrefix === undefined) ||
+        (value.tenant !== undefined && !text(value.tenant)) ||
+        (value.tenantPrefix !== undefined && !text(value.tenantPrefix)) ||
+        (value.member !== undefined && !text(value.member)) ||
+        (value.room !== undefined && !text(value.room)))
+        throw new SseError('INVALID_TARGET', 'A target is { tenant } or { tenantPrefix }, with member? and room?, strings of 1 to 256 characters.');
+    return Object.freeze({
+        ...(value.tenant === undefined
+            ? { tenantPrefix: value.tenantPrefix }
+            : { tenant: value.tenant }),
+        ...(value.member === undefined ? {} : { member: value.member }),
+        ...(value.room === undefined ? {} : { room: value.room }),
+    });
+}
+/** Allow-list entries must be exact http(s) origins such as `https://app.example.com`. */
+function parseOrigins(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === '*')
+        return '*';
+    if (!Array.isArray(value))
+        throw new SseError('INVALID_ROUTE', 'origins must be a list or *.');
+    const result = new Set();
+    for (const item of value) {
+        const url = typeof item === 'string' && URL.canParse(item) ? new URL(item) : undefined;
+        if (!url || (url.protocol !== 'http:' && url.protocol !== 'https:') || url.origin !== item)
+            throw new SseError('INVALID_ROUTE', 'origins entries are exact origins (https://host).');
+        result.add(url.origin);
+    }
+    return result;
+}
+/**
+ * The CORS answer to a request's Origin: undefined for same-origin (or non-browser) requests,
+ * headers for an allowed foreign origin, false for a forbidden one. EventSource sends Origin on
+ * cross-origin requests only, so a page's own stream needs no allow-list.
+ */
+function cors(origin, host, allowed) {
+    if (origin === undefined)
+        return undefined;
+    if (typeof origin !== 'string' || !URL.canParse(origin))
+        return false;
+    const url = new URL(origin);
+    if (url.protocol !== 'http:' && url.protocol !== 'https:')
+        return false;
+    const own = `${url.protocol}//${host}`;
+    if (host && URL.canParse(own) && new URL(own).host === url.host)
+        return undefined;
+    if (allowed === '*')
+        return { 'access-control-allow-origin': '*' };
+    if (allowed?.has(url.origin))
+        return {
+            'access-control-allow-origin': url.origin,
+            'access-control-allow-credentials': 'true',
+            vary: 'Origin',
+        };
+    return false;
+}
+function single(value) {
+    return Array.isArray(value) ? value[0] : value;
+}
+export class Gateway {
+    context;
+    web;
+    options;
+    bus;
+    api;
+    #entries = new Map();
+    #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();
+    #throttle;
+    /** Event ids: `<prefix>-<counter>`; the prefix tells processes apart, the counter only grows. */
+    #prefix = randomBytes(4).toString('hex');
+    /** Who published a bus message, so this process skips its own (it delivered them already). */
+    #origin = randomUUID();
+    #sequence = 0;
+    #routes = 0;
+    #frozen = false;
+    #closing = false;
+    #heartbeat;
+    #watch;
+    #subscription;
+    #health;
+    #busUp;
+    constructor(context, web, options, bus, health) {
+        this.context = context;
+        this.web = web;
+        this.options = options;
+        this.bus = bus;
+        this.#throttle = new LogThrottle(context.logger);
+        if (health) {
+            this.#health = health.register('sse', { required: false });
+            const handle = this.#health;
+            context.defer(() => handle.dispose());
+        }
+        const self = this;
+        this.api = Object.freeze({
+            route: (route) => this.#route(route),
+            publish: (target, event, data) => this.#publish(target, event, data),
+            connections: (filter) => this.#count(filter),
+            get bus() {
+                return self.options.bus;
+            },
+        });
+    }
+    /** Subscribes to the bus (setup): every process on it delivers to its own matching streams. */
+    async subscribe() {
+        if (!this.bus)
+            return;
+        const subscription = this.bus.subscribe(this.options.busEvent, (payload) => this.#fromBus(payload));
+        this.#subscription = subscription;
+        await subscription.ready;
+        this.context.logger.log('debug', 'SSE bus subscribed', {
+            bus: this.options.bus,
+            event: this.options.busEvent,
+            origin: this.#origin,
+        });
+    }
+    #route(route) {
+        if (this.#frozen || this.context.app.state !== 'starting')
+            throw new SseError('FROZEN', 'Register SSE routes during setup.');
+        if (!route ||
+            typeof route.path !== 'string' ||
+            !/^\/[^?#\s]{0,2047}$/.test(route.path) ||
+            typeof route.authenticate !== 'function' ||
+            (route.onOpen !== undefined && typeof route.onOpen !== 'function') ||
+            (route.onClose !== undefined && typeof route.onClose !== 'function') ||
+            (route.version !== undefined && (!text(route.version) || !isLine(route.version))) ||
+            (route.constraints !== undefined &&
+                (typeof route.constraints !== 'object' || route.constraints === null)))
+            throw new SseError('INVALID_ROUTE', 'Invalid SSE route.');
+        const registered = {
+            route: Object.freeze({ ...route }),
+            origins: parseOrigins(route.origins),
+        };
+        this.web.route({
+            method: 'GET',
+            url: route.path,
+            // A HEAD request would open a stream whose body Node discards: answer only GET.
+            exposeHeadRoute: false,
+            ...(route.constraints ? { constraints: { ...route.constraints } } : {}),
+            handler: (request, reply) => this.#open(request, reply, registered),
+        });
+        this.#routes++;
+        this.context.logger.log('debug', 'SSE route registered', {
+            path: route.path,
+            version: route.version ?? null,
+            origins: registered.origins === '*' ? '*' : registered.origins ? registered.origins.size : null,
+        });
+    }
+    /** Why a new stream is refused now, or undefined. */
+    #refusal() {
+        if (this.#closing)
+            return 'CLOSING';
+        if (this.#entries.size >= this.options.maxConnections)
+            return 'CAPACITY';
+        return undefined;
+    }
+    async #open(request, reply, registered) {
+        const { route } = registered;
+        const logger = this.context.logger;
+        const allowed = cors(request.headers.origin, this.web.requestHost(request), registered.origins);
+        if (allowed === false) {
+            if (logger.isEnabled('debug'))
+                logger.log('debug', 'SSE origin refused', {
+                    path: route.path,
+                    origin: String(request.headers.origin).slice(0, 200),
+                });
+            return reply.code(403).send({ error: 'ORIGIN_FORBIDDEN' });
+        }
+        let refused = this.#refusal();
+        if (refused) {
+            logger.log('debug', 'SSE stream refused', { path: route.path, reason: refused });
+            return reply
+                .code(503)
+                .header('retry-after', '5')
+                .send({ error: 'UNAVAILABLE', reason: refused });
+        }
+        const identity = await route.authenticate(request);
+        if (!identity) {
+            if (logger.isEnabled('debug'))
+                logger.log('debug', 'SSE stream unauthorized', { path: route.path });
+            return reply.code(401).send({ error: 'UNAUTHORIZED' });
+        }
+        // An invalid identity is an application bug: dokebi-web answers 500 and logs it.
+        const rooms = this.#identity(identity);
+        const query = (request.query ?? {});
+        // The browser client asks this after EventSource failed, to tell 401/403 from an outage.
+        if (query.dokebiProbe !== undefined)
+            return reply
+                .code(204)
+                .headers(allowed ?? {})
+                .send();
+        refused = this.#refusal();
+        if (refused) {
+            logger.log('debug', 'SSE stream refused', { path: route.path, reason: refused });
+            return reply
+                .code(503)
+                .header('retry-after', '5')
+                .send({ error: 'UNAVAILABLE', reason: refused });
+        }
+        const res = reply.raw;
+        const headers = { ...HEADERS, ...allowed };
+        // D-0062: a stream of a seal host seals the data of every event, its first ones included.
+        const seal = this.web.sealOf(request);
+        const data = (json) => (seal ? seal.encode(json) : json);
+        if (route.version !== undefined) {
+            const sent = single(query.dokebiVersion) ?? single(request.headers['x-dokebi-version']);
+            if (sent !== route.version) {
+                logger.log('debug', 'SSE version refused; reload sent', {
+                    path: route.path,
+                    expected: route.version,
+                    received: typeof sent === 'string' ? sent.slice(0, 64) : null,
+                });
+                reply.hijack();
+                res.writeHead(200, headers);
+                res.end(`retry: ${RELOAD_RETRY_MS}\n${frame(undefined, RELOAD_EVENT, data(JSON.stringify({ version: route.version })))}`);
+                return;
+            }
+        }
+        const header = single(request.headers['last-event-id']);
+        const asked = header ?? single(query.lastEventId);
+        const lastEventId = typeof asked === 'string' && asked.length <= MAX_TEXT && isLine(asked) ? asked : undefined;
+        reply.hijack();
+        if (res.destroyed || !res.socket || res.socket.destroyed) {
+            logger.log('debug', 'SSE client left before the stream opened', { path: route.path });
+            return;
+        }
+        res.writeHead(200, headers);
+        // The reconnect hint first, and the same value as data for clients that manage reconnects
+        // themselves (EventSource does not expose `retry:`).
+        res.write(`retry: ${this.options.retryMs}\n${frame(undefined, OPEN_EVENT, data(JSON.stringify({ retryMs: this.options.retryMs })))}`);
+        const entry = this.#add(res, identity, route, rooms, lastEventId, seal);
+        res.once('close', () => this.#closed(entry));
+        res.on('error', (error) => {
+            entry.reason ??= 'WRITE_FAILED';
+            const code = 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 });
+        });
+        if (logger.isEnabled('debug'))
+            logger.log('debug', 'SSE stream opened', {
+                stream: entry.id,
+                path: route.path,
+                tenant: entry.tenant,
+                member: entry.member,
+                rooms: rooms.length,
+                sealed: seal !== undefined,
+                lastEventId: lastEventId ?? null,
+                remote: `${request.socket.remoteAddress ?? '?'}:${request.socket.remotePort ?? '?'}`,
+                open: this.#entries.size,
+            });
+        if (route.onOpen) {
+            const onOpen = route.onOpen;
+            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, {
+                    path: route.path,
+                    stream: entry.id,
+                });
+                this.#end(entry, 'ON_OPEN_FAILED');
+            }));
+        }
+    }
+    #identity(identity) {
+        const rooms = identity.rooms ?? [];
+        if (typeof identity !== 'object' ||
+            !text(identity.tenant) ||
+            !text(identity.member) ||
+            !Array.isArray(rooms))
+            throw new SseError('INVALID_IDENTITY', 'authenticate must return { tenant, member, rooms? } with strings of 1 to 256 characters.');
+        const unique = [...new Set(rooms.map(checkRoom))];
+        if (unique.length > this.options.maxRooms)
+            throw new SseError('ROOM_LIMIT', `A stream may be in ${this.options.maxRooms} rooms.`);
+        return unique;
+    }
+    #add(res, identity, route, rooms, lastEventId, seal) {
+        const entry = {
+            id: randomUUID(),
+            res,
+            identity,
+            tenant: identity.tenant,
+            member: identity.member,
+            route,
+            rooms: new Set(),
+            opened: performance.now(),
+            lastEventId,
+            seal,
+            reason: undefined,
+            closed: false,
+            stream: undefined,
+        };
+        entry.stream = Object.freeze({
+            id: entry.id,
+            tenant: entry.tenant,
+            member: entry.member,
+            identity,
+            path: route.path,
+            lastEventId,
+            get rooms() {
+                return [...entry.rooms];
+            },
+            get closed() {
+                return entry.closed || entry.reason !== undefined;
+            },
+            send: (event, data) => {
+                checkEvent(event);
+                const json = encodeData(data, this.options.maxEventBytes);
+                return this.#event(entry, this.#nextId(), event, json);
+            },
+            join: (room) => this.#join(entry, checkRoom(room)),
+            leave: (room) => this.#leave(entry, checkRoom(room)),
+            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);
+        for (const room of rooms)
+            this.#join(entry, room);
+        return entry;
+    }
+    #join(entry, room) {
+        if (entry.closed || entry.rooms.has(room))
+            return;
+        if (entry.rooms.size >= this.options.maxRooms)
+            throw new SseError('ROOM_LIMIT', `A stream may be in ${this.options.maxRooms} rooms.`);
+        entry.rooms.add(room);
+        add(this.#rooms, key(entry.tenant, room), entry);
+        if (this.context.logger.isEnabled('debug'))
+            this.context.logger.log('debug', 'SSE room joined', {
+                stream: entry.id,
+                room: room.slice(0, 64),
+                rooms: entry.rooms.size,
+            });
+    }
+    #leave(entry, room) {
+        if (!entry.rooms.delete(room))
+            return;
+        remove(this.#rooms, key(entry.tenant, room), entry);
+        if (this.context.logger.isEnabled('debug'))
+            this.context.logger.log('debug', 'SSE room left', {
+                stream: entry.id,
+                room: room.slice(0, 64),
+                rooms: entry.rooms.size,
+            });
+    }
+    #nextId() {
+        this.#sequence++;
+        return `${this.#prefix}-${this.#sequence.toString(36)}`;
+    }
+    /**
+     * One event for one stream: the shared plain chunk, or this stream's own sealed frame (D-0062).
+     * A seal that fails ends the stream rather than send the data plain (fail closed).
+     */
+    #event(entry, id, event, json, plain) {
+        if (!entry.seal)
+            return this.#write(entry, plain ?? Buffer.from(frame(id, event, json)));
+        let chunk;
+        try {
+            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, {
+                stream: entry.id,
+                path: entry.route.path,
+            });
+            this.#end(entry, 'WRITE_FAILED', true);
+            return false;
+        }
+        return this.#write(entry, chunk);
+    }
+    /** Queues `chunk` on the stream unless that would pass maxBufferedBytes (then it ends). */
+    #write(entry, chunk) {
+        if (entry.closed || entry.reason !== undefined)
+            return false;
+        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, {
+                stream: entry.id,
+                path: entry.route.path,
+                bufferedBytes: res.writableLength,
+                maxBufferedBytes: this.options.maxBufferedBytes,
+            });
+            // Not end(): its last chunk would wait behind the data the client is not reading.
+            this.#end(entry, 'SLOW_CONSUMER', true);
+            return false;
+        }
+        res.write(chunk);
+        return true;
+    }
+    #end(entry, reason, destroy = false) {
+        if (entry.closed || entry.reason !== undefined)
+            return;
+        entry.reason = reason;
+        if (destroy)
+            entry.res.destroy();
+        else
+            entry.res.end();
+    }
+    #closed(entry) {
+        if (entry.closed)
+            return;
+        entry.closed = true;
+        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);
+        if (this.context.logger.isEnabled('debug'))
+            this.context.logger.log('debug', 'SSE stream closed', {
+                stream: entry.id,
+                path: entry.route.path,
+                member: entry.member,
+                reason,
+                ms: Math.round(performance.now() - entry.opened),
+                open: this.#entries.size,
+            });
+        const onClose = entry.route.onClose;
+        if (onClose)
+            void this.#task(Promise.resolve()
+                .then(() => onClose(entry.stream, reason))
+                .catch((error) => {
+                this.#throttle.report('error', 'SSE onClose failed', 'SSE_ON_CLOSE_FAILED', error, {
+                    path: entry.route.path,
+                    stream: entry.id,
+                    reason,
+                });
+            }));
+    }
+    /** Tracks an onOpen/onClose call (it never rejects: each logs its own failure). */
+    #task(task) {
+        this.#tasks.add(task);
+        return task.finally(() => this.#tasks.delete(task));
+    }
+    #select(target) {
+        if (target.room !== undefined)
+            return this.#rooms.get(key(target.tenant, target.room));
+        if (target.member !== undefined)
+            return this.#members.get(key(target.tenant, target.member));
+        return this.#tenants.get(target.tenant);
+    }
+    /** Writes one event to the matching streams of this process; returns how many took it. */
+    #deliver(target, event, id, json) {
+        if ('tenantPrefix' in target) {
+            // Each tenant under the prefix (D-0061); one stream belongs to one tenant, so none twice.
+            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);
+            return written;
+        }
+        const set = this.#select(target);
+        if (!set?.size)
+            return 0;
+        return this.#writeAll(set, target, { id, event, json, chunk: undefined });
+    }
+    /**
+     * Plain streams share one buffer, made at the first plain recipient; sealed streams each get
+     * their own frame (D-0062, like sealed WebSocket broadcasts).
+     */
+    #writeAll(set, target, shared) {
+        let written = 0;
+        for (const entry of set ?? []) {
+            if (target.room !== undefined &&
+                target.member !== undefined &&
+                entry.member !== target.member)
+                continue;
+            if (!entry.seal)
+                shared.chunk ??= Buffer.from(frame(shared.id, shared.event, shared.json));
+            if (this.#event(entry, shared.id, shared.event, shared.json, shared.chunk))
+                written++;
+        }
+        return written;
+    }
+    async #publish(target, event, data) {
+        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,
+                state: bus.state,
+            });
+            throw error;
+        }
+        const id = this.#nextId();
+        const local = this.#closing ? 0 : this.#deliver(checked, event, id, json);
+        if (bus) {
+            try {
+                await bus.publish(this.options.busEvent, {
+                    v: 1,
+                    id,
+                    origin: this.#origin,
+                    target: checked,
+                    event,
+                    data: json,
+                });
+            }
+            catch (cause) {
+                this.#throttle.report('error', 'SSE bus publish failed', 'BUS_PUBLISH_FAILED', cause, {
+                    bus: this.options.bus,
+                    id,
+                    local,
+                    busCode: 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 });
+            }
+        }
+        if (this.context.logger.isEnabled('debug'))
+            this.context.logger.log('debug', 'SSE published', {
+                id,
+                event,
+                tenant: 'tenant' in checked ? checked.tenant : null,
+                tenantPrefix: 'tenantPrefix' in checked ? checked.tenantPrefix.slice(0, 64) : null,
+                member: checked.member ?? null,
+                room: checked.room?.slice(0, 64) ?? null,
+                local,
+                bus: bus !== undefined,
+            });
+        return Object.freeze({ id, local });
+    }
+    /** A publication from the bus: delivered here unless this process published it. */
+    #fromBus(payload) {
+        const message = payload;
+        let target;
+        if (message &&
+            typeof message === 'object' &&
+            message.v === 1 &&
+            typeof message.id === 'string' &&
+            ID.test(message.id) &&
+            typeof message.origin === 'string' &&
+            typeof message.event === 'string' &&
+            EVENT.test(message.event) &&
+            typeof message.data === 'string' &&
+            isLine(message.data)) {
+            try {
+                target = checkTarget(message.target);
+            }
+            catch (error) {
+                this.#throttle.report('error', 'SSE bus message rejected', 'BUS_MESSAGE_INVALID', error, {
+                    bus: this.options.bus,
+                });
+                return;
+            }
+        }
+        if (!message || !target) {
+            this.#throttle.report('error', 'SSE bus message rejected', 'BUS_MESSAGE_INVALID', undefined, {
+                bus: this.options.bus,
+            });
+            return;
+        }
+        // The publishing process wrote it to its own streams already (exactly once there).
+        if (message.origin === this.#origin || this.#closing)
+            return;
+        const local = this.#deliver(target, message.event, message.id, message.data);
+        if (this.context.logger.isEnabled('debug'))
+            this.context.logger.log('debug', 'SSE bus event delivered', {
+                id: message.id,
+                event: message.event,
+                local,
+            });
+    }
+    #count(filter = {}) {
+        if (filter === null || typeof filter !== 'object')
+            throw new SseError('INVALID_TARGET', 'connections() takes { tenant?, member?, room?, path? }.');
+        let set = this.#entries.values();
+        if (filter.tenant !== undefined) {
+            const narrowed = this.#select(filter);
+            if (!narrowed)
+                return 0;
+            set = narrowed;
+        }
+        let count = 0;
+        for (const entry of set)
+            if ((filter.member === undefined || entry.member === filter.member) &&
+                (filter.room === undefined || entry.rooms.has(filter.room)) &&
+                (filter.path === undefined || entry.route.path === filter.path))
+                count++;
+        return count;
+    }
+    #busState() {
+        const bus = this.bus;
+        if (!bus || this.#closing)
+            return;
+        const up = bus.state === 'ready';
+        if (up === this.#busUp)
+            return;
+        const first = this.#busUp === undefined;
+        this.#busUp = up;
+        if (up) {
+            this.#health?.ready();
+            if (!first)
+                this.context.logger.log('info', 'SSE bus available again', { bus: this.options.bus });
+        }
+        else {
+            this.#health?.fail('BUS_UNAVAILABLE');
+            this.context.logger.log('warn', 'SSE bus unavailable; publications fail', {
+                code: 'BUS_UNAVAILABLE',
+                bus: this.options.bus,
+                state: bus.state,
+            });
+        }
+    }
+    start() {
+        this.#frozen = true;
+        this.#heartbeat = setInterval(() => {
+            for (const entry of this.#entries.values())
+                this.#write(entry, PING);
+        }, this.options.heartbeatMs);
+        this.#heartbeat.unref();
+        if (this.bus) {
+            this.#busState();
+            this.#watch = setInterval(() => this.#busState(), BUS_WATCH_MS);
+            this.#watch.unref();
+        }
+        else
+            this.#health?.ready();
+        this.context.logger.log('debug', 'SSE gateway started', {
+            routes: this.#routes,
+            bus: this.options.bus ?? null,
+            heartbeatMs: this.options.heartbeatMs,
+            retryMs: this.options.retryMs,
+            maxConnections: this.options.maxConnections,
+        });
+    }
+    /** Sends `dokebi-restart` to every stream, ends them, and cuts the rest at the deadline. */
+    async drain(signal) {
+        const started = performance.now();
+        const logger = this.context.logger;
+        this.#closing = true;
+        this.#frozen = true;
+        this.#timers();
+        logger.log('debug', 'SSE drain started', { open: this.#entries.size, tasks: this.#tasks.size });
+        const subscription = this.#subscription;
+        this.#subscription = undefined;
+        if (subscription)
+            try {
+                await subscription.unsubscribe();
+            }
+            catch (error) {
+                this.#throttle.report('error', 'SSE bus unsubscribe failed', 'BUS_UNSUBSCRIBE_FAILED', error, {
+                    bus: this.options.bus,
+                });
+            }
+        const json = JSON.stringify({ retryMs: this.options.retryMs });
+        const restart = Buffer.from(frame(undefined, RESTART_EVENT, json));
+        for (const entry of [...this.#entries.values()]) {
+            this.#event(entry, undefined, RESTART_EVENT, json, restart);
+            this.#end(entry, 'DRAIN');
+        }
+        const deadline = performance.now() + this.options.closeTimeoutMs;
+        while (this.#entries.size && performance.now() < deadline && !signal.aborted)
+            await delay(10);
+        if (this.#entries.size) {
+            logger.log('debug', 'SSE drain cutting streams', {
+                open: this.#entries.size,
+                aborted: signal.aborted,
+            });
+            for (const entry of this.#entries.values())
+                entry.res.destroy();
+        }
+        while (this.#tasks.size && !signal.aborted)
+            await delay(10);
+        this.#throttle.flush();
+        logger.log('debug', 'SSE drain finished', {
+            ms: Math.round(performance.now() - started),
+            aborted: signal.aborted,
+        });
+    }
+    #timers() {
+        if (this.#heartbeat)
+            clearInterval(this.#heartbeat);
+        if (this.#watch)
+            clearInterval(this.#watch);
+        this.#heartbeat = undefined;
+        this.#watch = undefined;
+    }
+    /** Cleanup: after a failed start no drain ran, so streams may still be open. */
+    close() {
+        this.#closing = true;
+        this.#timers();
+        for (const entry of this.#entries.values())
+            entry.res.destroy();
+        this.#throttle.flush();
+    }
+}