Files
clean-architecture-frontend…/src/adapters/realtime/event-codec.ts
T

395 lines
10 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,
} from "../../contracts/realtime-streams.ts";
import {
validateWithRuntimeSchemaRegistry,
type RuntimeSchemaCodec,
} from "../../contracts/schema-registry.ts";
import {
hasDuplicateJsonMembers,
} from "./json-member-scanner.ts";
export type ValidatedRealtimeEventDto = Readonly<{
envelope: RealtimeEventEnvelope;
wireBytes: number;
/**
* Adapter-private semantic identity used only by the bounded conflict
* detector. 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>();
export function createRealtimeEventCodec(
dependencies: RealtimeEventCodecDependencies,
): RealtimeEventCodec {
return Object.freeze({
decode(raw: string): RealtimeResult<ValidatedRealtimeEventDto> {
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<ValidatedRealtimeEventDto> {
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 = canonicalJson(envelope);
const fingerprintBytes = encoder.encode(semanticFingerprint).byteLength;
if (fingerprintBytes > stream.limits.maxEventBytes) {
return realtimeFailure("EVENT_TOO_LARGE", "DECODE");
}
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);
}
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(",")}}`;
}