// The round-2 SSE parser (decode each chunk, then re-encode every segment to // count its bytes), kept only as the oracle for the differential test. import type { RealtimeResult } from "../../../src/application/ports/realtime/shared.ts"; import { realtimeFailure, realtimeSuccess, } from "../../../src/adapters/realtime/result.ts"; export const SSE_PARSER_CEILINGS = Object.freeze({ maxLineBytes: 64 * 1_024, maxEventBytes: 64 * 1_024, maxIncompleteBufferBytes: 128 * 1_024, maxChunkBytes: 256 * 1_024, maxItemsPerChunk: 256, maxRetryMs: 60_000, }); const LINE_BREAK = /[\r\n]/gu; const NO_ITEMS: readonly SseParserItem[] = Object.freeze([]); const COMMENT_ITEMS: readonly SseParserItem[] = Object.freeze([ Object.freeze({ kind: "COMMENT" as const }), ]); export type SseParserLimits = Readonly<{ maxLineBytes: number; maxEventBytes: number; maxIncompleteBufferBytes: number; maxChunkBytes: number; maxItemsPerChunk: number; maxRetryMs: number; }>; export type ParsedSseEvent = Readonly<{ kind: "EVENT"; eventType: string; data: string; /** * Standard SSE last-event-ID state. Consumers that require cursor-after- * effect must additionally require `hasExplicitId` and commit independently. */ id: string | null; hasExplicitId: boolean; }>; export type SseParserItem = | ParsedSseEvent | Readonly<{ kind: "COMMENT" }> | Readonly<{ kind: "RETRY"; retryMs: number }>; export type SseParserFinish = Readonly<{ items: readonly SseParserItem[]; incompleteEventDiscarded: boolean; }>; export type IncrementalSseParser = Readonly<{ /** * Returns at most `maxItemsPerChunk` items. Text past that cap is kept and * must be taken with `drain()` until it returns no items; pushing or * finishing before then fails with QUEUE_OVERFLOW. */ push(chunk: Uint8Array): RealtimeResult; drain(): RealtimeResult; finish(): RealtimeResult; }>; export function createIncrementalSseParser( limits: Partial = {}, ): IncrementalSseParser { const resolved = resolveLimits(limits); // ignoreBOM: false makes the decoder strip the one leading BOM the // stream grammar allows; a second one is ordinary text. const decoder = new TextDecoder("utf-8", { fatal: true, ignoreBOM: false, }); const encoder = new TextEncoder(); let state: "OPEN" | "FAILED" | "FINISHED" = "OPEN"; let pendingCarriageReturn = false; let line = ""; let lineBytes = 0; let undrained = ""; let blockBytes = 0; let dataLines: string[] = []; let eventType = ""; let lastEventId: string | null = null; let hasExplicitId = false; function push( chunk: Uint8Array, ): RealtimeResult { if (state !== "OPEN") { return realtimeFailure("CLOSED", "DECODE"); } if (!(chunk instanceof Uint8Array)) { return fail("MALFORMED_EVENT"); } if (chunk.byteLength > resolved.maxChunkBytes) { return fail("EVENT_TOO_LARGE"); } if (undrained.length > 0) return fail("QUEUE_OVERFLOW"); let text: string; try { text = decoder.decode(chunk, { stream: true }); } catch { return fail("MALFORMED_EVENT"); } return consumeText(text); } function drain(): RealtimeResult { if (state !== "OPEN") { return realtimeFailure("CLOSED", "DECODE"); } const text = undrained; undrained = ""; return consumeText(text); } function finish(): RealtimeResult { if (state !== "OPEN") { return realtimeFailure("CLOSED", "DECODE"); } if (undrained.length > 0) return fail("QUEUE_OVERFLOW"); let tail: string; try { tail = decoder.decode(); } catch { return fail("MALFORMED_EVENT"); } const consumed = consumeText(tail); if (!consumed.ok) return consumed; const items = [...consumed.value]; if (pendingCarriageReturn) { pendingCarriageReturn = false; const processed = processLine(1); if (!processed.ok) return processed; items.push(...processed.value); } if ( undrained.length > 0 || items.length > resolved.maxItemsPerChunk ) { return fail("QUEUE_OVERFLOW"); } const incompleteEventDiscarded = lineBytes > 0 || blockBytes > 0 || dataLines.length > 0 || eventType.length > 0 || hasExplicitId; clearBlock(); line = ""; lineBytes = 0; state = "FINISHED"; return success( Object.freeze({ items: Object.freeze(items), incompleteEventDiscarded, }), ); } /** * Works a line at a time: find the next CR/LF, append the text before it * and count its UTF-8 bytes once. Byte counts only grow within a line, so * checking the limits per segment fails exactly where a per-character check * would. Stops at `maxItemsPerChunk` items and keeps the rest for `drain()`. */ function consumeText( text: string, ): RealtimeResult { const items: SseParserItem[] = []; let index = 0; while (index < text.length) { if (items.length >= resolved.maxItemsPerChunk) { undrained = text.slice(index); break; } if (pendingCarriageReturn) { pendingCarriageReturn = false; const lineFeed = text.charCodeAt(index) === 0x0a; const processed = processLine(lineFeed ? 2 : 1); if (!processed.ok) return processed; items.push(...processed.value); if (lineFeed) index += 1; continue; } LINE_BREAK.lastIndex = index; const lineBreak = LINE_BREAK.exec(text)?.index ?? text.length; if (lineBreak > index) { const segment = text.slice(index, lineBreak); line += segment; lineBytes += encoder.encode(segment).byteLength; if ( lineBytes > resolved.maxLineBytes || lineBytes + blockBytes > resolved.maxIncompleteBufferBytes ) { return fail("EVENT_TOO_LARGE"); } } if (lineBreak === text.length) break; index = lineBreak + 1; if (text.charCodeAt(lineBreak) === 0x0d) { pendingCarriageReturn = true; continue; } const processed = processLine(1); if (!processed.ok) return processed; items.push(...processed.value); } return success(Object.freeze(items)); } function processLine( terminatorBytes: number, ): RealtimeResult { const currentLine = line; const currentLineBytes = lineBytes; line = ""; lineBytes = 0; if (currentLine.length === 0) { const items: SseParserItem[] = []; if (dataLines.length > 0) { items.push( Object.freeze({ kind: "EVENT", eventType: eventType.length > 0 ? eventType : "message", data: dataLines.join("\n"), id: lastEventId, hasExplicitId, }), ); } clearBlock(); return success(Object.freeze(items)); } if (currentLine.startsWith(":")) return success(COMMENT_ITEMS); blockBytes += currentLineBytes + terminatorBytes; if (blockBytes > resolved.maxEventBytes) { return fail("EVENT_TOO_LARGE"); } if (blockBytes > resolved.maxIncompleteBufferBytes) { return fail("EVENT_TOO_LARGE"); } const separator = currentLine.indexOf(":"); const field = separator === -1 ? currentLine : currentLine.slice(0, separator); let value = separator === -1 ? "" : currentLine.slice(separator + 1); if (value.startsWith(" ")) value = value.slice(1); if (field === "data") { dataLines.push(value); return success(NO_ITEMS); } if (field === "event") { eventType = value; return success(NO_ITEMS); } if (field === "id") { if (!value.includes("\0")) { lastEventId = value; hasExplicitId = true; } return success(NO_ITEMS); } if (field === "retry" && /^\d+$/u.test(value)) { const retryMs = Number(value); if ( Number.isSafeInteger(retryMs) && retryMs <= resolved.maxRetryMs ) { return success( Object.freeze([ Object.freeze({ kind: "RETRY" as const, retryMs }), ]), ); } } return success(NO_ITEMS); } function clearBlock(): void { blockBytes = 0; dataLines = []; eventType = ""; hasExplicitId = false; } function fail( kind: | "EVENT_TOO_LARGE" | "MALFORMED_EVENT" | "QUEUE_OVERFLOW", ): RealtimeResult { state = "FAILED"; line = ""; lineBytes = 0; undrained = ""; clearBlock(); return realtimeFailure(kind, "DECODE"); } return Object.freeze({ push, drain, finish }); } function resolveLimits( input: Partial, ): SseParserLimits { const limits = { maxLineBytes: input.maxLineBytes ?? SSE_PARSER_CEILINGS.maxLineBytes, maxEventBytes: input.maxEventBytes ?? SSE_PARSER_CEILINGS.maxEventBytes, maxIncompleteBufferBytes: input.maxIncompleteBufferBytes ?? SSE_PARSER_CEILINGS.maxIncompleteBufferBytes, maxChunkBytes: input.maxChunkBytes ?? SSE_PARSER_CEILINGS.maxChunkBytes, maxItemsPerChunk: input.maxItemsPerChunk ?? SSE_PARSER_CEILINGS.maxItemsPerChunk, maxRetryMs: input.maxRetryMs ?? SSE_PARSER_CEILINGS.maxRetryMs, }; if ( !positiveInteger(limits.maxLineBytes) || limits.maxLineBytes > SSE_PARSER_CEILINGS.maxLineBytes || !positiveInteger(limits.maxEventBytes) || limits.maxEventBytes > SSE_PARSER_CEILINGS.maxEventBytes || !positiveInteger(limits.maxIncompleteBufferBytes) || limits.maxIncompleteBufferBytes > SSE_PARSER_CEILINGS.maxIncompleteBufferBytes || limits.maxIncompleteBufferBytes < limits.maxEventBytes || !positiveInteger(limits.maxChunkBytes) || limits.maxChunkBytes > SSE_PARSER_CEILINGS.maxChunkBytes || limits.maxChunkBytes < limits.maxEventBytes || !positiveInteger(limits.maxItemsPerChunk) || limits.maxItemsPerChunk > SSE_PARSER_CEILINGS.maxItemsPerChunk || !positiveInteger(limits.maxRetryMs) || limits.maxRetryMs > SSE_PARSER_CEILINGS.maxRetryMs ) { throw new TypeError("Invalid SSE parser limits."); } return Object.freeze(limits); } function success(value: Value): RealtimeResult { return realtimeSuccess(value); } function positiveInteger(value: number): boolean { return Number.isSafeInteger(value) && value > 0; }