real-time-communication-patterns

Real-Time Communication Patterns

Overview

Real-time communication introduces connection lifecycle complexity, horizontal scaling challenges, and security risks that request/response APIs avoid entirely. A single unbounded connection pool, missing heartbeat, or JWT exposed in a query string can bring down production systems.

When to use: Designing live dashboards, chat, collaborative editing, notifications, streaming APIs, IoT device feeds, or any feature where the server must push data to clients unprompted.

Quick Reference

Protocol	Direction	Reconnect	Scaling	Best For
WebSocket	Full-duplex	Manual	Redis Pub/Sub or sticky sessions	Chat, games, collaborative editing
Server-Sent Events (SSE)	Server → client	Auto (EventSource)	Standard HTTP load balancer	Notifications, live feeds, dashboards
Long Polling	Server → client	Per-request	Standard HTTP load balancer	Legacy clients, firewall-constrained envs
gRPC Streaming	Full-duplex	Manual	L7 load balancer (Envoy)	Microservice-to-microservice real-time

---

Patterns in Detail

1. WebSocket Lifecycle

A WebSocket connection passes through distinct phases: HTTP upgrade handshake, open/connected, heartbeat keep-alive, graceful close, and reconnection with backoff.

Red Flags:

• No heartbeat — idle connections silently dropped by load balancers or NAT devices
• No reconnection logic — network blips kill the session permanently
• Sending frames after close — race condition on the write path
• Missing onclose / onerror handlers — uncaught errors crash the page or goroutine

TypeScript — client lifecycle with reconnect:

interface WsOptions {
  url: string;
  heartbeatIntervalMs?: number;
  maxReconnectDelayMs?: number;
  onMessage: (data: unknown) => void;
}

class ManagedWebSocket {
  private ws: WebSocket | null = null;
  private heartbeatTimer: ReturnType<typeof setInterval> | null = null;
  private reconnectDelay = 1_000;

  constructor(private readonly opts: WsOptions) {
    this.connect();
  }

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

    this.ws.onopen = () => {
      this.reconnectDelay = 1_000; // reset on successful connect
      this.startHeartbeat();
    };

    this.ws.onmessage = (event) => {
      const msg = JSON.parse(event.data as string) as { type: string; payload: unknown };
      if (msg.type === 'pong') return; // heartbeat response — ignore
      this.opts.onMessage(msg.payload);
    };

    this.ws.onclose = (event) => {
      this.stopHeartbeat();
      if (!event.wasClean) this.scheduleReconnect();
    };

    this.ws.onerror = (err) => {
      console.error('[WS] error', err);
      this.ws?.close();
    };
  }

  private startHeartbeat(): void {
    const interval = this.opts.heartbeatIntervalMs ?? 25_000;
    this.heartbeatTimer = setInterval(() => {
      if (this.ws?.readyState === WebSocket.OPEN) {
        this.ws.send(JSON.stringify({ type: 'ping' }));
      }
    }, interval);
  }

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

  private scheduleReconnect(): void {
    const maxDelay = this.opts.maxReconnectDelayMs ?? 30_000;
    const jitter = Math.random() * 1_000;
    const delay = Math.min(this.reconnectDelay + jitter, maxDelay);
    this.reconnectDelay = Math.min(this.reconnectDelay * 2, maxDelay);
    setTimeout(() => this.connect(), delay);
  }

  send(payload: unknown): void {
    if (this.ws?.readyState === WebSocket.OPEN) {
      this.ws.send(JSON.stringify(payload));
    }
  }

  close(): void {
    this.stopHeartbeat();
    this.ws?.close(1000, 'Client closing gracefully');
  }
}