Realtime kept three DataSnapshot readers and about ten hand-written abort/timeout races, and two parsers had drifted copies in other adapters. Snapshot: reconnect-coordinator and bounded-poll now use result.ts captureRealtimeDataSnapshot (+ `source`, variadic hasExactSnapshotKeys). Kept the result.ts rules, the stricter ones: Object.hasOwn instead of `"value" in` (prototype pollution), enumerable fields only, keys read from one descriptor snapshot, frozen computed at snapshot time instead of a later Object.isFrozen. Poll therefore now rejects non-enumerable fields; it also accepts null-prototype records, which the other two copies already did (pure data, no inherited accessors). Characterization test added for both in bounded-poll-coordinator.test.ts. Race: one raceRealtimeTask(task, signal, deadline) in result.ts, built on kernel createAbortableOperation, replaces fetch-sse timed/cancelReader, reconnect race/drain (the drain keeps a host timer via timerDeadline, since the clock itself may hang), poll awaitTaskOrAbort/awaitWithinLease, live-poll checkpoint + two quiescence races (now one), stream-coordinator deadline/recovery-wait/close-drain, and the two WS inline races. Kept semantics: deadline armed first and wins a tie (poll lease), task still starts when the clock throws (reader cancel), collaborator rejections still reach stream-coordinator callers, scheduler install failure still fails closed as a timeout. Small change: nothing starts once the signal is already aborted (WS apply / SSE onEvent / reader.read could run just before being reported ABORTED). The mapping adds one microtask per race, so the reconnect test flush() helper gets 16 turns instead of 8. Kernel: parseRetryAfterDelay moves to platform/retry-after.ts (realtime re-exports it; http retry-policy parseRetryAfter now delegates, so it rejects "", " ", "1e3", "1.5", "0x10" and non-IMF dates it used to accept). json-member-scanner moves to platform/; web-push push-codec uses it instead of its top-level-only duplicate-key check, so nested duplicates are rejected too. INVENTORY 136 -> 137, detail tables updated. Tests: RED for http strict Retry-After, web-push nested duplicate, poll snapshot rules; new direct raceRealtimeTask tests. Gates: architecture, types app/test (+ service-worker/web-worker), lint, adapter-inventory (abort ratchet 21/21), test:unit, test:component, realtime-boundaries, integration/platform all pass. Realtime bundle 40346 -> 39433 gzip. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
414 lines
11 KiB
TypeScript
414 lines
11 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 "../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>();
|
|
|
|
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 = 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(",")}}`;
|
|
}
|