WebSocket Connection Drops

WebSocket connections can drop for many reasons (network, proxies, server restarts, client sleep). A resilient client and a resume-friendly server greatly improve UX. This page covers common causes, detection, reconnection strategies, resumption, buffering, and monitoring.

• Sudden disconnects with no error code or message.
• Repeated 1006 (abnormal closure) on browsers.
• Long pauses (silent period) followed by reconnection attempts.
• High reconnect churn (clients reconnecting in bursts after infra restart).

Use exponential backoff with jitter and a maximum cap. Avoid tight reconnect loops (thundering herd) and implement randomized jitter per client.

// Pseudo: reconnect with full jitter
let attempt = 0
const base = 500 // ms
const cap = 30000 // ms

function getBackoff() {
  const max = Math.min(cap, base * 2 ** attempt)
  // full jitter: uniform random between 0 and max
  return Math.floor(Math.random() * max)
}

async function tryConnect() {
  try {
    await ws.connect()
    attempt = 0
  } catch (err) {
    attempt++
    const wait = getBackoff()
    await sleep(wait)
    tryConnect()
  }
}

Add a maximum total retry window and surface a UI state (offline / reconnecting) if attempts exceed thresholds.

Heartbeats detect dead connections faster than TCP timeouts. Implement periodic ping/pong or application-level heartbeats.

// Client-side heartbeat (pseudo)
const HEARTBEAT_INTERVAL = 30000 // 30s
let hbTimer

function startHeartbeat() {
  hbTimer = setInterval(() => ws.send(JSON.stringify({ type: 'ping', ts: Date.now() })), HEARTBEAT_INTERVAL)
}

ws.onmessage = (msg) => {
  const data = JSON.parse(msg.data)
  if (data.type === 'pong') {
    // ok
  }
}

On the server, reply to pings quickly and close connections that miss N heartbeats to free resources.

To avoid data loss, support resumption: clients reconnect with a resume token or last-received sequence number and request missed messages. The server should be able to replay (or provide last N messages) for a short retention window.

// Reconnect payload (client)
{
  "type": "resume",
  "sessionId": "s_abc123",
  "lastSeq": 345
}

// Server reply: replay messages after seq 345, or request full state if gap too large
{
  "type": "resume_ack",
  "replayFrom": 346,
  "fallback": false
}

Replay window must be documented (e.g., last 5 minutes or last 10k messages). If gap is too large, require a full state sync.

Buffer outbound messages while disconnected and retry when reconnected. Ensure server-side operations are idempotent or require client-generated idempotency keys so retries don't cause duplicates.

// Outbound queue pseudo
const outQueue = []

function send(msg) {
  if (ws.readyState !== WebSocket.OPEN) {
    outQueue.push(msg)
    return
  }
  ws.send(JSON.stringify(msg))
}

ws.onopen = () => {
  while (outQueue.length) ws.send(JSON.stringify(outQueue.shift()))
}

• Use sticky sessions / consistent hashing if using multiple WebSocket workers behind a load balancer, or implement a shared session store for resumption.
• Configure proxy idle timeouts longer than your heartbeat interval (e.g., ALB idle timeout > 60s when using 30s heartbeats).
• Run health checks and drain connections gracefully before worker restarts; notify clients to reconnect with resume tokens if possible.

Track connection metrics and alert on anomalies:

• Active connections
• Disconnect rate (per minute)
• Reconnect attempts and backoff saturation
• Missed heartbeat count
• Replay/fallback occurrences (how often full state syncs are required)

Simulate network conditions (packet loss, latency, disconnects) and run chaos tests (restart workers, kill connections) to validate reconnection and resume flows.