Import packages/protocol/src/close-semantics.ts

This commit is contained in:
QQ 2026-11-14 15:03:54 +08:00
parent 5faf384b36
commit 534c9a3ac4
1 changed files with 114 additions and 0 deletions

View File

@ -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,
}
}