Import packages/protocol/src/close-semantics.ts
This commit is contained in:
parent
5faf384b36
commit
534c9a3ac4
|
|
@ -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,
|
||||
}
|
||||
}
|
||||
Loading…
Reference in New Issue