115 lines
4.8 KiB
TypeScript
115 lines
4.8 KiB
TypeScript
/**
|
|
* 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,
|
|
}
|
|
}
|