WebSockets, Server-Sent Events (SSE) & Real-Time Web Architecture Runbook

# Standard RFC 6455 WebSocket Upgrade Handshake
GET /realtime/v1/feed?token=jwt_eyJh... HTTP/1.1
Host: api.mayonlinetools.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: https://mayonlinetools.com

The Sec-WebSocket-Key is a 16-byte random base64 nonce that prevents caching proxies from misinterpreting the upgrade request as a standard cached GET.

# Server acknowledges upgrade and computes SHA-1 hash with standard GUID
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=

Sec-WebSocket-Accept is computed by concatenating Sec-WebSocket-Key with standard GUID "258EAFA5-E914-47DA-95CA-C5AB0DC85B11" and calculating the SHA-1 digest.

# Server response header must be text/event-stream with no buffering
HTTP/1.1 200 OK
Content-Type: text/event-stream; charset=utf-8
Cache-Control: no-cache, no-transform
Connection: keep-alive
X-Accel-Buffering: no

# Heartbeat comment to keep intermediate proxies and firewalls alive
: ping

id: evt_109283
event: order_update
retry: 5000
data: {"orderId": "ORD-941", "status": "shipped", "lat": 52.3676, "lng": 4.9041}

Lines beginning with a colon (:) are treated as comments. The retry directive instructs the browser to wait 5000ms before reconnecting if the TCP socket disconnects.

// Resilient client-side SSE consumer with custom event listeners
const evtSource = new EventSource('/api/v1/stream?channel=telemetry', {
  withCredentials: true
});

evtSource.addEventListener('order_update', (event: MessageEvent) => {
  const payload = JSON.parse(event.data);
  console.log('Order status changed:', payload, 'Last Event ID:', event.lastEventId);
});

evtSource.onerror = (err) => {
  if (evtSource.readyState === EventSource.CLOSED) {
    console.warn('SSE stream closed by server.');
  } else {
    console.info('SSE socket dropped; native browser engine is auto-reconnecting...');
  }
};

When reconnecting after an outage, the browser automatically injects the Last-Event-ID header containing the last received id value, allowing zero-loss state recovery.

# Choose Server-Sent Events (SSE) when:
# 1. Traffic is primarily unidirectional (server-to-client: stock ticks, LLM token streaming, notifications).
# 2. You operate behind corporate firewalls or Cloudflare proxies that restrict non-standard ports.
# 3. HTTP/2 or HTTP/3 multiplexing and native browser reconnection are prioritized.

# Choose WebSockets (WSS) when:
# 1. Low-latency bidirectional communication is mandatory (gaming, voice signaling, live canvas).
# 2. Message frequency exceeds 50 messages/second in both directions.
# 3. Binary serialization (Protobuf, MessagePack, ArrayBuffer) is required to save CPU and bandwidth.

SSE leverages existing HTTP infrastructure including caching, compression, and enterprise authentication middleware, while WebSockets bypass the HTTP layer entirely.

export class ResilientWebSocket {
  private ws: WebSocket | null = null;
  private attempt = 0;
  private readonly maxDelay = 30000; // Cap at 30 seconds
  private readonly baseDelay = 1000; // Start at 1 second
  private heartbeatTimer: number | null = null;
  private missedPings = 0;

  constructor(private url: string, private onMessage: (data: string) => void) {
    this.connect();
  }

  private connect(): void {
    this.ws = new WebSocket(this.url);

    this.ws.onopen = () => {
      this.attempt = 0;
      this.missedPings = 0;
      this.startHeartbeat();
      console.log('Real-time connection established.');
    };

    this.ws.onmessage = (event) => {
      if (event.data === 'pong') {
        this.missedPings = 0;
        return;
      }
      this.onMessage(event.data);
    };

    this.ws.onclose = () => {
      this.cleanup();
      this.scheduleReconnect();
    };

    this.ws.onerror = (err) => {
      console.error('WebSocket transport error:', err);
      this.ws?.close();
    };
  }

  private scheduleReconnect(): void {
    this.attempt++;
    // Exponential backoff: min(maxDelay, baseDelay * 2^attempt)
    const exponential = Math.min(this.maxDelay, this.baseDelay * Math.pow(2, this.attempt));
    // Full Jitter: uniform random value between 0 and exponential
    const delay = Math.floor(Math.random() * exponential);

    console.info(`Reconnecting in ${delay}ms (attempt ${this.attempt})...`);
    setTimeout(() => this.connect(), delay);
  }

  private startHeartbeat(): void {
    this.heartbeatTimer = window.setInterval(() => {
      if (!this.ws || this.ws.readyState !== WebSocket.OPEN) return;
      if (this.missedPings >= 2) {
        console.warn('Heartbeat missed 2 pongs; terminating dead half-open socket.');
        this.ws.close();
        return;
      }
      this.missedPings++;
      this.ws.send('ping');
    }, 15000); // 15-second probe
  }

  private cleanup(): void {
    if (this.heartbeatTimer) clearInterval(this.heartbeatTimer);
    this.ws = null;
  }
}

Full jitter ensures client reconnection spikes are spread evenly across a time window, preventing cascading overload on backend socket gateways.

import { createServer } from 'http';
import { WebSocketServer, WebSocket } from 'ws';
import { createClient } from 'redis';

const server = createServer();
const wss = new WebSocketServer({ server });
const pubClient = createClient({ url: process.env.REDIS_URL });
const subClient = pubClient.duplicate();

await Promise.all([pubClient.connect(), subClient.connect()]);

// Subscribe to global cluster channel
await subClient.subscribe('cluster:broadcast', (message) => {
  // Fan out message to all local sockets connected to this server instance
  for (const client of wss.clients) {
    if (client.readyState === WebSocket.OPEN) {
      client.send(message);
    }
  }
});

wss.on('connection', (socket) => {
  socket.on('message', async (data) => {
    // Publish message to Redis backplane; all cluster instances will receive it
    await pubClient.publish('cluster:broadcast', data.toString());
  });
});

server.listen(8080);

Using Redis as a cluster backplane allows you to horizontally scale socket server containers behind a standard Layer 4 (TCP) or Layer 7 load balancer without sticky sessions.