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:
co-authored by
Claude Opus 5.5
parent
02d3fdf546
commit
7e37660ba6
@@ -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 |
|
||||
|
||||
@@ -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");
|
||||
|
||||
@@ -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,
|
||||
|
||||
@@ -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");
|
||||
});
|
||||
});
|
||||
|
||||
Reference in New Issue
Block a user