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, } 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; }>; export type RealtimeEventCodecDependencies = Readonly<{ registry: RealtimePolicyRegistry; schemaCodecs: Readonly>; }>; 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(); export function createRealtimeEventCodec( dependencies: RealtimeEventCodecDependencies, ): RealtimeEventCodec { return Object.freeze({ decode(raw: string): RealtimeResult { try { return decodeUnsafe(raw, dependencies); } catch { return realtimeFailure("MALFORMED_EVENT", "DECODE"); } }, }); } 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, ): RealtimeResult { if (typeof raw !== "string") { return realtimeFailure("MALFORMED_EVENT", "DECODE"); } if ( raw.length > REALTIME_HARD_LIMITS.maxEventBytes || encoder.encode(raw).byteLength > REALTIME_HARD_LIMITS.maxEventBytes ) { return realtimeFailure("EVENT_TOO_LARGE", "DECODE"); } const wireBytes = encoder.encode(raw).byteLength; 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"); } 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) { return realtimeFailure("MALFORMED_EVENT", "DECODE"); } 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>, 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>, 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> { 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(); 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 = 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>)[key], )}`, ) .join(",")}}`; }