diff --git a/packages/plugin/src/control-stream.ts b/packages/plugin/src/control-stream.ts new file mode 100644 index 0000000..85e14ca --- /dev/null +++ b/packages/plugin/src/control-stream.ts @@ -0,0 +1,194 @@ +/** + * Loopback status event stream. One `text/event-stream` response per browser + * control client, fed by an in-process sampler that writes a frame only when the + * serialized Host status changes, so an idle Local-mode page receives nothing + * but keep-alive comments. + * + * The stream is a push carrier for the same value the unary `status` control + * endpoint returns; a reconnecting browser therefore receives the complete + * current status as its first frame instead of waiting for the next change. + */ + +import type { ServerResponse } from 'node:http' + +/** Status sampling period used to detect a change without any client request. */ +export const STATUS_STREAM_SAMPLE_INTERVAL_MS = 1_500 + +/** Comment-frame period that keeps an idle connection observable to both ends. */ +export const STATUS_STREAM_HEARTBEAT_INTERVAL_MS = 15_000 + +/** Reconnect delay advertised to the browser through the SSE `retry` field. */ +export const STATUS_STREAM_RETRY_MS = 3_000 + +/** Sampling and keep-alive periods of {@link ControlStatusStream}. */ +export interface ControlStatusStreamOptions { + sampleIntervalMs?: number + heartbeatIntervalMs?: number + retryMs?: number +} + +interface StreamSubscriber { + readonly response: ServerResponse + /** Last payload written to this subscriber, so a late joiner still gets the current one. */ + payload: string | undefined +} + +const KEEP_ALIVE_FRAME = ': keep-alive\n\n' + +/** + * Owns the loopback status event stream: subscribers, change-detecting sampler, + * and keep-alive frames. Sampling runs only while at least one subscriber is + * attached and stops with the last disconnect. + */ +export class ControlStatusStream { + private readonly subscribers = new Set() + private readonly sampleIntervalMs: number + private readonly heartbeatIntervalMs: number + private readonly retryMs: number + private timer: ReturnType | undefined + private sampling = false + private payload: string | undefined + private writtenAt = 0 + private closed = false + + /** + * @param readStatus - reads the current status value, the same value the unary control endpoint returns. + * @param options - sampling, keep-alive, and reconnect periods. + */ + constructor( + private readonly readStatus: () => Promise, + options: ControlStatusStreamOptions = {}, + ) { + this.sampleIntervalMs = options.sampleIntervalMs ?? STATUS_STREAM_SAMPLE_INTERVAL_MS + this.heartbeatIntervalMs = options.heartbeatIntervalMs ?? STATUS_STREAM_HEARTBEAT_INTERVAL_MS + this.retryMs = options.retryMs ?? STATUS_STREAM_RETRY_MS + } + + /** + * Write the SSE response head, the current status as its first frame, and keep + * pushing until the client disconnects or {@link close} runs. + * @param response - the loopback route response, owned for the connection lifetime. + */ + async handle(response: ServerResponse): Promise { + if (this.closed) { + response.writeHead(503) + response.end() + return + } + response.writeHead(200, { + 'content-type': 'text/event-stream', + 'cache-control': 'no-store', + connection: 'keep-alive', + }) + try { + response.write(`retry: ${String(this.retryMs)}\n\n`) + } catch { + // A client that vanished before its first frame leaves no stream to own. + return + } + const subscriber: StreamSubscriber = { response, payload: undefined } + this.subscribers.add(subscriber) + const detach = (): void => { this.detach(subscriber) } + response.on('close', detach) + response.on('error', detach) + + this.startSampling() + // The first frame is the current status: a fresh page paints from one pushed + // value, and a reconnecting page recovers the latest state immediately. A + // failed read leaves the reader on the last known frame instead of opening + // with nothing. + this.write((await this.readSnapshot()) ?? this.payload) + } + + /** End every open stream and stop sampling. */ + close(): void { + this.closed = true + this.stopSampling() + for (const subscriber of [...this.subscribers]) { + try { + subscriber.response.end() + } catch { + // A client that vanished mid-close has no stream left to end. + } + } + this.subscribers.clear() + this.payload = undefined + } + + /** Forget one subscriber; the last one to leave also stops the sampler. */ + private detach(subscriber: StreamSubscriber): void { + this.subscribers.delete(subscriber) + if (this.subscribers.size === 0) this.stopSampling() + } + + private startSampling(): void { + if (this.closed || this.timer !== undefined) return + this.timer = setInterval(() => { void this.sample() }, this.sampleIntervalMs) + } + + private stopSampling(): void { + if (this.timer === undefined) return + clearInterval(this.timer) + this.timer = undefined + } + + private async sample(): Promise { + if (this.sampling || this.closed) return + this.sampling = true + try { + const snapshot = await this.readSnapshot() + if (snapshot !== undefined && !this.closed) this.write(snapshot) + } finally { + this.sampling = false + } + } + + private async readSnapshot(): Promise { + try { + const value = await this.readStatus() + return value === undefined ? undefined : JSON.stringify(value) ?? undefined + } catch { + // An unreadable status keeps the last frame; the unary control endpoint + // reports the same failure to its own caller. + return undefined + } + } + + /** + * Write the payload to every subscriber that has not seen it, or one + * keep-alive comment when the whole connection set is idle. + */ + private write(snapshot: string | undefined): void { + if (snapshot === undefined || this.subscribers.size === 0) return + const now = Date.now() + const fresh = [...this.subscribers].filter(subscriber => subscriber.payload !== snapshot) + if (fresh.length > 0) { + const frame = `data: ${snapshot}\n\n` + for (const subscriber of fresh) { + if (this.writeChunk(subscriber, frame)) subscriber.payload = snapshot + else this.detach(subscriber) + } + this.payload = snapshot + this.writtenAt = now + return + } + if (now - this.writtenAt < this.heartbeatIntervalMs) return + for (const subscriber of [...this.subscribers]) { + if (!this.writeChunk(subscriber, KEEP_ALIVE_FRAME)) this.detach(subscriber) + } + this.writtenAt = now + } + + /** @returns true when the chunk reached a live response. */ + private writeChunk(subscriber: StreamSubscriber, chunk: string): boolean { + if (subscriber.response.destroyed || subscriber.response.writableEnded) return false + try { + subscriber.response.write(chunk) + return true + } catch { + // A socket error surfaces through the response `error` listener, which + // detaches the subscriber. + return false + } + } +}