167 lines
5.6 KiB
TypeScript
167 lines
5.6 KiB
TypeScript
/**
|
|
* 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<T> {
|
|
/** 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<T>
|
|
/** 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<T> {
|
|
/** 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<T>(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<T>(options: StatusStreamOptions<T>): StatusFeed<T> {
|
|
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<typeof setTimeout> | undefined
|
|
let pollTimer: ReturnType<typeof setInterval> | 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<T>(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()
|
|
},
|
|
}
|
|
}
|