fix(realtime): hand SSE items past the per-chunk cap to drain() (Q-6.4-5)

A single reader chunk with more than maxItemsPerChunk (256) items used to
fail the stream with non-retryable QUEUE_OVERFLOW, killing normal replay
bursts even though maxChunkBytes already bounds memory. The parser now
stops at the cap, keeps the remaining decoded text, and returns it through
a new additive drain() call; fetch-sse-connection drains after every push
before reading again. Pushing or finishing with undrained text still fails
closed (QUEUE_OVERFLOW), so buffered text stays bounded by one chunk. A
lone CR followed by another line now re-checks the cap before continuing.
COMMENT and empty item lists reuse frozen constants.

The old parser test that expected QUEUE_OVERFLOW for 3 comments with a
cap of 2 encoded the bug and is replaced.

RED: new parser drain test and a 300-event single-chunk connection test
failed with QUEUE_OVERFLOW before the change. Gates: check:architecture,
check:types:app/test, lint, check:adapter-inventory, test:unit,
test:component all pass.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-24 13:54:29 +09:00
co-authored by Claude Opus 5.5
parent a8c5eabcd9
commit cc906f08b4
4 changed files with 127 additions and 58 deletions
@@ -434,13 +434,20 @@ export function createFetchSseConnection(
await cancelReader(reader, clock, controller);
return failed("MALFORMED_EVENT", "DECODE", false);
}
const parsed = parser.push(readResult.value.value);
if (!parsed.ok) {
await cancelReader(reader, clock, controller);
return parsed;
// Items past the parser's per-call cap arrive through drain().
for (
let parsed = parser.push(readResult.value.value);
;
parsed = parser.drain()
) {
if (!parsed.ok) {
await cancelReader(reader, clock, controller);
return parsed;
}
if (parsed.value.length === 0) break;
const dispatchFailure = await handleParserItems(parsed.value);
if (dispatchFailure) return dispatchFailure;
}
const dispatchFailure = await handleParserItems(parsed.value);
if (dispatchFailure) return dispatchFailure;
}
} catch {
return failed(
+45 -40
View File
@@ -14,6 +14,10 @@ export const SSE_PARSER_CEILINGS = Object.freeze({
});
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;
@@ -47,7 +51,13 @@ export type SseParserFinish = Readonly<{
}>;
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<readonly SseParserItem[]>;
drain(): RealtimeResult<readonly SseParserItem[]>;
finish(): RealtimeResult<SseParserFinish>;
}>;
@@ -66,6 +76,7 @@ export function createIncrementalSseParser(
let pendingCarriageReturn = false;
let line = "";
let lineBytes = 0;
let undrained = "";
let blockBytes = 0;
let dataLines: string[] = [];
let eventType = "";
@@ -84,6 +95,7 @@ export function createIncrementalSseParser(
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 });
@@ -93,10 +105,20 @@ export function createIncrementalSseParser(
return consumeText(text);
}
function drain(): RealtimeResult<readonly SseParserItem[]> {
if (state !== "OPEN") {
return realtimeFailure("CLOSED", "DECODE");
}
const text = undrained;
undrained = "";
return consumeText(text);
}
function finish(): RealtimeResult<SseParserFinish> {
if (state !== "OPEN") {
return realtimeFailure("CLOSED", "DECODE");
}
if (undrained.length > 0) return fail("QUEUE_OVERFLOW");
let tail: string;
try {
tail = decoder.decode();
@@ -110,9 +132,13 @@ export function createIncrementalSseParser(
pendingCarriageReturn = false;
const processed = processLine(1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
items.push(...processed.value);
}
if (
undrained.length > 0 ||
items.length > resolved.maxItemsPerChunk
) {
return fail("QUEUE_OVERFLOW");
}
const incompleteEventDiscarded =
lineBytes > 0 ||
@@ -136,7 +162,7 @@ export function createIncrementalSseParser(
* 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.
* would. Stops at `maxItemsPerChunk` items and keeps the rest for `drain()`.
*/
function consumeText(
text: string,
@@ -149,18 +175,18 @@ export function createIncrementalSseParser(
}
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;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
if (lineFeed) {
index += 1;
continue;
}
items.push(...processed.value);
if (lineFeed) index += 1;
continue;
}
LINE_BREAK.lastIndex = index;
@@ -185,9 +211,7 @@ export function createIncrementalSseParser(
}
const processed = processLine(1);
if (!processed.ok) return processed;
if (!appendItems(items, processed.value)) {
return fail("QUEUE_OVERFLOW");
}
items.push(...processed.value);
}
return success(Object.freeze(items));
}
@@ -217,13 +241,7 @@ export function createIncrementalSseParser(
return success(Object.freeze(items));
}
if (currentLine.startsWith(":")) {
return success(
Object.freeze([
Object.freeze({ kind: "COMMENT" as const }),
]),
);
}
if (currentLine.startsWith(":")) return success(COMMENT_ITEMS);
blockBytes += currentLineBytes + terminatorBytes;
if (blockBytes > resolved.maxEventBytes) {
@@ -244,18 +262,18 @@ export function createIncrementalSseParser(
if (field === "data") {
dataLines.push(value);
return success(Object.freeze([]));
return success(NO_ITEMS);
}
if (field === "event") {
eventType = value;
return success(Object.freeze([]));
return success(NO_ITEMS);
}
if (field === "id") {
if (!value.includes("\0")) {
lastEventId = value;
hasExplicitId = true;
}
return success(Object.freeze([]));
return success(NO_ITEMS);
}
if (field === "retry" && /^\d+$/u.test(value)) {
const retryMs = Number(value);
@@ -270,7 +288,7 @@ export function createIncrementalSseParser(
);
}
}
return success(Object.freeze([]));
return success(NO_ITEMS);
}
function clearBlock(): void {
@@ -289,25 +307,12 @@ export function createIncrementalSseParser(
state = "FAILED";
line = "";
lineBytes = 0;
undrained = "";
clearBlock();
return realtimeFailure(kind, "DECODE");
}
function appendItems(
target: SseParserItem[],
additions: readonly SseParserItem[],
): boolean {
if (
target.length + additions.length >
resolved.maxItemsPerChunk
) {
return false;
}
target.push(...additions);
return true;
}
return Object.freeze({ push, finish });
return Object.freeze({ push, drain, finish });
}
function resolveLimits(