Files
clean-architecture-frontend…/src/adapters/realtime/event-codec.ts
T
DongHyeonkaandClaude Opus 5.5 7e37660ba6 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>
2026-09-26 00:14:11 +09:00

439 lines
12 KiB
TypeScript

import {
realtimeFailure,
realtimeSuccess,
type RealtimeResult,
} from "./result.ts";
import {
isCanonicalRealtimeSequence,
isRealtimeOpaqueIdentifier,
isRealtimeResumeCursor,
isRealtimeScopeBinding,
isStrictRealtimeTimestamp,
type RealtimeEventEnvelope,
} from "../../contracts/realtime-events.ts";
import {
REALTIME_EVENT_PROTOCOL,
REALTIME_HARD_LIMITS,
type RealtimeEventTypeRegistration,
type RealtimePolicyRegistry,
type RealtimeStreamRegistration,
type StreamRegistrationId,
} from "../../contracts/realtime-streams.ts";
import {
validateWithRuntimeSchemaRegistry,
type RuntimeSchemaCodec,
} from "../../contracts/schema-registry.ts";
import {
hasDuplicateJsonMembers,
} from "../platform/json-member-scanner.ts";
export type ValidatedRealtimeEventDto = Readonly<{
envelope: RealtimeEventEnvelope;
wireBytes: number;
/**
* Adapter-private semantic identity used only by the bounded conflict
* detector: a fixed-size hash of the canonical envelope, so dedupe memory
* does not grow with payload size. It must never be logged or projected
* into diagnostics.
*/
semanticFingerprint: string;
fingerprintBytes: number;
}>;
export type RealtimeEventCodec = Readonly<{
decode(raw: string): RealtimeResult<ValidatedRealtimeEventDto>;
}>;
export type RealtimeEventCodecDependencies = Readonly<{
registry: RealtimePolicyRegistry;
schemaCodecs: Readonly<Record<string, RuntimeSchemaCodec>>;
}>;
const ENVELOPE_KEYS = Object.freeze([
"eventId",
"eventType",
"occurredAt",
"payload",
"protocol",
"recoveryMode",
"resumeCursor",
"scopeBinding",
"sequence",
"streamEpoch",
"streamId",
] as const);
const FORBIDDEN_OBJECT_KEYS = new Set([
"__proto__",
"constructor",
"prototype",
]);
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 {
result = decodeUnsafe(raw, dependencies, progress);
} catch {
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 {
return (
!!value &&
typeof value === "object" &&
issuedDtos.has(value) &&
Object.isFrozen(value)
);
}
function decodeUnsafe(
raw: string,
dependencies: RealtimeEventCodecDependencies,
progress: DecodeProgress,
): RealtimeResult<ValidatedRealtimeEventDto> {
if (typeof raw !== "string") {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
if (raw.length > REALTIME_HARD_LIMITS.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
const wireBytes = encoder.encode(raw).byteLength;
if (wireBytes > REALTIME_HARD_LIMITS.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
let input: unknown;
if (
hasDuplicateJsonMembers(raw, {
maxDepth: REALTIME_HARD_LIMITS.maxPayloadDepth + 2,
maxMembers: REALTIME_HARD_LIMITS.maxPayloadNodes + 32,
})
) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
try {
input = JSON.parse(raw);
} catch {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
if (!hasExactEnvelopeKeys(input)) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
if (input.protocol !== REALTIME_EVENT_PROTOCOL) {
return realtimeFailure("PROTOCOL_MISMATCH", "DECODE");
}
if (typeof input.streamId !== "string") {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
const stream = dependencies.registry.findStream(input.streamId);
if (!stream) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
progress.stream = stream.id;
if (wireBytes > stream.limits.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
if (typeof input.eventType !== "string") {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
const eventType = dependencies.registry.findStreamEventType(
stream.id,
input.eventType,
);
if (!eventType) {
// 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");
}
if (
!withinJsonBudget(
input.payload,
stream.limits.maxPayloadDepth,
stream.limits.maxPayloadNodes,
)
) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
const payload = validateWithRuntimeSchemaRegistry(
eventType.payloadSchemaId,
input.payload,
dependencies.schemaCodecs,
);
if (!payload.success) {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
let payloadSnapshot: unknown;
try {
payloadSnapshot = snapshotJson(
payload.data,
stream.limits.maxPayloadDepth,
stream.limits.maxPayloadNodes,
);
} catch {
return realtimeFailure("MALFORMED_EVENT", "DECODE");
}
const envelope = createEnvelope(
input,
stream,
eventType,
payloadSnapshot,
);
const semanticFingerprint = hash64(canonicalJson(envelope));
const fingerprintBytes = semanticFingerprint.length;
const dto = Object.freeze({
envelope,
wireBytes,
semanticFingerprint,
fingerprintBytes,
});
issuedDtos.add(dto);
return realtimeSuccess(dto);
}
function hasValidEnvelopeFields(
input: Readonly<Record<string, unknown>>,
stream: RealtimeStreamRegistration,
): boolean {
if (
!isRealtimeOpaqueIdentifier(input.streamEpoch) ||
!isRealtimeOpaqueIdentifier(input.eventId) ||
!isCanonicalRealtimeSequence(input.sequence) ||
!isStrictRealtimeTimestamp(input.occurredAt) ||
!isRealtimeScopeBinding(input.scopeBinding) ||
input.recoveryMode !== stream.recovery.mode
) {
return false;
}
return stream.recovery.mode === "CURSOR"
? isRealtimeResumeCursor(input.resumeCursor)
: input.resumeCursor === null;
}
function createEnvelope(
input: Readonly<Record<string, unknown>>,
stream: RealtimeStreamRegistration,
eventType: RealtimeEventTypeRegistration,
payload: unknown,
): RealtimeEventEnvelope {
const base = {
protocol: REALTIME_EVENT_PROTOCOL,
streamId: stream.id,
streamEpoch: input.streamEpoch as string,
eventType: eventType.id,
eventId: input.eventId as string,
sequence: input.sequence as string,
occurredAt: input.occurredAt as string,
scopeBinding: input.scopeBinding as string,
payload,
};
return stream.recovery.mode === "CURSOR"
? Object.freeze({
...base,
recoveryMode: "CURSOR" as const,
resumeCursor: input.resumeCursor as string,
})
: Object.freeze({
...base,
recoveryMode: stream.recovery.mode,
resumeCursor: null,
});
}
function hasExactEnvelopeKeys(
value: unknown,
): value is Readonly<Record<string, unknown>> {
if (
!value ||
typeof value !== "object" ||
Array.isArray(value) ||
Object.getPrototypeOf(value) !== Object.prototype
) {
return false;
}
const keys = Object.keys(value).sort();
return (
keys.length === ENVELOPE_KEYS.length &&
keys.every((key, index) => key === ENVELOPE_KEYS[index])
);
}
function withinJsonBudget(
value: unknown,
maxDepth: number,
maxNodes: number,
): boolean {
let nodes = 0;
const visit = (candidate: unknown, depth: number): boolean => {
nodes += 1;
if (nodes > maxNodes || depth > maxDepth) return false;
if (
candidate === null ||
typeof candidate === "string" ||
typeof candidate === "boolean" ||
(typeof candidate === "number" && Number.isFinite(candidate))
) {
return true;
}
if (Array.isArray(candidate)) {
return candidate.every((item) => visit(item, depth + 1));
}
if (
!candidate ||
typeof candidate !== "object" ||
Object.getPrototypeOf(candidate) !== Object.prototype
) {
return false;
}
return Object.entries(candidate).every(
([key, item]) =>
!FORBIDDEN_OBJECT_KEYS.has(key) && visit(item, depth + 1),
);
};
return visit(value, 0);
}
function snapshotJson(
value: unknown,
maxDepth: number,
maxNodes: number,
): unknown {
const seen = new WeakSet<object>();
let nodes = 0;
const visit = (candidate: unknown, depth: number): unknown => {
nodes += 1;
if (nodes > maxNodes || depth > maxDepth) {
throw new TypeError("Realtime payload exceeds its structural budget.");
}
if (
candidate === null ||
typeof candidate === "string" ||
typeof candidate === "boolean" ||
(typeof candidate === "number" && Number.isFinite(candidate))
) {
return candidate;
}
if (!candidate || typeof candidate !== "object") {
throw new TypeError("Realtime payload is not JSON-compatible.");
}
if (seen.has(candidate)) {
throw new TypeError("Realtime payload contains shared object identity.");
}
seen.add(candidate);
if (Array.isArray(candidate)) {
for (let index = 0; index < candidate.length; index += 1) {
if (!Object.hasOwn(candidate, index)) {
throw new TypeError("Realtime payload contains a sparse array.");
}
}
return Object.freeze(
candidate.map((item) => visit(item, depth + 1)),
);
}
if (
Object.getPrototypeOf(candidate) !== Object.prototype &&
Object.getPrototypeOf(candidate) !== null
) {
throw new TypeError("Realtime payload requires plain objects.");
}
const output: Record<string, unknown> = Object.create(null);
const descriptors = Object.getOwnPropertyDescriptors(candidate);
for (const key of Object.keys(descriptors).sort()) {
if (FORBIDDEN_OBJECT_KEYS.has(key)) {
throw new TypeError("Realtime payload contains a forbidden key.");
}
const descriptor = descriptors[key];
if (!descriptor || !("value" in descriptor)) {
throw new TypeError("Realtime payload contains an accessor.");
}
output[key] = visit(descriptor.value, depth + 1);
}
return Object.freeze(output);
};
return visit(value, 0);
}
/**
* Two differently seeded 32-bit FNV-1a hashes as 16 hex characters.
* ponytail: not collision-proof against a hostile server; a collision only
* lets a conflicting redelivery pass as a duplicate. Use SHA-256 if the
* server is not trusted to keep event IDs unique.
*/
function hash64(text: string): string {
let first = 0x811c9dc5;
let second = 0x9e3779b9;
for (let index = 0; index < text.length; index += 1) {
const unit = text.charCodeAt(index);
first = Math.imul(first ^ unit, 0x01000193);
second = Math.imul(second ^ unit, 0x01000193);
}
return (
(first >>> 0).toString(16).padStart(8, "0") +
(second >>> 0).toString(16).padStart(8, "0")
);
}
function canonicalJson(value: unknown): string {
if (
value === null ||
typeof value === "string" ||
typeof value === "boolean" ||
typeof value === "number"
) {
return JSON.stringify(value);
}
if (Array.isArray(value)) {
return `[${value.map(canonicalJson).join(",")}]`;
}
if (!value || typeof value !== "object") {
throw new TypeError("Realtime semantic identity is invalid.");
}
return `{${Object.keys(value)
.sort()
.map(
(key) =>
`${JSON.stringify(key)}:${canonicalJson(
(value as Readonly<Record<string, unknown>>)[key],
)}`,
)
.join(",")}}`;
}