import { EngineError, EngineErrorCode, type DocumentEventOf, type EditSessionStatus, } from '@embedpdf/engine-core/runtime'; import { EditSessionStatusSchema } from '@embedpdf/engine-core/wire'; import type { AuditEventRow } from './auditRowToEvents'; import type { HttpClient } from '../transport/HttpClient'; /** Why the stream can't be followed change by change (`stream.desynced`). */ export type DesyncReason = DocumentEventOf<'stream.desynced'>['reason']; export interface SseClientOptions { http: HttpClient; path: string; /** Resume cursor for the first connect (manifest `auditHead` / * `lastServerSequence`); `null` subscribes "from now". */ initialCursor: number | null; /** One parsed audit row, in id order. The cursor has already advanced. */ onRow(row: AuditEventRow): void; /** * The server sent `full-refresh` in place of rows: the gap is too large to * replay, or a row holds a kind of change this client's version doesn't * have. Refetch state. */ onFullRefresh(reason: DesyncReason): void; /** Auth is permanently gone (401/403); the client stopped for good. */ onAuthLost(): void; /** The editing session's `session` event: every object number it holds, and its expiry. */ onSession?(status: EditSessionStatus): void; /** The stream is up (`true`) or down (`false`). */ onConnected?(connected: boolean): void; } /** * Fetch-based SSE consumer. Browser-native `EventSource` cannot send an * `Authorization` header, so the stream rides the same `HttpClient` as * every other request (same token provider, same session header). * * Resilience model: the cursor is the only state that matters. Every * (re)connect sends `Last-Event-ID: cursor`; the server replays the gap * from the audit log. So a dropped stream costs latency, never events — * the client needs no buffering and no acknowledgements. * * - network drop / server close / `auth-expiring` → reconnect with * jittered exponential backoff (500ms → 30s; reset after a stream * that lived ≥30s). `auth-expiring` reconnects pick up a fresh token * from the HttpClient's provider automatically. * - 401/403 → permanent: `onAuthLost`, no retry loop against a dead * credential. */ export class SseClient { private cursor: number | null; private closed = false; private abort: AbortController | null = null; private retryTimer: ReturnType | null = null; private retryDelayMs = 500; constructor(private readonly options: SseClientOptions) { this.cursor = options.initialCursor; } open(): void { if (this.closed) return; void this.run(); } close(): void { this.closed = true; if (this.retryTimer) clearTimeout(this.retryTimer); this.abort?.abort(); } get lastEventId(): number | null { return this.cursor; } private async run(): Promise { const startedAt = Date.now(); this.abort = new AbortController(); try { const res = await this.options.http.stream( this.options.path, this.cursor !== null ? { 'Last-Event-ID': String(this.cursor) } : {}, this.abort.signal, ); if (res.status === 401 || res.status === 403) { this.closed = true; this.options.onAuthLost(); return; } if (!res.ok || !res.body) { throw new EngineError(EngineErrorCode.Network, `events stream HTTP ${res.status}`); } this.options.onConnected?.(true); try { await this.consume(res.body); } finally { this.options.onConnected?.(false); } // Stream ended (server close / auth-expiring / network): reconnect. if (Date.now() - startedAt >= 30_000) this.retryDelayMs = 500; } catch { // Aborts land here too; `closed` guards the reschedule below. } if (this.closed) return; const jitter = this.retryDelayMs * (0.5 + Math.random() * 0.5); this.retryTimer = setTimeout(() => void this.run(), jitter); this.retryDelayMs = Math.min(this.retryDelayMs * 2, 30_000); } private async consume(body: ReadableStream): Promise { const reader = body.getReader(); const decoder = new TextDecoder(); let buffer = ''; for (;;) { const { done, value } = await reader.read(); if (done || this.closed) return; buffer += decoder.decode(value, { stream: true }); for (;;) { const sep = buffer.indexOf('\n\n'); if (sep < 0) break; const block = buffer.slice(0, sep); buffer = buffer.slice(sep + 2); this.dispatch(block); } } } private dispatch(block: string): void { if (block.startsWith(':')) return; // heartbeat / comment let id: number | null = null; let event = 'message'; const data: string[] = []; for (const line of block.split('\n')) { if (line.startsWith('id:')) id = Number(line.slice(3).trim()); else if (line.startsWith('event:')) event = line.slice(6).trim(); else if (line.startsWith('data:')) data.push(line.slice(5).trim()); } if (id !== null && Number.isFinite(id)) this.cursor = id; if (event === 'mutation') { try { this.options.onRow(JSON.parse(data.join('\n')) as AuditEventRow); } catch { // A malformed row advances the cursor and is skipped; the audit log // remains the source of truth for anyone who refetches. } } else if (event === 'session') { const parsed = safeJson(data.join('\n')); const status = EditSessionStatusSchema.safeParse(parsed); if (status.success) this.options.onSession?.(status.data); } else if (event === 'full-refresh') { // A server older than the reason sends none: it only refreshes a client too far behind. const sent = (safeJson(data.join('\n')) as { reason?: unknown } | null)?.reason; this.options.onFullRefresh(sent === 'unknown-change' ? sent : 'backlog-overflow'); } else if (event === 'auth-revoked') { // Terminal: the credential is dead by decree, not by clock — never // retry against it (a reconnect would just 401; this saves the trip // and surfaces the loss immediately). this.closed = true; this.abort?.abort(); this.options.onAuthLost(); } // 'auth-expiring' needs no handling: the server ends the stream right // after, and the reconnect path fetches a fresh token. } } function safeJson(text: string): unknown { try { return JSON.parse(text); } catch { return null; } }