Import packages/plugin/src/status-stream.ts
This commit is contained in:
parent
d712a47010
commit
d4c61a5eb7
|
|
@ -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<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()
|
||||
},
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue