WebSocket

How a WebSocket connection is established

The connection starts as an ordinary HTTP/1.1 request with two special headers:

GET /chat HTTP/1.1
Host: example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13

The server, if it supports WebSocket on this path, responds with:

HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

The Sec-WebSocket-Accept is the SHA-1 hash of the client's Sec-WebSocket-Key concatenated with a fixed string, base64-encoded. Crude but effective: it confirms the server actually understood the WebSocket protocol (rather than echoing back the key naively).

From that point forward, the same TCP connection switches from HTTP framing to WebSocket framing. Both sides can send messages whenever they want.

WebSocket vs alternatives

	WebSocket	HTTP polling	HTTP long-polling	Server-Sent Events	HTTP/2 push
Direction	Bidirectional	Client → Server	Client → Server	Server → Client only	Server → Client (mostly removed)
Latency (server→client)	Sub-millisecond	Polling interval (1s+)	Sub-second	Sub-millisecond	Sub-millisecond
Server resources per client	1 connection	1 conn per poll	1 long-held conn	1 long-held conn	Multiplexed on shared conn
Reconnection	Manual	Trivial (next poll)	Manual	Auto (built-in)	Built-in
Browser support	Excellent	Universal	Universal	Excellent (no IE)	Mostly removed
Best for	Chat, games, collaboration	Simple "any updates?" checks	Notifications when polling is too chatty	One-way feeds (news, stock prices)	Performance-only optimization

For a chat app, polling every second wastes bandwidth and adds 500ms average latency. WebSocket has near-zero latency and zero overhead per message. The trade-off is connection management — handling reconnects, scaling state across servers, dealing with idle connection timeouts.

When to use WebSocket

• Real-time chat and messaging. Slack, Discord, WhatsApp Web all use WebSocket (or socket.io, which falls back when needed). Sub-100ms message delivery is impossible with HTTP polling.
• Multiplayer games. Player position updates dozens of times per second from each player to all others. WebSocket's per-message overhead is the right cost for this rate.
• Collaborative editors. Google Docs, Figma, Notion — every keystroke from every user broadcasts to every other user. WebSocket plus operational transformation or CRDTs.
• Live dashboards. Trading prices, system metrics, score boards. Server pushes updates as they happen.
• IoT control. Bidirectional device-to-cloud communication where the cloud needs to send commands. MQTT is more common for IoT but WebSocket also works.

JavaScript: WebSocket client

const ws = new WebSocket('wss://example.com/chat');

ws.addEventListener('open', () => {
  console.log('connected');
  ws.send(JSON.stringify({ type: 'subscribe', channel: 'general' }));
});

ws.addEventListener('message', (e) => {
  const msg = JSON.parse(e.data);
  console.log('received:', msg);
});

ws.addEventListener('close', (e) => {
  console.log('closed', e.code, e.reason);
  // Reconnect with exponential backoff
  setTimeout(reconnect, getBackoff());
});

ws.addEventListener('error', (e) => {
  console.error('socket error', e);
});

// Send a message later
function sendChat(text) {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send(JSON.stringify({ type: 'chat', text }));
  } else {
    // Queue for after reconnect
    pendingMessages.push({ type: 'chat', text });
  }
}

Node.js: minimal echo WebSocket server

import { WebSocketServer } from 'ws';

const wss = new WebSocketServer({ port: 8080 });

wss.on('connection', (socket, req) => {
  console.log('client connected from', req.socket.remoteAddress);

  socket.on('message', (data) => {
    // Echo back to sender
    socket.send(data);

    // Broadcast to everyone else
    wss.clients.forEach((c) => {
      if (c !== socket && c.readyState === socket.OPEN) c.send(data);
    });
  });

  socket.on('close', () => console.log('client disconnected'));

  // Heartbeat to detect dead connections
  socket.isAlive = true;
  socket.on('pong', () => { socket.isAlive = true; });
});

// Periodically check for dead connections
setInterval(() => {
  wss.clients.forEach((s) => {
    if (!s.isAlive) return s.terminate();
    s.isAlive = false;
    s.ping();
  });
}, 30000);

Python: websockets library

import asyncio
import websockets

async def echo(websocket):
    async for message in websocket:
        await websocket.send(message)  # echo

async def main():
    async with websockets.serve(echo, 'localhost', 8080):
        await asyncio.Future()  # run forever

asyncio.run(main())

Reconnection with exponential backoff

WebSocket has no built-in reconnect. Implement it with exponential backoff and jitter:

class ReconnectingWebSocket {
  constructor(url) {
    this.url = url;
    this.attempts = 0;
    this.connect();
  }

  connect() {
    this.ws = new WebSocket(this.url);
    this.ws.addEventListener('open', () => { this.attempts = 0; });
    this.ws.addEventListener('close', () => this.scheduleReconnect());
    this.ws.addEventListener('error', () => this.ws.close());
  }

  scheduleReconnect() {
    const base = Math.min(1000 * 2 ** this.attempts, 30000); // cap at 30s
    const jitter = base * (0.9 + Math.random() * 0.2);        // ±10%
    this.attempts++;
    setTimeout(() => this.connect(), jitter);
  }

  send(data) {
    if (this.ws.readyState === WebSocket.OPEN) this.ws.send(data);
    // else: queue for after reconnect, application-specific
  }
}

Without jitter, all clients reconnect at the same instant after a server crash — a "thundering herd" that can DDoS your own service. The random ±10% spreads reconnect attempts across a window.

Scaling WebSocket servers

Each WebSocket holds an open TCP connection. Servers can typically handle 10K-100K concurrent connections per machine (kernel and tunable limit on file descriptors).

To scale beyond that, you need a horizontal-scaling pattern:

1. Pub/Sub backplane. Use Redis Pub/Sub, NATS, or Kafka. When server A receives a message that should go to a client on server B, A publishes to a channel; B's subscription delivers it to its connected client.
2. Sticky sessions. Load balancers route a client's reconnects to the same server. Avoids re-establishing per-server state.
3. Connection state externalized. Don't keep "user X is in channel Y" only in process memory; store it in Redis or similar so any server can answer.
4. Health checks. Old connections to dead servers must time out cleanly. TCP keepalive + WebSocket ping/pong every 30s.

Common WebSocket issues

• Idle connection timeouts. NAT devices, load balancers, and proxies often time out connections after ~5 minutes of inactivity. Send WebSocket ping frames every 30 seconds to keep the connection alive.
• Authentication after upgrade. The HTTP upgrade request can carry cookies or headers, but once the connection is open, those don't apply to messages. Validate auth tokens in your message handlers if authorization changes during the session.
• Backpressure when one client is slow. If a slow client can't drain messages fast enough, your send buffer fills up and the server runs out of memory. Apply per-client send queues with size limits; close clients that fall too far behind.
• Message ordering across reconnects. After a reconnect, missed messages are gone unless the server kept them. Use sequence numbers and let the client request "everything since seq N" on reconnect.
• Mixed-content blocks. An HTTPS page can't open a ws:// WebSocket — only wss://. Always use TLS in production.
• JSON parsing in hot path. Every message goes through JSON.parse. For high-throughput streams (60+ msgs/sec per client), consider binary framing (MessagePack, Protobuf) — 2-3× faster parsing and smaller payloads.