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>
1884 lines
48 KiB
TypeScript
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);
|
|
}
|