Files
clean-architecture-frontend…/src/adapters/realtime/websocket/websocket-connection.ts
T
DongHyeonkaandClaude Opus 5.5 bcad7b0d12 fix(realtime): reset the retry budget on every session end and pause it offline (04-01)
A long healthy connection that ended offline or with a throwing waitClosed
kept a spent elapsed budget and stopped with zero retries. Offline waits no
longer spend the budget, and WebSocket HEARTBEAT_ACK is now observable so a
quiet stream can earn a fresh budget.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-09-26 00:01:10 +09:00

1884 lines
48 KiB
TypeScript

import type { ClockPort } from "../../../application/ports/clock-port.ts";
import type {
RealtimeTransportEventOutcome,
} from "../../../application/ports/realtime/event-authority.ts";
import type {
RealtimeFailure,
RealtimeFailureKind,
RealtimeOperation,
RealtimeResult,
} from "../../../application/ports/realtime/shared.ts";
import {
isRealtimeResult,
isRealtimeTransportEventOutcome,
raceRealtimeTask,
realtimeFailure,
realtimeSuccess,
} from "../result.ts";
import {
REALTIME_WEBSOCKET_PROTOCOL,
decodeWebSocketServerFrame,
encodeWebSocketClientFrame,
nextUnsignedSequence,
type WebSocketAdvertisedLimits,
type WebSocketClientFrame,
type WebSocketCloseCategory,
type WebSocketEventFrame,
type WebSocketServerFrame,
type WebSocketSubscribedFrame,
} from "./websocket-protocol.ts";
export type WebSocketConnectionStatus =
| "IDLE"
| "CONNECTING"
| "OPEN"
| "CLOSING"
| "CLOSED";
export type WebSocketResumeCheckpoint = Readonly<{
streamEpoch: string;
lastAppliedSequence: string;
cursor: string | null;
}>;
export type WebSocketSubscriptionRequest = Readonly<{
subscriptionId: string;
streamId: string;
scopeBinding: string;
stateBearing: boolean;
/**
* State-bearing subscriptions require a snapshot/replay checkpoint before
* SUBSCRIBE. This prevents an initial live frame from silently becoming the
* state authority.
*/
checkpoint?: WebSocketResumeCheckpoint;
}>;
export type WebSocketRecoveryRequest = Readonly<{
subscriptionId: string | null;
reason:
| "APPLY_FAILED"
| "CURSOR_EXPIRED"
| "EVENT_RATE_EXCEEDED"
| "PROTOCOL_MISMATCH"
| "QUEUE_OVERFLOW"
| "SCOPE_CHANGED"
| "SEQUENCE_GAP"
| "SERVER_RESET";
}>;
export type WebSocketConnectionObservation = Readonly<{
kind:
| "CONNECTED"
| "SUBSCRIBED"
| "HEARTBEAT_ACK"
| "FRAME_REJECTED"
| "RECOVERY_REQUIRED"
| "CLOSED";
failureKind?: RealtimeFailureKind;
closeCategory?: WebSocketCloseCategory;
}>;
export type WebSocketConnectionSnapshot = Readonly<{
status: WebSocketConnectionStatus;
subscriptionCount: number;
inboundQueueCount: number;
inboundQueueBytes: number;
outboundQueueCount: number;
outboundQueueBytes: number;
awaitingHeartbeatAck: boolean;
}>;
export type WebSocketOpenReceipt = Readonly<{
protocol: typeof REALTIME_WEBSOCKET_PROTOCOL;
effectiveLimits: WebSocketAdvertisedLimits;
}>;
export type WebSocketSubscribedReceipt = Readonly<{
subscriptionId: string;
streamId: string;
streamEpoch: string;
acceptedCursor: string | null;
nextExpectedSequence: string;
}>;
export type WebSocketLocalSendReceipt = Readonly<{
acceptedLocally: true;
}>;
export type WebSocketInboundEventOutcome =
RealtimeTransportEventOutcome;
export type WebSocketClosedReceipt = Readonly<{
category: WebSocketCloseCategory;
error: RealtimeFailure;
recovery: Extract<
RealtimeTransportEventOutcome,
{ kind: "RECOVERY_COMMITTED" }
> | null;
}>;
export type WebSocketFacade = Readonly<{
protocol: string;
readyState: number;
bufferedAmount: number;
send(data: string): void;
close(code?: number, reason?: string): void;
addEventListener(
type: "open" | "message" | "close" | "error",
listener: (event: unknown) => void,
): void;
removeEventListener(
type: "open" | "message" | "close" | "error",
listener: (event: unknown) => void,
): void;
}>;
export type WebSocketConnection = Readonly<{
connect(
signal?: AbortSignal,
): Promise<RealtimeResult<WebSocketOpenReceipt>>;
subscribe(
request: WebSocketSubscriptionRequest,
): RealtimeResult<WebSocketLocalSendReceipt>;
unsubscribe(
subscriptionId: string,
): RealtimeResult<WebSocketLocalSendReceipt>;
waitClosed(): Promise<WebSocketClosedReceipt>;
close(category?: WebSocketCloseCategory): void;
inspect(): WebSocketConnectionSnapshot;
}>;
export type WebSocketConnectionDependencies = Readonly<{
origin: string;
endpointPath: string;
clock: ClockPort;
createNonce(): string;
createSocket(
endpoint: string,
protocol: typeof REALTIME_WEBSOCKET_PROTOCOL,
): WebSocketFacade;
onEvent(
frame: WebSocketEventFrame,
signal: AbortSignal,
): Promise<RealtimeResult<WebSocketInboundEventOutcome>>;
/**
* Runs after the SUBSCRIBED cursor/epoch/sequence contract is validated and
* before the subscription becomes an event writer. A reconnect bridge can
* hold this gate until the exact recovery checkpoint is confirmed.
*/
onSubscribed?(
receipt: WebSocketSubscribedReceipt,
signal: AbortSignal,
):
| RealtimeResult<void>
| Promise<RealtimeResult<void>>;
onRecoveryRequired(request: WebSocketRecoveryRequest): void;
heartbeatEligible?(): boolean;
observe?(observation: WebSocketConnectionObservation): void;
verifyCursorRotation?(input: Readonly<{
requestedCursor: string;
acceptedCursor: string;
streamEpoch: string;
nextExpectedSequence: string;
}>): boolean;
ceilings?: Partial<WebSocketClientCeilings>;
}>;
export type WebSocketClientCeilings = Readonly<
WebSocketAdvertisedLimits & {
connectTimeoutMs: number;
minHeartbeatMs: number;
maxHeartbeatMs: number;
minHeartbeatAckTimeoutMs: number;
maxHeartbeatAckTimeoutMs: number;
maxApplyMs: number;
}
>;
export const WEBSOCKET_IMPLEMENTATION_CEILINGS: WebSocketClientCeilings =
Object.freeze({
maxFrameBytes: 64 * 1_024,
maxSubscriptions: 32,
maxInboundQueueCount: 256,
maxInboundQueueBytes: 4 * 1_024 * 1_024,
maxOutboundQueueCount: 128,
maxOutboundQueueBytes: 256 * 1_024,
maxBufferedAmountBytes: 256 * 1_024,
maxEventsPerSecond: 256,
connectTimeoutMs: 30_000,
minHeartbeatMs: 5_000,
maxHeartbeatMs: 60_000,
minHeartbeatAckTimeoutMs: 1_000,
maxHeartbeatAckTimeoutMs: 30_000,
maxApplyMs: 30_000,
});
type SubscriptionState = {
readonly request: WebSocketSubscriptionRequest;
state: "PENDING" | "ACTIVE" | "UNSUBSCRIBING";
unsubscribeController: AbortController | null;
eventWindowStartedAt: number;
eventCount: number;
};
type QueuedFrame = Readonly<{
frame: WebSocketServerFrame;
byteLength: number;
}>;
type QueuedOutboundFrame = Readonly<{
data: string;
byteLength: number;
operation: RealtimeOperation;
}>;
const IDENTIFIER = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u;
const OPAQUE_VALUE = /^[A-Za-z0-9][A-Za-z0-9._~:+/=-]{0,511}$/u;
const NATIVE_CONNECTING = 0;
const NATIVE_OPEN = 1;
const NATIVE_CLOSING = 2;
const PRIVATE_CLOSE_CODE = 4_000;
/**
* One connection generation. Reconnect ownership deliberately remains
* outside this object so a route/component cannot create competing retry
* loops.
*/
export function createWebSocketConnection(
dependencies: WebSocketConnectionDependencies,
): WebSocketConnection {
if (
dependencies.onSubscribed !== undefined &&
typeof dependencies.onSubscribed !== "function"
) {
throw new TypeError("WebSocket subscribed barrier is invalid.");
}
const endpointCandidate = fixedSameOriginWebSocketEndpoint(
dependencies.origin,
dependencies.endpointPath,
);
if (!endpointCandidate) {
throw new TypeError("WebSocket endpoint policy is invalid.");
}
const endpoint: string = endpointCandidate;
const ceilings = resolveCeilings(dependencies.ceilings);
let status: WebSocketConnectionStatus = "IDLE";
let socket: WebSocketFacade | null = null;
let transportOpened = false;
let welcomeReceived = false;
let effectiveLimits: WebSocketAdvertisedLimits | null = null;
const generation = new AbortController();
const connectDeadlineController = new AbortController();
let externalAbortCleanup: (() => void) | null = null;
let settleConnect:
| ((
result: RealtimeResult<WebSocketOpenReceipt>,
) => void)
| null = null;
let connectPromise:
| Promise<RealtimeResult<WebSocketOpenReceipt>>
| null = null;
let settleClosed:
| ((receipt: WebSocketClosedReceipt) => void)
| null = null;
const closedPromise = new Promise<WebSocketClosedReceipt>(
(resolve) => {
settleClosed = resolve;
},
);
let closeObserved = false;
let processing = false;
let queuedBytes = 0;
let outboundQueuedBytes = 0;
let outboundDrainScheduled = false;
let outboundDraining = false;
let outstandingHeartbeat: string | null = null;
let retiredHeartbeat: string | null = null;
const queue: QueuedFrame[] = [];
const outboundQueue: QueuedOutboundFrame[] = [];
const subscriptions = new Map<string, SubscriptionState>();
const openListener = () => {
if (status !== "CONNECTING" || !socket) return;
if (socket.protocol !== REALTIME_WEBSOCKET_PROTOCOL) {
terminate(
failure(
"PROTOCOL_MISMATCH",
"CONNECT",
false,
),
"PROTOCOL_MISMATCH",
{
subscriptionId: null,
reason: "PROTOCOL_MISMATCH",
},
);
return;
}
transportOpened = true;
};
const messageListener = (event: unknown) => {
if (status === "CLOSED" || status === "CLOSING") return;
let decoded: ReturnType<typeof decodeWebSocketServerFrame>;
try {
const data = eventData(event);
decoded = decodeWebSocketServerFrame(
data,
effectiveLimits?.maxFrameBytes ?? ceilings.maxFrameBytes,
);
} catch {
decoded = Object.freeze({
ok: false,
error: Object.freeze({
code: "MALFORMED_FRAME" as const,
}),
});
}
if (!decoded.ok) {
const code =
decoded.error.code === "FRAME_TOO_LARGE"
? "EVENT_TOO_LARGE"
: decoded.error.code === "PROTOCOL_MISMATCH"
? "PROTOCOL_MISMATCH"
: "MALFORMED_EVENT";
observe({
kind: "FRAME_REJECTED",
failureKind: code,
});
terminate(
failure(code, "RECEIVE", false),
"PROTOCOL_MISMATCH",
{
subscriptionId: null,
reason: "PROTOCOL_MISMATCH",
},
);
return;
}
if (decoded.value.type === "HEARTBEAT_ACK") {
if (
!welcomeReceived ||
(decoded.value.nonce !== outstandingHeartbeat &&
decoded.value.nonce !== retiredHeartbeat)
) {
terminateProtocol();
return;
}
if (decoded.value.nonce === outstandingHeartbeat) {
outstandingHeartbeat = null;
}
if (decoded.value.nonce === retiredHeartbeat) {
retiredHeartbeat = null;
}
// A quiet stream's only liveness proof; composition can forward it to
// the reconnect coordinator's markValidHeartbeatOrEvent.
observe({ kind: "HEARTBEAT_ACK" });
return;
}
const queueLimits = effectiveLimits ?? ceilings;
if (
queue.length + 1 > queueLimits.maxInboundQueueCount ||
queuedBytes + decoded.byteLength >
queueLimits.maxInboundQueueBytes
) {
terminate(
failure(
"QUEUE_OVERFLOW",
"RECEIVE",
false,
),
"CURSOR_RESET",
{
subscriptionId: null,
reason: "QUEUE_OVERFLOW",
},
);
return;
}
queue.push(
Object.freeze({
frame: decoded.value,
byteLength: decoded.byteLength,
}),
);
queuedBytes += decoded.byteLength;
void drainQueue();
};
const closeListener = (event: unknown) => {
if (status === "CLOSED") return;
const category = mapNativeCloseCategory(eventCode(event));
terminate(
closeFailure(category),
category,
category === "CURSOR_RESET"
? {
subscriptionId: null,
reason: "CURSOR_EXPIRED",
}
: undefined,
false,
);
};
const errorListener = () => {
if (status === "CLOSED") return;
terminate(
failure(
"PROVIDER_UNAVAILABLE",
status === "CONNECTING"
? "CONNECT"
: "RECEIVE",
true,
),
"NETWORK_LOST",
undefined,
);
};
async function connect(
signal?: AbortSignal,
): Promise<RealtimeResult<WebSocketOpenReceipt>> {
if (status === "CLOSED" || status === "CLOSING") {
return connectionFailure(
"CLOSED",
"CONNECT",
false,
);
}
if (connectPromise) return connectPromise;
if (status !== "IDLE") {
return connectionFailure(
"CLOSED",
"CONNECT",
false,
);
}
if (signal?.aborted) {
const aborted = connectionFailure(
"ABORTED",
"CONNECT",
false,
);
terminate(
aborted.error,
"NORMAL",
undefined,
false,
);
return aborted;
}
status = "CONNECTING";
connectPromise = new Promise((resolve) => {
settleConnect = resolve;
});
try {
socket = dependencies.createSocket(
endpoint,
REALTIME_WEBSOCKET_PROTOCOL,
);
socket.addEventListener("open", openListener);
socket.addEventListener("message", messageListener);
socket.addEventListener("close", closeListener);
socket.addEventListener("error", errorListener);
} catch {
terminate(
failure(
"PROVIDER_UNAVAILABLE",
"CONNECT",
true,
),
"NETWORK_LOST",
undefined,
);
return connectPromise;
}
if (signal) {
const abort = () => {
terminate(
failure(
"ABORTED",
"CONNECT",
false,
),
"NORMAL",
undefined,
);
};
signal.addEventListener("abort", abort, { once: true });
externalAbortCleanup = () =>
signal.removeEventListener("abort", abort);
if (signal.aborted) abort();
}
void connectDeadline(connectDeadlineController.signal);
return connectPromise;
}
function subscribe(
request: WebSocketSubscriptionRequest,
): RealtimeResult<WebSocketLocalSendReceipt> {
if (
status !== "OPEN" ||
!effectiveLimits ||
!isSubscriptionRequest(request) ||
(request.stateBearing && !request.checkpoint) ||
subscriptions.has(request.subscriptionId) ||
subscriptions.size >= effectiveLimits.maxSubscriptions
) {
return connectionFailure(
status === "OPEN" ? "PROTOCOL_MISMATCH" : "CLOSED",
"SUBSCRIBE",
false,
);
}
const eventWindowStartedAt = readClockNow(dependencies.clock);
if (eventWindowStartedAt === null) {
const unavailable = connectionFailure(
"PROVIDER_UNAVAILABLE",
"SUBSCRIBE",
true,
);
terminate(
unavailable.error,
"NETWORK_LOST",
undefined,
);
return unavailable;
}
const frame: WebSocketClientFrame = {
type: "SUBSCRIBE",
protocol: REALTIME_WEBSOCKET_PROTOCOL,
subscriptionId: request.subscriptionId,
streamId: request.streamId,
cursor: request.checkpoint?.cursor ?? null,
scopeBinding: request.scopeBinding,
};
const sent = sendCritical(frame, "SUBSCRIBE");
if (!sent.ok) return sent;
subscriptions.set(request.subscriptionId, {
request: snapshotSubscriptionRequest(request),
state: "PENDING",
unsubscribeController: null,
eventWindowStartedAt,
eventCount: 0,
});
return sent;
}
function unsubscribe(
subscriptionId: string,
): RealtimeResult<WebSocketLocalSendReceipt> {
const subscription = subscriptions.get(subscriptionId);
if (
status !== "OPEN" ||
!IDENTIFIER.test(subscriptionId) ||
!subscription ||
subscription.state === "UNSUBSCRIBING"
) {
return connectionFailure(
status === "OPEN" ? "PROTOCOL_MISMATCH" : "CLOSED",
"SUBSCRIBE",
false,
);
}
const sent = sendCritical(
{
type: "UNSUBSCRIBE",
protocol: REALTIME_WEBSOCKET_PROTOCOL,
subscriptionId,
},
"SUBSCRIBE",
);
if (sent.ok) {
subscription.state = "UNSUBSCRIBING";
startUnsubscribeDeadline(subscriptionId, subscription);
}
return sent;
}
function waitClosed(): Promise<WebSocketClosedReceipt> {
return closedPromise;
}
function close(
category: WebSocketCloseCategory = "NORMAL",
): void {
if (status === "CLOSED" || status === "CLOSING") return;
if (
status === "OPEN" &&
socket?.readyState === NATIVE_OPEN &&
effectiveLimits
) {
const sent = sendCritical(
{
type: "CLOSE",
protocol: REALTIME_WEBSOCKET_PROTOCOL,
category,
},
"CLOSE",
);
if (sent.ok) drainOutboundQueue();
}
terminate(
failure("CLOSED", "CLOSE", false),
category,
undefined,
);
}
function inspect(): WebSocketConnectionSnapshot {
return Object.freeze({
status,
subscriptionCount: countLiveSubscriptions(subscriptions),
inboundQueueCount: queue.length,
inboundQueueBytes: queuedBytes,
outboundQueueCount: outboundQueue.length,
outboundQueueBytes: outboundQueuedBytes,
awaitingHeartbeatAck: outstandingHeartbeat !== null,
});
}
async function connectDeadline(signal: AbortSignal): Promise<void> {
try {
await dependencies.clock.sleep(ceilings.connectTimeoutMs, signal);
if (status === "CONNECTING") {
terminate(
failure(
"CONNECT_TIMEOUT",
"CONNECT",
true,
),
"NETWORK_LOST",
undefined,
);
}
} catch {
if (
!signal.aborted &&
status === "CONNECTING"
) {
terminate(
failure(
"PROVIDER_UNAVAILABLE",
"CONNECT",
true,
),
"NETWORK_LOST",
undefined,
);
}
}
}
async function drainQueue(): Promise<void> {
if (processing) return;
processing = true;
try {
while (queue.length > 0 && status !== "CLOSED") {
const queued = queue.shift();
if (!queued) break;
queuedBytes -= queued.byteLength;
await processFrame(queued.frame);
}
} finally {
processing = false;
}
}
async function processFrame(
frame: WebSocketServerFrame,
): Promise<void> {
if (!welcomeReceived) {
if (frame.type !== "WELCOME" || !transportOpened) {
terminateProtocol();
return;
}
processWelcome(frame);
return;
}
if (frame.type === "WELCOME") {
terminateProtocol();
return;
}
switch (frame.type) {
case "SUBSCRIBED":
await processSubscribed(frame);
return;
case "UNSUBSCRIBED": {
const subscription = subscriptions.get(
frame.subscriptionId,
);
if (
!subscription ||
subscription.state !== "UNSUBSCRIBING"
) {
terminateProtocol();
return;
}
subscription.unsubscribeController?.abort();
subscription.unsubscribeController = null;
subscriptions.delete(frame.subscriptionId);
return;
}
case "EVENT":
await processEvent(frame);
return;
case "RESET_REQUIRED": {
const subscription = subscriptions.get(
frame.subscriptionId,
);
if (!subscription) {
terminateProtocol();
return;
}
if (subscription.state === "UNSUBSCRIBING") return;
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: frame.reason,
});
terminate(
failure(
resetFailureCode(frame.reason),
"RECEIVE",
false,
),
"CURSOR_RESET",
undefined,
);
return;
}
case "HEARTBEAT_ACK":
// HEARTBEAT_ACK is consumed by the bounded control path in the
// message listener so application effects cannot head-of-line block
// the acknowledgement deadline.
terminateProtocol();
return;
case "CLOSE":
terminate(
closeFailure(frame.category),
frame.category,
frame.category === "CURSOR_RESET"
? {
subscriptionId: null,
reason: "CURSOR_EXPIRED",
}
: undefined,
);
return;
}
}
function processWelcome(
frame: Extract<WebSocketServerFrame, { type: "WELCOME" }>,
): void {
if (
frame.heartbeatMs < ceilings.minHeartbeatMs ||
frame.heartbeatMs > ceilings.maxHeartbeatMs ||
frame.heartbeatAckTimeoutMs <
ceilings.minHeartbeatAckTimeoutMs ||
frame.heartbeatAckTimeoutMs >
ceilings.maxHeartbeatAckTimeoutMs
) {
terminateProtocol();
return;
}
effectiveLimits = minLimits(ceilings, frame.limits);
welcomeReceived = true;
status = "OPEN";
connectDeadlineController.abort();
settleOpen(
realtimeSuccess(
Object.freeze({
protocol: REALTIME_WEBSOCKET_PROTOCOL,
effectiveLimits,
}),
),
);
observe({ kind: "CONNECTED" });
void heartbeatLoop(
generation.signal,
frame.heartbeatMs,
frame.heartbeatAckTimeoutMs,
);
}
async function processSubscribed(
frame: WebSocketSubscribedFrame,
): Promise<void> {
const subscription = subscriptions.get(frame.subscriptionId);
if (!subscription) {
terminateProtocol();
return;
}
if (subscription.state === "UNSUBSCRIBING") return;
if (subscription.state !== "PENDING") {
terminateProtocol();
return;
}
const checkpoint = subscription.request.checkpoint;
if (checkpoint) {
const expectedSequence = nextUnsignedSequence(
checkpoint.lastAppliedSequence,
);
const cursorMatches =
checkpoint.cursor === null
? frame.acceptedCursor === null
: frame.acceptedCursor === checkpoint.cursor ||
(frame.acceptedCursor !== null &&
verifyCursorRotation(
dependencies.verifyCursorRotation,
checkpoint.cursor,
frame.acceptedCursor,
frame.streamEpoch,
frame.nextExpectedSequence,
));
if (
expectedSequence === null ||
frame.streamEpoch !== checkpoint.streamEpoch ||
frame.nextExpectedSequence !== expectedSequence ||
!cursorMatches
) {
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: "SEQUENCE_GAP",
});
terminate(
failure(
"SEQUENCE_GAP",
"RECEIVE",
false,
),
"CURSOR_RESET",
undefined,
);
return;
}
} else if (subscription.request.stateBearing) {
terminateProtocol();
return;
} else if (frame.acceptedCursor !== null) {
terminateProtocol();
return;
}
const onSubscribed = dependencies.onSubscribed;
if (onSubscribed) {
const outcome = await raceRealtimeTask(
(signal) =>
Promise.resolve().then(() =>
onSubscribed(
Object.freeze({
subscriptionId: frame.subscriptionId,
streamId: subscription.request.streamId,
streamEpoch: frame.streamEpoch,
acceptedCursor: frame.acceptedCursor,
nextExpectedSequence: frame.nextExpectedSequence,
}),
signal,
),
),
generation.signal,
(signal) => dependencies.clock.sleep(ceilings.maxApplyMs, signal),
);
if (outcome.kind === "TIMEOUT" && status !== "CLOSED") {
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: "APPLY_FAILED",
});
terminate(
failure(
"APPLY_FAILED",
"RECOVER",
false,
),
"CURSOR_RESET",
undefined,
);
return;
}
if (outcome.kind === "VALUE" && status !== "CLOSED") {
if (!isRealtimeResult(outcome.value, isUndefined)) {
terminateInboundFailure(
realtimeFailure(
"PROTOCOL_MISMATCH",
"RECOVER",
false,
).error,
frame.subscriptionId,
);
return;
}
if (!outcome.value.ok) {
terminateInboundFailure(
outcome.value.error,
frame.subscriptionId,
);
return;
}
}
if (outcome.kind !== "TIMEOUT" && outcome.kind !== "VALUE") {
if (status !== "CLOSED" && !generation.signal.aborted) {
terminateInboundFailure(
realtimeFailure(
"PROVIDER_UNAVAILABLE",
"RECOVER",
false,
).error,
frame.subscriptionId,
);
}
return;
}
}
if (
status !== "OPEN" ||
generation.signal.aborted ||
subscription.state !== "PENDING"
) {
return;
}
subscription.state = "ACTIVE";
observe({ kind: "SUBSCRIBED" });
}
async function processEvent(
frame: WebSocketEventFrame,
): Promise<void> {
const subscription = subscriptions.get(frame.subscriptionId);
if (!subscription) {
terminateProtocol();
return;
}
if (subscription.state === "UNSUBSCRIBING") return;
if (subscription.state !== "ACTIVE") {
terminateProtocol();
return;
}
if (
frame.envelope.streamId !==
subscription.request.streamId
) {
terminateProtocol();
return;
}
const now = readClockNow(dependencies.clock);
if (now === null) {
terminate(
failure(
"PROVIDER_UNAVAILABLE",
"RECEIVE",
true,
),
"NETWORK_LOST",
undefined,
);
return;
}
if (now - subscription.eventWindowStartedAt >= 1_000) {
subscription.eventWindowStartedAt = now;
subscription.eventCount = 0;
}
subscription.eventCount += 1;
if (
subscription.eventCount >
(effectiveLimits?.maxEventsPerSecond ??
ceilings.maxEventsPerSecond)
) {
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: "EVENT_RATE_EXCEEDED",
});
terminate(
failure(
"QUEUE_OVERFLOW",
"RECEIVE",
false,
),
"CURSOR_RESET",
undefined,
);
return;
}
const outcome = await raceRealtimeTask(
(signal) => dependencies.onEvent(frame, signal),
generation.signal,
(signal) => dependencies.clock.sleep(ceilings.maxApplyMs, signal),
);
const handled =
outcome.kind === "VALUE" &&
isRealtimeResult(outcome.value, isRealtimeTransportEventOutcome)
? outcome.value
: null;
if (!handled) {
// Timed out, returned no valid result, or failed while still current.
if (
status !== "CLOSED" &&
(outcome.kind === "TIMEOUT" ||
outcome.kind === "VALUE" ||
!generation.signal.aborted)
) {
requestRecovery({
subscriptionId: frame.subscriptionId,
reason: "APPLY_FAILED",
});
terminate(
failure(
"APPLY_FAILED",
"RECEIVE",
false,
),
"CURSOR_RESET",
undefined,
);
}
} else if (status !== "CLOSED") {
if (!handled.ok) {
terminateInboundFailure(handled.error, frame.subscriptionId);
} else if (handled.value.kind === "RECOVERY_COMMITTED") {
terminate(
failure(
"CURSOR_EXPIRED",
"RECEIVE",
false,
),
"CURSOR_RESET",
undefined,
true,
handled.value,
);
}
}
}
function terminateInboundFailure(
terminalFailure: RealtimeFailure,
subscriptionId: string,
): void {
terminate(
terminalFailure,
closeCategoryForInboundFailure(terminalFailure),
recoveryRequestForInboundFailure(
terminalFailure.kind,
subscriptionId,
),
);
}
async function heartbeatLoop(
signal: AbortSignal,
heartbeatMs: number,
ackTimeoutMs: number,
): Promise<void> {
try {
while (!signal.aborted && status === "OPEN") {
await dependencies.clock.sleep(heartbeatMs, signal);
if (signal.aborted || status !== "OPEN") return;
const eligible = heartbeatIsEligible();
if (eligible === null) {
terminateClockFailure();
return;
}
if (!eligible) continue;
if (outstandingHeartbeat !== null) {
terminateIdleTimeout();
return;
}
const nonce = dependencies.createNonce();
if (!IDENTIFIER.test(nonce)) {
terminateProtocol();
return;
}
const sent = sendCritical(
{
type: "HEARTBEAT",
protocol: REALTIME_WEBSOCKET_PROTOCOL,
nonce,
},
"SEND",
);
if (!sent.ok) return;
retiredHeartbeat = null;
outstandingHeartbeat = nonce;
await dependencies.clock.sleep(ackTimeoutMs, signal);
const stillEligible = heartbeatIsEligible();
if (stillEligible === null) {
if (!signal.aborted && status === "OPEN") {
terminateClockFailure();
}
return;
}
if (
!signal.aborted &&
status === "OPEN" &&
outstandingHeartbeat === nonce &&
!stillEligible
) {
outstandingHeartbeat = null;
retiredHeartbeat = nonce;
continue;
}
if (
!signal.aborted &&
status === "OPEN" &&
outstandingHeartbeat === nonce
) {
terminateIdleTimeout();
return;
}
}
} catch {
if (!signal.aborted && status === "OPEN") {
terminateClockFailure();
}
}
}
function heartbeatIsEligible(): boolean | null {
try {
return dependencies.heartbeatEligible?.() !== false;
} catch {
return null;
}
}
function terminateClockFailure(): void {
terminate(
failure(
"PROVIDER_UNAVAILABLE",
"RECEIVE",
true,
),
"NETWORK_LOST",
undefined,
);
}
function terminateIdleTimeout(): void {
terminate(
failure(
"IDLE_TIMEOUT",
"RECEIVE",
true,
),
"NETWORK_LOST",
undefined,
);
}
function terminateProtocol(): void {
requestRecovery({
subscriptionId: null,
reason: "PROTOCOL_MISMATCH",
});
terminate(
failure(
"PROTOCOL_MISMATCH",
"RECEIVE",
false,
),
"PROTOCOL_MISMATCH",
undefined,
);
}
function sendCritical(
frame: WebSocketClientFrame,
operation: RealtimeOperation,
): RealtimeResult<WebSocketLocalSendReceipt> {
if (
status !== "OPEN" ||
!socket ||
socket.readyState !== NATIVE_OPEN ||
!effectiveLimits
) {
return connectionFailure("CLOSED", operation, false);
}
const encoded = encodeWebSocketClientFrame(
frame,
effectiveLimits.maxFrameBytes,
);
if (!encoded.ok) {
return connectionFailure(
encoded.error.code === "FRAME_TOO_LARGE"
? "EVENT_TOO_LARGE"
: "PROTOCOL_MISMATCH",
operation,
false,
);
}
if (
outboundQueue.length + 1 >
effectiveLimits.maxOutboundQueueCount ||
outboundQueuedBytes + encoded.byteLength >
effectiveLimits.maxOutboundQueueBytes
) {
return terminateOutboundOverflow(operation);
}
const bufferedAmount = readSocketBufferedAmount(socket);
if (bufferedAmount === null) {
const result = connectionFailure(
"PROVIDER_UNAVAILABLE",
operation,
true,
);
terminate(result.error, "NETWORK_LOST", undefined);
return result;
}
if (
bufferedAmount +
outboundQueuedBytes +
encoded.byteLength >
effectiveLimits.maxBufferedAmountBytes
) {
return terminateOutboundOverflow(operation);
}
outboundQueue.push(
Object.freeze({
data: encoded.value,
byteLength: encoded.byteLength,
operation,
}),
);
outboundQueuedBytes += encoded.byteLength;
scheduleOutboundDrain();
return realtimeSuccess(
Object.freeze({ acceptedLocally: true as const }),
);
}
function scheduleOutboundDrain(): void {
if (outboundDrainScheduled || outboundDraining) return;
outboundDrainScheduled = true;
void Promise.resolve().then(() => {
outboundDrainScheduled = false;
drainOutboundQueue();
});
}
function drainOutboundQueue(): void {
if (outboundDraining) return;
outboundDraining = true;
try {
while (outboundQueue.length > 0 && status === "OPEN") {
if (!socket || !effectiveLimits) return;
const queued = outboundQueue[0];
if (!queued) return;
const bufferedAmount = readSocketBufferedAmount(socket);
if (bufferedAmount === null) {
terminate(
failure(
"PROVIDER_UNAVAILABLE",
queued.operation,
true,
),
"NETWORK_LOST",
undefined,
);
return;
}
if (
bufferedAmount + queued.byteLength >
effectiveLimits.maxBufferedAmountBytes
) {
terminateOutboundOverflow(queued.operation);
return;
}
outboundQueue.shift();
outboundQueuedBytes -= queued.byteLength;
try {
socket.send(queued.data);
} catch {
terminate(
failure(
"PROVIDER_UNAVAILABLE",
queued.operation,
true,
),
"NETWORK_LOST",
undefined,
);
return;
}
}
} finally {
outboundDraining = false;
}
}
function terminateOutboundOverflow(
operation: RealtimeOperation,
): Extract<RealtimeResult<never>, { ok: false }> {
const result = connectionFailure(
"QUEUE_OVERFLOW",
operation,
false,
);
terminate(result.error, "OVERLOADED", {
subscriptionId: null,
reason: "QUEUE_OVERFLOW",
});
return result;
}
function terminate(
terminalFailure: RealtimeFailure,
category: WebSocketCloseCategory,
recoveryRequest?: WebSocketRecoveryRequest,
closeNative = true,
committedRecovery: Extract<
RealtimeTransportEventOutcome,
{ kind: "RECOVERY_COMMITTED" }
> | null = null,
): void {
if (status === "CLOSED") return;
status = "CLOSING";
if (recoveryRequest) requestRecovery(recoveryRequest);
connectDeadlineController.abort();
generation.abort();
externalAbortCleanup?.();
externalAbortCleanup = null;
queue.length = 0;
queuedBytes = 0;
outboundQueue.length = 0;
outboundQueuedBytes = 0;
outboundDrainScheduled = false;
for (const subscription of subscriptions.values()) {
subscription.unsubscribeController?.abort();
subscription.unsubscribeController = null;
}
subscriptions.clear();
outstandingHeartbeat = null;
retiredHeartbeat = null;
detachSocket();
if (
closeNative &&
socket &&
(socket.readyState === NATIVE_CONNECTING ||
socket.readyState === NATIVE_OPEN ||
socket.readyState === NATIVE_CLOSING)
) {
try {
socket.close(
category === "NORMAL" ? 1_000 : PRIVATE_CLOSE_CODE,
);
} catch {
// Teardown remains idempotent even when the native provider throws.
}
}
status = "CLOSED";
settleOpen(Object.freeze({ ok: false, error: terminalFailure }));
const settleTerminal = settleClosed;
settleClosed = null;
settleTerminal?.(
Object.freeze({
category,
error: terminalFailure,
recovery: committedRecovery,
}),
);
if (!closeObserved) {
closeObserved = true;
observe({
kind: "CLOSED",
failureKind: terminalFailure.kind,
closeCategory: category,
});
}
}
function detachSocket(): void {
if (!socket) return;
try {
socket.removeEventListener("open", openListener);
socket.removeEventListener("message", messageListener);
socket.removeEventListener("close", closeListener);
socket.removeEventListener("error", errorListener);
} catch {
// Listener cleanup is best effort after the generation is fenced.
}
}
function startUnsubscribeDeadline(
subscriptionId: string,
subscription: SubscriptionState,
): void {
const controller = new AbortController();
const abort = () => controller.abort();
generation.signal.addEventListener("abort", abort, {
once: true,
});
if (generation.signal.aborted) abort();
subscription.unsubscribeController = controller;
void (async () => {
try {
await dependencies.clock.sleep(
ceilings.maxApplyMs,
controller.signal,
);
if (
status === "OPEN" &&
subscriptions.get(subscriptionId) === subscription &&
subscription.state === "UNSUBSCRIBING" &&
subscription.unsubscribeController === controller
) {
terminate(
failure(
"IDLE_TIMEOUT",
"SUBSCRIBE",
true,
),
"NETWORK_LOST",
undefined,
);
}
} catch {
if (
!controller.signal.aborted &&
status === "OPEN" &&
subscriptions.get(subscriptionId) === subscription &&
subscription.state === "UNSUBSCRIBING" &&
subscription.unsubscribeController === controller
) {
terminate(
failure(
"PROVIDER_UNAVAILABLE",
"SUBSCRIBE",
true,
),
"NETWORK_LOST",
undefined,
);
}
} finally {
generation.signal.removeEventListener("abort", abort);
if (subscription.unsubscribeController === controller) {
subscription.unsubscribeController = null;
}
}
})();
}
function settleOpen(
result: RealtimeResult<WebSocketOpenReceipt>,
): void {
const settle = settleConnect;
settleConnect = null;
settle?.(result);
}
function requestRecovery(request: WebSocketRecoveryRequest): void {
try {
dependencies.onRecoveryRequired(Object.freeze({ ...request }));
} catch {
// Recovery observation cannot change connection safety.
}
observe({ kind: "RECOVERY_REQUIRED" });
}
function observe(observation: WebSocketConnectionObservation): void {
try {
dependencies.observe?.(Object.freeze({ ...observation }));
} catch {
// Best-effort telemetry never controls the protocol.
}
}
return Object.freeze({
connect,
subscribe,
unsubscribe,
waitClosed,
close,
inspect,
});
}
function countLiveSubscriptions(
subscriptions: ReadonlyMap<string, SubscriptionState>,
): number {
let count = 0;
for (const subscription of subscriptions.values()) {
if (subscription.state !== "UNSUBSCRIBING") count += 1;
}
return count;
}
function readClockNow(clock: ClockPort): number | null {
try {
const value = clock.now();
return Number.isFinite(value) && value >= 0 ? value : null;
} catch {
return null;
}
}
function readSocketBufferedAmount(
socket: WebSocketFacade,
): number | null {
try {
const value = socket.bufferedAmount;
return Number.isSafeInteger(value) && value >= 0 ? value : null;
} catch {
return null;
}
}
function closeCategoryForInboundFailure(
error: RealtimeFailure,
): WebSocketCloseCategory {
switch (error.kind) {
case "ABORTED":
case "CLOSED":
return "NORMAL";
case "AUTH_REQUIRED":
return "AUTH_REQUIRED";
case "FORBIDDEN":
return "FORBIDDEN";
case "PROTOCOL_MISMATCH":
case "MALFORMED_EVENT":
case "MAPPING_CONTRACT_VIOLATION":
case "EVENT_CONFLICT":
return "PROTOCOL_MISMATCH";
case "CURSOR_EXPIRED":
case "SEQUENCE_GAP":
case "QUEUE_OVERFLOW":
case "EVENT_TOO_LARGE":
case "APPLY_FAILED":
case "SCOPE_FENCED":
case "SCOPE_PROTOCOL_VIOLATION":
return "CURSOR_RESET";
default:
return "NETWORK_LOST";
}
}
function recoveryRequestForInboundFailure(
kind: RealtimeFailureKind,
subscriptionId: string,
): WebSocketRecoveryRequest | undefined {
switch (kind) {
case "CURSOR_EXPIRED":
return { subscriptionId, reason: "CURSOR_EXPIRED" };
case "SEQUENCE_GAP":
return { subscriptionId, reason: "SEQUENCE_GAP" };
case "SCOPE_FENCED":
case "SCOPE_PROTOCOL_VIOLATION":
return { subscriptionId, reason: "SCOPE_CHANGED" };
case "QUEUE_OVERFLOW":
return { subscriptionId, reason: "QUEUE_OVERFLOW" };
case "APPLY_FAILED":
return { subscriptionId, reason: "APPLY_FAILED" };
case "MALFORMED_EVENT":
case "MAPPING_CONTRACT_VIOLATION":
case "EVENT_CONFLICT":
case "PROTOCOL_MISMATCH":
return { subscriptionId, reason: "PROTOCOL_MISMATCH" };
default:
return undefined;
}
}
function fixedSameOriginWebSocketEndpoint(
originInput: string,
endpointPath: string,
): string | null {
if (
typeof originInput !== "string" ||
!/^\/[A-Za-z0-9._~!$&'()*+,;=:@%/-]*$/u.test(endpointPath)
) {
return null;
}
try {
const origin = new URL(originInput);
if (
origin.protocol !== "https:" ||
origin.username !== "" ||
origin.password !== "" ||
origin.search !== "" ||
origin.hash !== "" ||
origin.origin !== originInput.replace(/\/$/u, "") ||
endpointPath.includes("//")
) {
return null;
}
const endpoint = new URL(endpointPath, origin);
if (endpoint.origin !== origin.origin) return null;
endpoint.protocol = "wss:";
return endpoint.toString();
} catch {
return null;
}
}
function isUndefined(value: unknown): value is undefined {
return value === undefined;
}
function resolveCeilings(
reductions: Partial<WebSocketClientCeilings> | undefined,
): WebSocketClientCeilings {
const resolved = {
...WEBSOCKET_IMPLEMENTATION_CEILINGS,
...reductions,
};
const lowerBoundKeys = new Set<keyof WebSocketClientCeilings>([
"minHeartbeatMs",
"minHeartbeatAckTimeoutMs",
]);
for (const [key, hardLimit] of Object.entries(
WEBSOCKET_IMPLEMENTATION_CEILINGS,
) as [keyof WebSocketClientCeilings, number][]) {
const value = resolved[key];
if (
!Number.isSafeInteger(value) ||
value < 1 ||
(lowerBoundKeys.has(key)
? value < hardLimit
: value > hardLimit)
) {
throw new TypeError("WebSocket ceiling is invalid.");
}
}
if (
resolved.minHeartbeatMs > resolved.maxHeartbeatMs ||
resolved.minHeartbeatAckTimeoutMs >
resolved.maxHeartbeatAckTimeoutMs
) {
throw new TypeError("WebSocket heartbeat range is invalid.");
}
return Object.freeze(resolved);
}
function minLimits(
client: WebSocketClientCeilings,
server: WebSocketAdvertisedLimits,
): WebSocketAdvertisedLimits {
return Object.freeze({
maxFrameBytes: Math.min(
client.maxFrameBytes,
server.maxFrameBytes,
),
maxSubscriptions: Math.min(
client.maxSubscriptions,
server.maxSubscriptions,
),
maxInboundQueueCount: Math.min(
client.maxInboundQueueCount,
server.maxInboundQueueCount,
),
maxInboundQueueBytes: Math.min(
client.maxInboundQueueBytes,
server.maxInboundQueueBytes,
),
maxOutboundQueueCount: Math.min(
client.maxOutboundQueueCount,
server.maxOutboundQueueCount,
),
maxOutboundQueueBytes: Math.min(
client.maxOutboundQueueBytes,
server.maxOutboundQueueBytes,
),
maxBufferedAmountBytes: Math.min(
client.maxBufferedAmountBytes,
server.maxBufferedAmountBytes,
),
maxEventsPerSecond: Math.min(
client.maxEventsPerSecond,
server.maxEventsPerSecond,
),
});
}
function isSubscriptionRequest(
request: WebSocketSubscriptionRequest,
): boolean {
if (
!IDENTIFIER.test(request.subscriptionId) ||
!IDENTIFIER.test(request.streamId) ||
!OPAQUE_VALUE.test(request.scopeBinding) ||
typeof request.stateBearing !== "boolean"
) {
return false;
}
const checkpoint = request.checkpoint;
return (
checkpoint === undefined ||
(IDENTIFIER.test(checkpoint.streamEpoch) &&
nextUnsignedSequence(checkpoint.lastAppliedSequence) !== null &&
(checkpoint.cursor === null ||
OPAQUE_VALUE.test(checkpoint.cursor)))
);
}
function snapshotSubscriptionRequest(
request: WebSocketSubscriptionRequest,
): WebSocketSubscriptionRequest {
return Object.freeze({
subscriptionId: request.subscriptionId,
streamId: request.streamId,
scopeBinding: request.scopeBinding,
stateBearing: request.stateBearing,
...(request.checkpoint
? {
checkpoint: Object.freeze({
...request.checkpoint,
}),
}
: {}),
});
}
function eventData(event: unknown): unknown {
if (!event || typeof event !== "object") return undefined;
try {
return Reflect.get(event, "data");
} catch {
return undefined;
}
}
function verifyCursorRotation(
verify:
| WebSocketConnectionDependencies["verifyCursorRotation"]
| undefined,
requestedCursor: string,
acceptedCursor: string,
streamEpoch: string,
nextExpectedSequence: string,
): boolean {
try {
return (
verify?.(
Object.freeze({
requestedCursor,
acceptedCursor,
streamEpoch,
nextExpectedSequence,
}),
) === true
);
} catch {
return false;
}
}
function eventCode(event: unknown): number {
if (!event || typeof event !== "object") return 0;
try {
const code = Reflect.get(event, "code");
return Number.isSafeInteger(code) ? Number(code) : 0;
} catch {
return 0;
}
}
function mapNativeCloseCategory(
code: number,
): WebSocketCloseCategory {
switch (code) {
case 1_000:
return "NORMAL";
case 1_001:
case 1_012:
return "RESTART";
case 1_013:
return "OVERLOADED";
case 1_008:
case 4_403:
return "FORBIDDEN";
case 4_001:
return "AUTH_REQUIRED";
case 4_002:
return "CURSOR_RESET";
default:
return "NETWORK_LOST";
}
}
function closeFailure(
category: WebSocketCloseCategory,
): RealtimeFailure {
switch (category) {
case "NORMAL":
return failure("CLOSED", "CLOSE", false);
case "RESTART":
case "NETWORK_LOST":
return failure(
"PROVIDER_UNAVAILABLE",
"RECEIVE",
true,
);
case "OVERLOADED":
return failure(
"PROVIDER_UNAVAILABLE",
"RECEIVE",
false,
);
case "AUTH_REQUIRED":
return failure(
"AUTH_REQUIRED",
"RECEIVE",
false,
);
case "FORBIDDEN":
return failure(
"FORBIDDEN",
"RECEIVE",
false,
);
case "PROTOCOL_MISMATCH":
return failure(
"PROTOCOL_MISMATCH",
"RECEIVE",
false,
);
case "CURSOR_RESET":
return failure(
"CURSOR_EXPIRED",
"RECEIVE",
false,
);
}
}
function resetFailureCode(
reason:
| "CURSOR_EXPIRED"
| "SEQUENCE_GAP"
| "SERVER_RESET"
| "SCOPE_CHANGED",
): RealtimeFailureKind {
switch (reason) {
case "CURSOR_EXPIRED":
return "CURSOR_EXPIRED";
case "SEQUENCE_GAP":
return "SEQUENCE_GAP";
case "SERVER_RESET":
case "SCOPE_CHANGED":
return "PROTOCOL_MISMATCH";
}
}
function failure(
kind: RealtimeFailureKind,
operation: RealtimeOperation,
retryable: boolean,
): RealtimeFailure {
return realtimeFailure(kind, operation, retryable).error;
}
function connectionFailure(
kind: RealtimeFailureKind,
operation: RealtimeOperation,
retryable: boolean,
): Extract<RealtimeResult<never>, { ok: false }> {
return realtimeFailure(kind, operation, retryable);
}