fix(realtime): end an unregistered event type as a registry mismatch with freshness UNKNOWN (04-03)

A type added by a newer backend ended the connection as MALFORMED_EVENT and
left the stream CURRENT. It is now PROTOCOL_MISMATCH/REGISTRY, and any decode
failure after the stream lookup marks that stream UNKNOWN (design 13.1).

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
DongHyeonka
2026-09-26 00:14:11 +09:00
co-authored by Claude Opus 5.5
parent 02d3fdf546
commit 7e37660ba6
6 changed files with 156 additions and 20 deletions
@@ -1850,6 +1850,13 @@ drop-only malformed 처리는 명시적으로 non-state-bearing heartbeat/contro
허용하며, threshold를 넘으면 protocol close한다. state-bearing event나 unknown
event type을 버리고 freshness를 `CURRENT`로 유지하지 않는다.
stream을 찾은 뒤 decode가 실패하면 consumer가 그 stream의 freshness를 `UNKNOWN`으로
바꾼다. 다음 event는 recovery부터 한다(`event-consumer.ts:89-90`,
`stream-coordinator.ts:998-1001`). registry에 없는 event type은 `MALFORMED_EVENT`가
아니라 `PROTOCOL_MISMATCH`(operation `REGISTRY`)로 닫는다(`event-codec.ts:172-175`).
event type 추가는 이전 bundle에는 호환 변경이 아니다. 조합 코드는 operation
`REGISTRY` 실패를 "구버전 client"로 보고 reload를 유도한다.
### 13.2 Effect certainty
| effect | certainty |
+28 -3
View File
@@ -17,6 +17,7 @@ import {
type RealtimeEventTypeRegistration,
type RealtimePolicyRegistry,
type RealtimeStreamRegistration,
type StreamRegistrationId,
} from "../../contracts/realtime-streams.ts";
import {
validateWithRuntimeSchemaRegistry,
@@ -68,21 +69,41 @@ const FORBIDDEN_OBJECT_KEYS = new Set([
]);
const encoder = new TextEncoder();
const issuedDtos = new WeakSet<object>();
const failedStreams = new WeakMap<object, StreamRegistrationId>();
type DecodeProgress = { stream?: StreamRegistrationId };
export function createRealtimeEventCodec(
dependencies: RealtimeEventCodecDependencies,
): RealtimeEventCodec {
return Object.freeze({
decode(raw: string): RealtimeResult<ValidatedRealtimeEventDto> {
const progress: DecodeProgress = {};
let result: RealtimeResult<ValidatedRealtimeEventDto>;
try {
return decodeUnsafe(raw, dependencies);
result = decodeUnsafe(raw, dependencies, progress);
} catch {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
result = realtimeFailure("MALFORMED_EVENT", "DECODE");
}
if (!result.ok && progress.stream) {
failedStreams.set(result, progress.stream);
}
return result;
},
});
}
/**
* The registered stream a failed decode had already identified, so that
* stream's freshness can become UNKNOWN (design 13.1). `null` when the
* failure came before the stream lookup.
*/
export function realtimeDecodeFailureStream(
failure: RealtimeResult<unknown>,
): StreamRegistrationId | null {
return failedStreams.get(failure) ?? null;
}
export function isValidatedRealtimeEventDto(
value: unknown,
): value is ValidatedRealtimeEventDto {
@@ -97,6 +118,7 @@ export function isValidatedRealtimeEventDto(
function decodeUnsafe(
raw: string,
dependencies: RealtimeEventCodecDependencies,
progress: DecodeProgress,
): RealtimeResult<ValidatedRealtimeEventDto> {
if (typeof raw !== "string") {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
@@ -136,6 +158,7 @@ function decodeUnsafe(
if (!stream) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
progress.stream = stream.id;
if (wireBytes > stream.limits.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
@@ -147,7 +170,9 @@ function decodeUnsafe(
input.eventType,
);
if (!eventType) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
// A type the backend added after this bundle was built: a client/server
// version mismatch (reload), not a corrupt event.
return realtimeFailure("PROTOCOL_MISMATCH", "REGISTRY");
}
if (!hasValidEnvelopeFields(input, stream)) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
+7 -3
View File
@@ -15,8 +15,9 @@ import {
import type {
StreamRegistrationId,
} from "../../contracts/realtime-streams.ts";
import type {
RealtimeEventCodec,
import {
realtimeDecodeFailureStream,
type RealtimeEventCodec,
} from "./event-codec.ts";
import type {
RealtimeStreamCoordinator,
@@ -63,7 +64,8 @@ export type RealtimeEventConsumer = Readonly<{
export function createRealtimeEventConsumer(
dependencies: Readonly<{
codec: RealtimeEventCodec;
coordinator: Pick<RealtimeStreamCoordinator, "accept">;
coordinator: Pick<RealtimeStreamCoordinator, "accept"> &
Partial<Pick<RealtimeStreamCoordinator, "invalidate">>;
}>,
): RealtimeEventConsumer {
async function consumeWithStream(
@@ -84,6 +86,8 @@ export function createRealtimeEventConsumer(
}
const decoded = dependencies.codec.decode(rawEnvelope);
if (!decoded.ok) {
const failedStream = realtimeDecodeFailureStream(decoded);
if (failedStream) dependencies.coordinator.invalidate?.(failedStream);
return { streamId: null, result: decoded };
}
const envelope = decoded.value.envelope;
@@ -93,6 +93,11 @@ export type RealtimeStreamCoordinator = Readonly<{
checkpoint: RealtimeRecoveryCheckpoint,
): RealtimeResult<void>;
getResumeState(streamId: StreamRegistrationId): RealtimeResumeState | null;
/**
* An event for this stream failed to decode (design 13.1): freshness
* becomes UNKNOWN, so the next admitted event recovers first.
*/
invalidate(streamId: StreamRegistrationId): void;
inspect(streamId: StreamRegistrationId): RealtimeStreamInspection;
lifecycle(streamId: StreamRegistrationId): RealtimeStreamLifecycle;
/**
@@ -990,6 +995,11 @@ export function createRealtimeStreamCoordinator(
});
}
function invalidate(streamId: StreamRegistrationId): void {
const state = states.get(streamId);
if (state) state.freshness = "UNKNOWN";
}
function lifecycleOf(streamId: StreamRegistrationId): RealtimeStreamLifecycle {
const state = states.get(streamId);
if (!state) return "CLOSED";
@@ -1139,6 +1149,7 @@ export function createRealtimeStreamCoordinator(
recover,
confirmTransportBarrier,
getResumeState,
invalidate,
inspect,
lifecycle: lifecycleOf,
close,
+19 -14
View File
@@ -10,8 +10,10 @@ import {
} from "../../../src/contracts/realtime-events.ts";
import {
isValidatedRealtimeEventDto,
realtimeDecodeFailureStream,
} from "../../../src/adapters/realtime/event-codec.ts";
import {
STREAM_ID,
TEST_LIMITS,
createTestRealtimeCodec,
createTestRealtimeRegistry,
@@ -59,28 +61,31 @@ describe("REALTIME_EVENT_V1 codec", () => {
ok: false,
error: { kind: "MALFORMED_EVENT", operation: "DECODE" },
});
expect(
codec.decode(
realtimeEventJson({ streamId: "UNKNOWN_STREAM" }),
),
).toMatchObject({
const unknownStream = codec.decode(
realtimeEventJson({ streamId: "UNKNOWN_STREAM" }),
);
expect(unknownStream).toMatchObject({
ok: false,
error: { kind: "MALFORMED_EVENT" },
});
expect(
codec.decode(
realtimeEventJson({ eventType: "UNKNOWN_EVENT" }),
),
).toMatchObject({
expect(realtimeDecodeFailureStream(unknownStream)).toBeNull();
// A type added by a newer backend is a version mismatch, not corruption.
const unknownType = codec.decode(
realtimeEventJson({ eventType: "UNKNOWN_EVENT" }),
);
expect(unknownType).toMatchObject({
ok: false,
error: { kind: "MALFORMED_EVENT" },
error: { kind: "PROTOCOL_MISMATCH", operation: "REGISTRY" },
});
expect(
codec.decode(realtimeEventJson({ payload: { value: 42 } })),
).toMatchObject({
expect(realtimeDecodeFailureStream(unknownType)).toBe(STREAM_ID);
const badPayload = codec.decode(
realtimeEventJson({ payload: { value: 42 } }),
);
expect(badPayload).toMatchObject({
ok: false,
error: { kind: "MALFORMED_EVENT" },
});
expect(realtimeDecodeFailureStream(badPayload)).toBe(STREAM_ID);
const duplicateEnvelopeMember =
`{"eventId":"shadowed",${JSON.stringify(
@@ -314,4 +314,88 @@ describe("SSE transport, consumer and stream coordinator together", () => {
false,
);
});
it("ends on an unregistered event type as a registry mismatch and leaves freshness UNKNOWN", async () => {
const registry = createTestRealtimeRegistry({
recovery: {
mode: "SNAPSHOT_ONLY",
snapshotOperationId: "GET_REFERENCE_REALTIME_SNAPSHOT",
checkpointCodecId: "ReferenceRealtimeCheckpoint",
barrier: "NONE",
},
delivery: "INVALIDATION_HINT",
stateBearing: false,
});
const apply = vi.fn(async () => realtimeSuccess(undefined));
const coordinator = createRealtimeStreamCoordinator({
registry,
mappers: TEST_MAPPERS,
authority: {
effects: { apply },
recovery: {
recover: async () =>
realtimeSuccess({
kind: "SNAPSHOT_RESET",
checkpoint: {
recoveryMode: "SNAPSHOT_ONLY",
streamEpoch: "stream-epoch-0001",
lastAppliedSequence: "0",
resumeCursor: null,
snapshotRevision: "snapshot-revision-0",
},
}),
},
},
scope: {
generation: 7,
scopeBinding: "scope-binding-0001",
isCurrent: () => true,
},
now: () => 10_000,
});
const consumer = createRealtimeEventConsumer({
codec: createTestRealtimeCodec(registry),
coordinator,
});
await expect(
coordinator.recover(STREAM_ID, "INITIALIZE"),
).resolves.toMatchObject({ ok: true });
// A newer backend added an event type this bundle does not know.
const frame = (sequence: string, eventType?: string) =>
`data: ${realtimeEventJson({
eventId: `event-0000000${sequence}`,
sequence,
recoveryMode: "SNAPSHOT_ONLY",
resumeCursor: null,
...(eventType === undefined ? {} : { eventType }),
})}\n\n`;
const body = frame("1") + frame("2", "ADDED_BY_NEWER_BACKEND");
const connection = createFetchSseConnection({
endpoint: "https://app.example.test/events",
applicationOrigin: "https://app.example.test",
recoveryMode: "SNAPSHOT_ONLY",
fetcher: async () =>
new Response(body, {
status: 200,
headers: { "Content-Type": "text/event-stream" },
}),
});
const closed = await connection.read({
resumeCursor: null,
onEvent: (event, signal) =>
consumer.consumeForTransport(
event.data,
{ kind: "SSE_NO_CURSOR" },
signal,
),
});
expect(apply).toHaveBeenCalledOnce();
expect(closed).toEqual(
realtimeFailure("PROTOCOL_MISMATCH", "REGISTRY", false),
);
expect(coordinator.inspect(STREAM_ID).freshness).toBe("UNKNOWN");
});
});