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(
@@ -526,6 +526,29 @@ describe("fetch SSE connection", () => {
);
});
it("dispatches a single chunk holding more events than the per-chunk item cap", async () => {
const chunk = Array.from(
{ length: 300 },
(_, index) =>
`id: cursor-${index}\ndata: ${"x".repeat(300)}\n\n`,
).join("");
const runtime = connection(
(async () => eventStream([chunk])) as typeof fetch,
);
const received: string[] = [];
await expect(
runtime.read({
resumeCursor: null,
onEvent: (event) => {
received.push(event.id ?? "");
return realtimeSuccess(SSE_CONTINUE);
},
}),
).resolves.toMatchObject({ ok: true, value: { kind: "EOF" } });
expect(received).toHaveLength(300);
expect(received[299]).toBe("cursor-299");
});
it("rejects arbitrary endpoints and mode-incoherent cursors before fetch", async () => {
expect(() =>
createFetchSseConnection({
+46 -12
View File
@@ -159,18 +159,6 @@ describe("incremental SSE parser", () => {
},
});
const excessiveBatch = createIncrementalSseParser({
maxItemsPerChunk: 2,
});
expect(excessiveBatch.push(encoder.encode(":\n:\n:\n"))).toEqual({
ok: false,
error: {
kind: "QUEUE_OVERFLOW",
operation: "DECODE",
retryable: false,
},
});
const oversizedChunk = createIncrementalSseParser({
maxChunkBytes: 65_536,
});
@@ -186,6 +174,52 @@ describe("incremental SSE parser", () => {
});
});
it("hands items past the per-chunk cap to drain() instead of failing", () => {
const parser = createIncrementalSseParser({ maxItemsPerChunk: 1 });
const comment = { kind: "COMMENT" };
expect(pushText(parser, ":\r:\r\n:\ndata: a\r")).toEqual([comment]);
// The retained text resumes between CR and LF.
expect(parser.drain()).toEqual({ ok: true, value: [comment] });
expect(parser.drain()).toEqual({ ok: true, value: [comment] });
expect(parser.drain()).toEqual({ ok: true, value: [] });
expect(parser.drain()).toEqual({ ok: true, value: [] });
expect(pushText(parser, "\n\n")).toEqual([
{
kind: "EVENT",
eventType: "message",
data: "a",
id: null,
hasExplicitId: false,
},
]);
// A lone CR followed by another complete line still honours the cap.
const loneCarriageReturn = createIncrementalSseParser({
maxItemsPerChunk: 1,
});
expect(pushText(loneCarriageReturn, ":\r:\n")).toEqual([comment]);
expect(loneCarriageReturn.drain()).toEqual({
ok: true,
value: [comment],
});
// Undrained items are a caller bug: fail closed instead of buffering.
const undrained = createIncrementalSseParser({ maxItemsPerChunk: 1 });
expect(pushText(undrained, ":\n:\n")).toEqual([comment]);
const overflow = {
ok: false,
error: {
kind: "QUEUE_OVERFLOW",
operation: "DECODE",
retryable: false,
},
};
expect(undrained.push(encoder.encode(":\n"))).toEqual(overflow);
const unfinished = createIncrementalSseParser({ maxItemsPerChunk: 1 });
expect(pushText(unfinished, ":\n:\n")).toEqual([comment]);
expect(unfinished.finish()).toEqual(overflow);
});
it("parses the same items whether bytes arrive at once or one by one", () => {
const stream = encoder.encode(
"event: a\r\ndata: 한글\rdata: 😀 é\r\n\r\n" +