diff --git a/docs/architecture/realtime-events-web-push-and-bounded-polling.md b/docs/architecture/realtime-events-web-push-and-bounded-polling.md index fc581c94..6a8ad5f1 100644 --- a/docs/architecture/realtime-events-web-push-and-bounded-polling.md +++ b/docs/architecture/realtime-events-web-push-and-bounded-polling.md @@ -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 | diff --git a/src/adapters/realtime/event-codec.ts b/src/adapters/realtime/event-codec.ts index 15b1042f..60f6f29e 100644 --- a/src/adapters/realtime/event-codec.ts +++ b/src/adapters/realtime/event-codec.ts @@ -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(); +const failedStreams = new WeakMap(); + +type DecodeProgress = { stream?: StreamRegistrationId }; export function createRealtimeEventCodec( dependencies: RealtimeEventCodecDependencies, ): RealtimeEventCodec { return Object.freeze({ decode(raw: string): RealtimeResult { + const progress: DecodeProgress = {}; + let result: RealtimeResult; 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, +): 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 { 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"); diff --git a/src/adapters/realtime/event-consumer.ts b/src/adapters/realtime/event-consumer.ts index 30976f1f..2626055e 100644 --- a/src/adapters/realtime/event-consumer.ts +++ b/src/adapters/realtime/event-consumer.ts @@ -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; + coordinator: Pick & + Partial>; }>, ): 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; diff --git a/src/adapters/realtime/stream-coordinator.ts b/src/adapters/realtime/stream-coordinator.ts index ba7abe23..3653b734 100644 --- a/src/adapters/realtime/stream-coordinator.ts +++ b/src/adapters/realtime/stream-coordinator.ts @@ -93,6 +93,11 @@ export type RealtimeStreamCoordinator = Readonly<{ checkpoint: RealtimeRecoveryCheckpoint, ): RealtimeResult; 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, diff --git a/tests/unit/realtime/event-codec.test.ts b/tests/unit/realtime/event-codec.test.ts index d1c7fdd1..c8ab3fe1 100644 --- a/tests/unit/realtime/event-codec.test.ts +++ b/tests/unit/realtime/event-codec.test.ts @@ -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( diff --git a/tests/unit/realtime/event-consumer.test.ts b/tests/unit/realtime/event-consumer.test.ts index 9d5ac5e1..19b5b857 100644 --- a/tests/unit/realtime/event-consumer.test.ts +++ b/tests/unit/realtime/event-consumer.test.ts @@ -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"); + }); });