Files
clean-architecture-frontend…/src/adapters/realtime/event-consumer.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

239 lines
6.8 KiB
TypeScript

import type {
RealtimeAcceptDisposition,
RealtimeTransportEventOutcome,
} from "../../application/ports/realtime/event-authority.ts";
import {
REALTIME_TRANSPORT_CONTINUE,
realtimeTransportRecoveryCommitted,
} from "../../application/ports/realtime/event-authority.ts";
import type {
RealtimeResult,
} from "../../application/ports/realtime/shared.ts";
import {
isRealtimeResumeCursor,
} from "../../contracts/realtime-events.ts";
import type {
StreamRegistrationId,
} from "../../contracts/realtime-streams.ts";
import {
realtimeDecodeFailureStream,
type RealtimeEventCodec,
} from "./event-codec.ts";
import type {
RealtimeStreamCoordinator,
} from "./stream-coordinator.ts";
import {
realtimeFailure,
realtimeSuccess,
} from "./result.ts";
export type RealtimeTransportCursor =
| Readonly<{
kind: "SSE_DIRECT_CURSOR";
eventId: string;
}>
| Readonly<{ kind: "SSE_NO_CURSOR" }>
| Readonly<{ kind: "ENCAPSULATED" }>;
export type RealtimeEventConsumer = Readonly<{
consume(
rawEnvelope: string,
cursor: RealtimeTransportCursor,
signal?: AbortSignal,
): Promise<RealtimeResult<RealtimeAcceptDisposition>>;
consumeEncapsulated(
envelope: Readonly<Record<string, unknown>>,
signal?: AbortSignal,
): Promise<RealtimeResult<RealtimeAcceptDisposition>>;
consumeForTransport(
rawEnvelope: string,
cursor: RealtimeTransportCursor,
signal?: AbortSignal,
): Promise<RealtimeResult<RealtimeTransportEventOutcome>>;
consumeEncapsulatedForTransport(
envelope: Readonly<Record<string, unknown>>,
signal?: AbortSignal,
): Promise<RealtimeResult<RealtimeTransportEventOutcome>>;
}>;
/**
* The single handoff from transport bytes to the common event authority.
* SSE's transport-level `id` is checked here against the validated envelope;
* WebSocket can carry the same envelope without inventing a second cursor.
*/
export function createRealtimeEventConsumer(
dependencies: Readonly<{
codec: RealtimeEventCodec;
coordinator: Pick<RealtimeStreamCoordinator, "accept"> &
Partial<Pick<RealtimeStreamCoordinator, "invalidate">>;
}>,
): RealtimeEventConsumer {
async function consumeWithStream(
rawEnvelope: string,
cursor: RealtimeTransportCursor,
signal?: AbortSignal,
): Promise<
Readonly<{
streamId: StreamRegistrationId | null;
result: RealtimeResult<RealtimeAcceptDisposition>;
}>
> {
if (signal?.aborted) {
return {
streamId: null,
result: realtimeFailure("ABORTED", "RECEIVE"),
};
}
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;
if (
(cursor.kind === "SSE_DIRECT_CURSOR" &&
(!isRealtimeResumeCursor(cursor.eventId) ||
envelope.recoveryMode !== "CURSOR" ||
envelope.resumeCursor !== cursor.eventId)) ||
(cursor.kind === "SSE_NO_CURSOR" &&
(envelope.recoveryMode === "CURSOR" ||
envelope.resumeCursor !== null))
) {
return {
streamId: envelope.streamId,
result: realtimeFailure(
"PROTOCOL_MISMATCH",
"RECEIVE",
),
};
}
return {
streamId: envelope.streamId,
result: await dependencies.coordinator.accept(
decoded.value,
signal,
),
};
}
async function consume(
rawEnvelope: string,
cursor: RealtimeTransportCursor,
signal?: AbortSignal,
): Promise<RealtimeResult<RealtimeAcceptDisposition>> {
return (
await consumeWithStream(rawEnvelope, cursor, signal)
).result;
}
async function consumeEncapsulated(
envelope: Readonly<Record<string, unknown>>,
signal?: AbortSignal,
): Promise<RealtimeResult<RealtimeAcceptDisposition>> {
const serialized = serializeEnvelope(envelope);
if (!serialized.ok) return serialized;
return await consume(
serialized.value,
{ kind: "ENCAPSULATED" },
signal,
);
}
async function consumeForTransport(
rawEnvelope: string,
cursor: RealtimeTransportCursor,
signal?: AbortSignal,
): Promise<RealtimeResult<RealtimeTransportEventOutcome>> {
const consumed = await consumeWithStream(
rawEnvelope,
cursor,
signal,
);
return projectTransportOutcome(
consumed.result,
consumed.streamId,
);
}
async function consumeEncapsulatedForTransport(
envelope: Readonly<Record<string, unknown>>,
signal?: AbortSignal,
): Promise<RealtimeResult<RealtimeTransportEventOutcome>> {
const serialized = serializeEnvelope(envelope);
if (!serialized.ok) return serialized;
return await consumeForTransport(
serialized.value,
{ kind: "ENCAPSULATED" },
signal,
);
}
return Object.freeze({
consume,
consumeEncapsulated,
consumeForTransport,
consumeEncapsulatedForTransport,
});
}
function projectTransportOutcome(
accepted: RealtimeResult<RealtimeAcceptDisposition>,
streamId: StreamRegistrationId | null,
): RealtimeResult<RealtimeTransportEventOutcome> {
if (!accepted.ok) return accepted;
// A recovery with no barrier to confirm keeps the connection; handing it to
// the reconnect path would ask for a barrier the coordinator never set.
if (
accepted.value.outcome === "RECOVERED" &&
accepted.value.transportBarrierRequired === false
) {
return realtimeSuccess(REALTIME_TRANSPORT_CONTINUE);
}
if (
accepted.value.outcome === "RECOVERED" ||
accepted.value.outcome === "RECOVERY_BARRIER_REQUIRED"
) {
if (streamId === null) {
return realtimeFailure("PROTOCOL_MISMATCH", "RECEIVE");
}
return realtimeSuccess(
realtimeTransportRecoveryCommitted(
streamId,
accepted.value.resumeState,
),
);
}
if (accepted.value.outcome === "APPLIED") {
return realtimeSuccess(REALTIME_TRANSPORT_CONTINUE);
}
switch (accepted.value.reason) {
case "DUPLICATE_EVENT":
case "STALE_EVENT":
return realtimeSuccess(REALTIME_TRANSPORT_CONTINUE);
case "RECOVERY_IN_PROGRESS":
return realtimeFailure(
"PROTOCOL_MISMATCH",
"RECEIVE",
);
case "CLOSED":
return realtimeFailure("CLOSED", "RECEIVE");
case "SCOPE_FENCED":
return realtimeFailure("SCOPE_FENCED", "RECEIVE");
}
}
function serializeEnvelope(
envelope: Readonly<Record<string, unknown>>,
): RealtimeResult<string> {
let rawEnvelope: string;
try {
rawEnvelope = JSON.stringify(envelope);
} catch {
return realtimeFailure("MALFORMED_EVENT", "RECEIVE");
}
return typeof rawEnvelope === "string"
? realtimeSuccess(rawEnvelope)
: realtimeFailure("MALFORMED_EVENT", "RECEIVE");
}