diff --git a/packages/plugin/src/status-stream.ts b/packages/plugin/src/status-stream.ts new file mode 100644 index 0000000..d15adbe --- /dev/null +++ b/packages/plugin/src/status-stream.ts @@ -0,0 +1,166 @@ +/** + * Browser-side status feed. One EventSource subscription replaces the fixed + * interval of unary `status` control calls, and degrades to that interval when + * the Host exposes no event stream — an older Host, or a carrier whose control + * channel serves POST only. + */ + +/** The EventSource members the feed drives. */ +export interface StatusStreamSource { + close(): void + onmessage: ((event: MessageEvent) => void) | null + onerror: ((event: Event) => void) | null + readonly readyState: number +} + +/** Why a status stream stopped pushing and fell back to unary status reads. */ +export type StatusStreamFallback = 'unsupported' | 'unavailable' | 'silent' + +/** Construction options for {@link createStatusFeed}. */ +export interface StatusStreamOptions { + /** Document-relative or absolute URL of the Host status event stream. */ + url: string + /** Unary status read used by the fallback path, and by no other path. */ + readStatus: () => Promise + /** EventSource factory; tests supply a scripted source. */ + createSource?: (url: string) => StatusStreamSource + pollIntervalMs?: number + openTimeoutMs?: number + /** Reports the one reason the stream yielded to the fallback. */ + onFallback?: (reason: StatusStreamFallback) => void +} + +/** One shared status source for every component that renders Host status. */ +export interface StatusFeed { + /** Latest pushed status; the same reference until the next frame arrives. */ + getSnapshot(): T | undefined + /** Listen to status frames; the first subscriber opens the stream, the last closes it. */ + subscribe(listener: (status: T) => void): () => void + /** Stop streaming and forget every listener, keeping the latest snapshot. */ + close(): void +} + +/** Fallback poll period: the interval the unary status polling used. */ +export const STATUS_STREAM_POLL_INTERVAL_MS = 1_500 + +/** How long a stream may deliver nothing before the fallback replaces it. */ +export const STATUS_STREAM_OPEN_TIMEOUT_MS = 4_000 + +/** EventSource readyState after a permanent failure, where the browser never retries. */ +const SOURCE_CLOSED = 2 + +/** Parse one SSE payload; a missing or non-object frame keeps the last status. */ +function parseStatus(data: unknown): T | undefined { + if (typeof data !== 'string') return undefined + try { + const parsed = JSON.parse(data) as T | null + return parsed === null || typeof parsed !== 'object' ? undefined : parsed + } catch { + return undefined + } +} + +/** + * Create the status feed. + * @param options - stream URL, fallback reader, and timing overrides. + * @returns feed with a stable snapshot accessor and a ref-counted subscription. + */ +export function createStatusFeed(options: StatusStreamOptions): StatusFeed { + const listeners = new Set<(status: T) => void>() + const pollIntervalMs = options.pollIntervalMs ?? STATUS_STREAM_POLL_INTERVAL_MS + const openTimeoutMs = options.openTimeoutMs ?? STATUS_STREAM_OPEN_TIMEOUT_MS + const createSource = options.createSource + ?? ((url: string): StatusStreamSource => new EventSource(url)) + let status: T | undefined + let source: StatusStreamSource | undefined + let openTimer: ReturnType | undefined + let pollTimer: ReturnType | undefined + + const publish = (next: T): void => { + status = next + for (const listener of [...listeners]) listener(next) + } + + const teardown = (): void => { + if (openTimer !== undefined) { + clearTimeout(openTimer) + openTimer = undefined + } + if (pollTimer !== undefined) { + clearInterval(pollTimer) + pollTimer = undefined + } + source?.close() + source = undefined + } + + const poll = (): void => { + void options.readStatus().then(next => { + // A read that lands after teardown must not resurrect the subscription. + if (pollTimer !== undefined) publish(next) + }).catch(() => undefined) + } + + const fallbackToPolling = (reason: StatusStreamFallback): void => { + if (pollTimer !== undefined || listeners.size === 0) return + if (openTimer !== undefined) { + clearTimeout(openTimer) + openTimer = undefined + } + source?.close() + source = undefined + options.onFallback?.(reason) + poll() + pollTimer = setInterval(poll, pollIntervalMs) + } + + const openStream = (): void => { + let opened: StatusStreamSource + try { + opened = createSource(options.url) + } catch { + // A carrier without EventSource support reports the same degradation as a + // Host without the stream route. + fallbackToPolling('unsupported') + return + } + source = opened + let received = false + openTimer = setTimeout(() => { + if (!received) fallbackToPolling('silent') + }, openTimeoutMs) + opened.onmessage = event => { + received = true + if (openTimer !== undefined) { + clearTimeout(openTimer) + openTimer = undefined + } + const next = parseStatus(event.data) + if (next !== undefined) publish(next) + } + opened.onerror = () => { + // A permanent failure (a non-2xx response or a non-event-stream content + // type) closes the source and never retries; a transient one stays + // CONNECTING, and the browser's own reconnect delivers the current status + // as the next first frame. + if (opened.readyState === SOURCE_CLOSED) fallbackToPolling('unavailable') + } + } + + return { + getSnapshot: () => status, + subscribe: listener => { + listeners.add(listener) + if (status !== undefined) listener(status) + if (listeners.size === 1) openStream() + return () => { + listeners.delete(listener) + if (listeners.size === 0) teardown() + } + }, + close: () => { + listeners.clear() + teardown() + }, + } +}