diff --git a/packages/protocol/src/close-semantics.ts b/packages/protocol/src/close-semantics.ts new file mode 100644 index 0000000..e6cd69a --- /dev/null +++ b/packages/protocol/src/close-semantics.ts @@ -0,0 +1,114 @@ +/** + * WebSocket close semantics for the control channel. + * + * Close codes are a *versioned transport detail*; the close reason is the + * capability-independent semantic key. Two different implementations disagree + * on the code today, so every endpoint must classify by (code, reason) pairs + * through this module instead of testing `event.code` on its own: + * + * - `apps/server` (self-hosted) sends `4009` / `server shutdown` on graceful + * shutdown (`SERVER_SHUTDOWN_CLOSE_CODE`). + * - The hosted Server's hub currently closes sockets with `4001` / + * `server shutdown` and reserves `4009` for heartbeat expiry + * (`heartbeat timeout`). `4001` is therefore accepted as a historical alias + * for the shutdown semantics; it still means timeout/auth failure for every + * other reason. + * - `1013` / `server shutdown` is the WebSocket "try again later" alias. + * + * Never derive session-retention from a bare code: `4009` alone is a + * heartbeat timeout on the hosted Server, and `4001` alone is also used for + * hello timeouts, heartbeat expiry and authorization failures. + */ + +/** Exact reason string that marks a Server-initiated, expected outage. */ +export const SERVER_SHUTDOWN_REASON = 'server shutdown' + +/** Close codes that may carry {@link SERVER_SHUTDOWN_REASON}. */ +export const SERVER_SHUTDOWN_CLOSE_CODES: readonly number[] = [4009, 4001, 1013] + +/** Hosted Server heartbeat expiry: the peer went away, not the Server. */ +export const HEARTBEAT_TIMEOUT_CLOSE_CODE = 4009 +export const HEARTBEAT_TIMEOUT_REASON = 'heartbeat timeout' + +/** `4001` with this reason is documented as a retryable heartbeat failure. */ +export const HEARTBEAT_CONNECTION_FAILED_REASON = 'CONNECTION_FAILED' + +/** + * Close codes where the control socket simply went away: a polite normal + * closure initiated by either side, an established connection that was never + * closed politely, a server that is going away, or a handshake that never + * completed. + */ +export const TRANSIENT_CONTROL_CLOSE_CODES: readonly number[] = [1000, 1001, 1006, 1011, 1012, 1013] + +function normalizeReason(reason: string | undefined | null): string { + return typeof reason === 'string' ? reason.trim() : '' +} + +/** + * True only for an intentional, expected Server outage. + * + * This is the gate for lease-backed session retention (keep authenticated + * data-plane state and recover the control channel in the background) and for + * spreading the first recovery attempt over a jitter window so a restarting + * Server does not receive the whole fleet at once. + */ +export function isServerShutdownClose(code: number, reason?: string | null): boolean { + return SERVER_SHUTDOWN_CLOSE_CODES.includes(code) + && normalizeReason(reason) === SERVER_SHUTDOWN_REASON +} + +/** + * True when the peer itself stopped answering (heartbeat expiry). + * + * This is indistinguishable from a network partition and must never be + * treated as a Server-restart signal. + */ +export function isHeartbeatTimeoutClose(code: number, reason?: string | null): boolean { + return (code === HEARTBEAT_TIMEOUT_CLOSE_CODE && normalizeReason(reason) === HEARTBEAT_TIMEOUT_REASON) + || (code === 4001 && normalizeReason(reason) === HEARTBEAT_CONNECTION_FAILED_REASON) +} + +/** + * Close codes that another instance replaced, revoked or otherwise terminated + * explicitly. Retrying these without user action cannot succeed. + */ +export const TERMINAL_CONTROL_CLOSE_CODES: readonly number[] = [4003, 4004] + +export interface ControlCloseClassification { + /** Expected Server outage; eligible for lease-backed retention. */ + serverShutdown: boolean + /** + * Peer heartbeat expiry. Retryable and safe to retain across (it is + * indistinguishable from a network partition), but it never means the + * Server restarted. + */ + heartbeatTimeout: boolean + /** Polite or transient close that may be retried. */ + retryable: boolean + /** Another instance took over this identity. */ + replaced: boolean +} + +/** + * One classifier shared by every endpoint (Host plugin, WebRTC transport, + * Relay transport, apps). + * + * `retryable` is deliberately *not* "every code except terminal auth": only + * the documented transient codes, the shutdown pair and the heartbeat pair + * qualify, so an unknown or new application close code is treated as terminal + * by the transport and never silently widens session retention. Whether an + * endpoint additionally retries the connection for an unknown code is a + * transport-policy decision made by that endpoint. + */ +export function classifyControlClose(code: number, reason?: string | null): ControlCloseClassification { + const serverShutdown = isServerShutdownClose(code, reason) + const heartbeatTimeout = isHeartbeatTimeoutClose(code, reason) + const replaced = code === 4003 + return { + serverShutdown, + heartbeatTimeout, + retryable: serverShutdown || heartbeatTimeout || TRANSIENT_CONTROL_CLOSE_CODES.includes(code), + replaced, + } +}