ds-harness-remote-fast/packages/plugin/src/control-stream.ts

195 lines
6.7 KiB
TypeScript

/**
* 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<StreamSubscriber>()
private readonly sampleIntervalMs: number
private readonly heartbeatIntervalMs: number
private readonly retryMs: number
private timer: ReturnType<typeof setInterval> | 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<unknown>,
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<void> {
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<void> {
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<string | undefined> {
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
}
}
}