HTTP was designed for documents — a client requests a page, the server responds, and the connection closes. For 20 years, we've built workarounds for real-time communication on top of this request-response model: polling (make a request every second), long-polling (make a request and hold the connection open until data is available), and Server-Sent Events (one-way server-to-client streaming). Each has limitations: polling wastes bandwidth and adds latency, long-polling ties up server resources with idle connections, and SSE only supports server-to-client communication.
WebSockets solve these problems with a persistent, full-duplex connection between client and server. Once established, either side can send data at any time without the overhead of HTTP headers, connection negotiation, or polling intervals. The result: sub-100ms message delivery, minimal bandwidth usage, and truly bidirectional communication.
This guide covers everything you need to build production-grade real-time applications: the WebSocket protocol, server implementation, client handling, authentication, horizontal scaling, and the architectural patterns that work at scale.
Chapter 1: Understanding the WebSocket Protocol
The Handshake
WebSocket connections begin as HTTP requests. The client sends an HTTP upgrade request, and the server responds with a 101 Switching Protocols status. After the handshake, the TCP connection is repurposed for WebSocket communication — no more HTTP overhead.
// Client handshake request (sent by browser)
GET /ws HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: chat, superchat
Origin: https://example.com
// Server handshake response
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
Sec-WebSocket-Protocol: chat
// After this handshake, both sides communicate using WebSocket frames
// No more HTTP headers — just raw message data with minimal framingThe Sec-WebSocket-Key and Sec-WebSocket-Accept headers prevent cross-protocol attacks. The server concatenates the client's key with a fixed GUID, computes a SHA-1 hash, and returns it base64-encoded. This proves the server understands WebSocket protocol and isn't just an HTTP server blindly accepting connections.
Frame Format
After the handshake, data is transmitted in frames. Each frame has a minimal header (2-14 bytes depending on payload size) compared to HTTP headers (typically 200-800 bytes). This makes WebSockets extremely efficient for frequent small messages.
Frame types: text frames (UTF-8 encoded strings), binary frames (arbitrary binary data), ping frames (keepalive check — server sends, client automatically responds with pong), pong frames (response to ping), and close frames (graceful connection termination with a status code and optional reason).
When to Use WebSockets (and When Not To)
Use WebSockets for: Chat and messaging applications, live notifications, collaborative editing (Google Docs, Figma), live dashboards and monitoring, multiplayer games, financial trading platforms (real-time price feeds), live sports scores, IoT device communication, and any use case where the server needs to push data to the client without being asked.
Don't use WebSockets for: Standard CRUD operations (use REST), file uploads (use HTTP with progress events), one-time data fetches (use HTTP), server-to-client only streaming (use Server-Sent Events — simpler and auto-reconnects), and applications where eventual consistency with 1-5 second delays is acceptable (use polling).
Chapter 2: Server Implementation with Node.js
Raw WebSocket Server
The ws library is the most popular WebSocket implementation for Node.js. It's lightweight, fast, and protocol-compliant.
import { WebSocketServer, WebSocket } from 'ws';
import { createServer } from 'http';
import { parse } from 'url';
const server = createServer();
const wss = new WebSocketServer({ noServer: true });
// Connection map: track all connected clients
interface Client {
ws: WebSocket;
userId: string;
rooms: Set<string>;
isAlive: boolean;
connectedAt: Date;
}
const clients = new Map<string, Client>();
// Handle upgrade request (authentication happens here)
server.on('upgrade', async (request, socket, head) => {
try {
// Authenticate the connection
const { query } = parse(request.url || '', true);
const token = query.token as string;
if (!token) {
socket.write('HTTP/1.1 401 Unauthorized\r\n\r\n');
socket.destroy();
return;
}
const user = await verifyToken(token);
if (!user) {
socket.write('HTTP/1.1 403 Forbidden\r\n\r\n');
socket.destroy();
return;
}
// Complete the WebSocket handshake
wss.handleUpgrade(request, socket, head, (ws) => {
wss.emit('connection', ws, request, user);
});
} catch (error) {
console.error('Upgrade error:', error);
socket.write('HTTP/1.1 500 Internal Server Error\r\n\r\n');
socket.destroy();
}
});
// Handle new connections
wss.on('connection', (ws: WebSocket, request: any, user: any) => {
const clientId = generateId();
const client: Client = {
ws,
userId: user.id,
rooms: new Set(['global']),
isAlive: true,
connectedAt: new Date(),
};
clients.set(clientId, client);
console.log(
'Client connected:',
clientId,
'User:', user.id,
'Total:', clients.size
);
// Send welcome message
send(ws, {
type: 'connected',
clientId,
serverTime: Date.now(),
});
// Handle incoming messages
ws.on('message', (data: Buffer) => {
try {
const message = JSON.parse(data.toString());
handleMessage(clientId, client, message);
} catch (error) {
send(ws, { type: 'error', message: 'Invalid message format' });
}
});
// Handle pong (heartbeat response)
ws.on('pong', () => {
client.isAlive = true;
});
// Handle disconnection
ws.on('close', (code: number, reason: Buffer) => {
console.log(
'Client disconnected:',
clientId,
'Code:', code,
'Reason:', reason.toString()
);
clients.delete(clientId);
// Notify other clients in shared rooms
broadcastToRooms(client.rooms, {
type: 'user_left',
userId: client.userId,
}, clientId);
});
// Handle errors
ws.on('error', (error: Error) => {
console.error('WebSocket error:', clientId, error.message);
});
});
// Message handler
function handleMessage(clientId: string, client: Client, message: any) {
switch (message.type) {
case 'chat':
// Broadcast to room
broadcastToRoom(message.room || 'global', {
type: 'chat',
userId: client.userId,
content: message.content,
timestamp: Date.now(),
}, clientId);
break;
case 'join_room':
client.rooms.add(message.room);
send(client.ws, {
type: 'room_joined',
room: message.room,
});
break;
case 'leave_room':
client.rooms.delete(message.room);
send(client.ws, {
type: 'room_left',
room: message.room,
});
break;
case 'typing':
broadcastToRoom(message.room || 'global', {
type: 'user_typing',
userId: client.userId,
}, clientId);
break;
default:
send(client.ws, {
type: 'error',
message: 'Unknown message type: ' + message.type,
});
}
}
// Utility functions
function send(ws: WebSocket, data: any) {
if (ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify(data));
}
}
function broadcastToRoom(
room: string, data: any, excludeClientId?: string
) {
clients.forEach((client, id) => {
if (id !== excludeClientId && client.rooms.has(room)) {
send(client.ws, data);
}
});
}
function broadcastToRooms(
rooms: Set<string>, data: any, excludeClientId?: string
) {
rooms.forEach(room => broadcastToRoom(room, data, excludeClientId));
}
function generateId(): string {
return Math.random().toString(36).substring(2, 15);
}
server.listen(8080, () => {
console.log('WebSocket server running on port 8080');
});Chapter 3: Heartbeats and Connection Health
WebSocket connections can silently die. The TCP connection might be terminated by a firewall, load balancer, or NAT gateway without either side knowing. Without heartbeats, the server holds dead connections indefinitely, wasting memory and distorting active user counts.
Server-Side Heartbeat
// Ping every client every 30 seconds
// If a client doesn't respond with pong within 30 seconds,
// terminate the connection
const HEARTBEAT_INTERVAL = 30000; // 30 seconds
const heartbeatInterval = setInterval(() => {
clients.forEach((client, id) => {
if (!client.isAlive) {
// Client didn't respond to last ping — terminate
console.log('Terminating dead connection:', id);
client.ws.terminate();
clients.delete(id);
return;
}
// Mark as not alive, send ping
// If client responds with pong, isAlive is set back to true
client.isAlive = false;
client.ws.ping();
});
}, HEARTBEAT_INTERVAL);
// Clean up on server shutdown
wss.on('close', () => {
clearInterval(heartbeatInterval);
});Client-Side Heartbeat and Reconnection
The client should also implement heartbeats and automatic reconnection. When the connection drops, the client should reconnect with exponential backoff to avoid overwhelming the server during outages.
// Robust WebSocket client with reconnection
class WebSocketClient {
private ws: WebSocket | null = null;
private url: string;
private token: string;
private reconnectAttempts = 0;
private maxReconnectAttempts = 10;
private baseReconnectDelay = 1000; // 1 second
private maxReconnectDelay = 30000; // 30 seconds
private heartbeatInterval: ReturnType<typeof setInterval> | null = null;
private messageQueue: any[] = [];
private listeners = new Map<string, Set<Function>>();
constructor(url: string, token: string) {
this.url = url;
this.token = token;
}
connect() {
try {
this.ws = new WebSocket(this.url + '?token=' + this.token);
this.ws.onopen = () => {
console.log('WebSocket connected');
this.reconnectAttempts = 0;
this.startHeartbeat();
this.flushMessageQueue();
this.emit('connected', null);
};
this.ws.onmessage = (event: MessageEvent) => {
try {
const data = JSON.parse(event.data);
this.emit(data.type, data);
this.emit('message', data);
} catch (error) {
console.error('Failed to parse message:', error);
}
};
this.ws.onclose = (event: CloseEvent) => {
console.log('WebSocket closed:', event.code, event.reason);
this.stopHeartbeat();
// Don't reconnect if closed intentionally (code 1000)
// or if server rejected the connection (4xxx codes)
if (event.code === 1000 || event.code >= 4000) {
this.emit('disconnected', { permanent: true });
return;
}
this.emit('disconnected', { permanent: false });
this.scheduleReconnect();
};
this.ws.onerror = (error: Event) => {
console.error('WebSocket error:', error);
};
} catch (error) {
console.error('Connection failed:', error);
this.scheduleReconnect();
}
}
private scheduleReconnect() {
if (this.reconnectAttempts >= this.maxReconnectAttempts) {
console.error('Max reconnect attempts reached');
this.emit('reconnect_failed', null);
return;
}
// Exponential backoff with jitter
const delay = Math.min(
this.baseReconnectDelay *
Math.pow(2, this.reconnectAttempts) *
(0.5 + Math.random() * 0.5),
this.maxReconnectDelay
);
this.reconnectAttempts++;
console.log(
'Reconnecting in ' + Math.round(delay) + 'ms' +
' (attempt ' + this.reconnectAttempts + '/' +
this.maxReconnectAttempts + ')'
);
setTimeout(() => this.connect(), delay);
}
private startHeartbeat() {
this.heartbeatInterval = setInterval(() => {
if (this.ws?.readyState === WebSocket.OPEN) {
this.send({ type: 'ping' });
}
}, 25000); // 25 seconds (before server's 30s timeout)
}
private stopHeartbeat() {
if (this.heartbeatInterval) {
clearInterval(this.heartbeatInterval);
this.heartbeatInterval = null;
}
}
send(data: any) {
if (this.ws?.readyState === WebSocket.OPEN) {
this.ws.send(JSON.stringify(data));
} else {
// Queue messages while disconnected
this.messageQueue.push(data);
}
}
private flushMessageQueue() {
while (this.messageQueue.length > 0) {
const msg = this.messageQueue.shift();
this.send(msg);
}
}
on(event: string, callback: Function) {
if (!this.listeners.has(event)) {
this.listeners.set(event, new Set());
}
this.listeners.get(event)!.add(callback);
}
off(event: string, callback: Function) {
this.listeners.get(event)?.delete(callback);
}
private emit(event: string, data: any) {
this.listeners.get(event)?.forEach(cb => cb(data));
}
disconnect() {
this.maxReconnectAttempts = 0; // Prevent reconnection
this.stopHeartbeat();
this.ws?.close(1000, 'Client disconnecting');
}
}
// Usage
const client = new WebSocketClient('wss://api.example.com/ws', authToken);
client.on('connected', () => {
console.log('Connected!');
client.send({ type: 'join_room', room: 'support-chat' });
});
client.on('chat', (data: any) => {
console.log('New message:', data.content);
displayMessage(data);
});
client.on('disconnected', (info: any) => {
if (info.permanent) {
showReloginPrompt();
} else {
showReconnectingIndicator();
}
});
client.connect();Chapter 4: Authentication and Authorization
WebSocket connections don't support custom headers in the browser (the WebSocket API only allows the Sec-WebSocket-Protocol header). This means you can't send an Authorization header like you would with HTTP requests. Common authentication strategies:
Token in Query String
The simplest approach: pass the authentication token as a query parameter. The server validates the token during the HTTP upgrade handshake before establishing the WebSocket connection.
Concern: the token appears in server access logs and might be cached by intermediate proxies. Mitigation: use short-lived tokens (5-minute expiry) generated specifically for WebSocket connections. The client obtains the token via an authenticated HTTP endpoint, then uses it to connect the WebSocket.
Cookie-Based Authentication
If your application uses cookie-based sessions, the browser automatically includes cookies in the WebSocket handshake request. The server validates the session cookie during the upgrade. This is the simplest approach for applications that already use cookie authentication.
Two-Step Authentication
The most secure approach: the client connects the WebSocket without authentication, then sends an authentication message as the first message. The server validates the credentials and either upgrades the connection to "authenticated" or closes it with a 4001 custom close code.
// Server-side two-step authentication
wss.on('connection', (ws: WebSocket) => {
let authenticated = false;
let userId: string | null = null;
// Set a timeout — client must authenticate within 5 seconds
const authTimeout = setTimeout(() => {
if (!authenticated) {
ws.close(4001, 'Authentication timeout');
}
}, 5000);
ws.on('message', (data: Buffer) => {
const message = JSON.parse(data.toString());
if (!authenticated) {
// First message must be authentication
if (message.type !== 'authenticate') {
ws.close(4002, 'First message must be authentication');
return;
}
const user = verifyToken(message.token);
if (!user) {
ws.close(4003, 'Invalid credentials');
return;
}
authenticated = true;
userId = user.id;
clearTimeout(authTimeout);
send(ws, { type: 'authenticated', userId: user.id });
return;
}
// Handle normal messages (only after authentication)
handleMessage(userId!, message);
});
});Chapter 5: Horizontal Scaling with Redis Pub/Sub
A single WebSocket server can handle 10,000-100,000 concurrent connections depending on hardware and message volume. When you need more, you scale horizontally — run multiple WebSocket server instances behind a load balancer.
The challenge: WebSocket connections are stateful. If User A is connected to Server 1 and User B is connected to Server 2, a message from User A needs to reach User B across servers. The solution: use Redis Pub/Sub (or NATS, or Kafka) as a message bus between server instances.
import { createClient } from 'redis';
// Each server instance subscribes to Redis channels
// and publishes messages to Redis instead of broadcasting locally
const redisPub = createClient({ url: process.env.REDIS_URL });
const redisSub = createClient({ url: process.env.REDIS_URL });
await redisPub.connect();
await redisSub.connect();
// Subscribe to room channels
async function joinRoom(room: string) {
await redisSub.subscribe('room:' + room, (message) => {
const data = JSON.parse(message);
// Broadcast to local clients in this room
broadcastToLocalRoom(room, data, data._excludeClientId);
});
}
// Publish messages through Redis (reaches all server instances)
async function publishToRoom(
room: string, data: any, excludeClientId?: string
) {
await redisPub.publish('room:' + room, JSON.stringify({
...data,
_excludeClientId: excludeClientId,
}));
}
// Modified message handler — publish to Redis instead of local broadcast
function handleChatMessage(
clientId: string, client: Client, message: any
) {
publishToRoom(message.room || 'global', {
type: 'chat',
userId: client.userId,
content: message.content,
timestamp: Date.now(),
}, clientId);
}
// Track connected users across instances using Redis Sets
async function trackUserConnection(userId: string, serverId: string) {
await redisPub.sAdd('online_users', userId);
await redisPub.sAdd('server:' + serverId + ':users', userId);
// Set expiry for cleanup if server crashes
await redisPub.expire('server:' + serverId + ':users', 120);
}
async function getOnlineUsers(): Promise<string[]> {
return redisPub.sMembers('online_users');
}
async function getOnlineUserCount(): Promise<number> {
return redisPub.sCard('online_users');
}Load Balancer Configuration
WebSocket connections require sticky sessions (session affinity) at the load balancer level. Once a WebSocket connection is established with Server 1, all subsequent frames must go to Server 1 — they can't be round-robined to different servers.
# Nginx configuration for WebSocket load balancing
upstream websocket_servers {
# Use IP hash for sticky sessions
ip_hash;
server ws1.internal:8080;
server ws2.internal:8080;
server ws3.internal:8080;
}
server {
listen 443 ssl;
server_name ws.example.com;
ssl_certificate /etc/ssl/certs/example.com.pem;
ssl_certificate_key /etc/ssl/private/example.com.key;
location /ws {
proxy_pass http://websocket_servers;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# Timeout for idle WebSocket connections
# Must be longer than heartbeat interval
proxy_read_timeout 120s;
proxy_send_timeout 120s;
# Buffer settings
proxy_buffering off;
proxy_cache off;
}
}Chapter 6: Message Protocol Design
Design your message protocol carefully — it's the contract between client and server. A good protocol is: typed (every message has a type field), versioned (protocol version in the handshake), validated (server validates every message before processing), and documented (every message type is documented with its fields).
// Message protocol definition
interface BaseMessage {
type: string;
id?: string; // Optional message ID for acknowledgment
timestamp?: number;
}
// Client -> Server messages
interface JoinRoomMessage extends BaseMessage {
type: 'join_room';
room: string;
}
interface LeaveRoomMessage extends BaseMessage {
type: 'leave_room';
room: string;
}
interface ChatMessage extends BaseMessage {
type: 'chat';
room: string;
content: string;
replyTo?: string; // Optional reply to message ID
}
interface TypingMessage extends BaseMessage {
type: 'typing';
room: string;
isTyping: boolean;
}
// Server -> Client messages
interface ChatBroadcast extends BaseMessage {
type: 'chat';
room: string;
userId: string;
userName: string;
content: string;
messageId: string;
timestamp: number;
}
interface PresenceUpdate extends BaseMessage {
type: 'presence';
room: string;
onlineUsers: string[];
userJoined?: string;
userLeft?: string;
}
interface ErrorMessage extends BaseMessage {
type: 'error';
code: string;
message: string;
}
interface AckMessage extends BaseMessage {
type: 'ack';
messageId: string; // ID of the acknowledged message
status: 'delivered' | 'read';
}Message Acknowledgment
For applications where message delivery is critical (chat, notifications), implement acknowledgment. The server sends an ack message for every received message, and the client retries messages that aren't acknowledged within a timeout.
Rate Limiting
Without rate limiting, a single malicious client can flood your server with messages, consuming resources and potentially causing a denial-of-service. Implement per-connection rate limiting:
// Simple sliding window rate limiter for WebSocket messages
class MessageRateLimiter {
private windows = new Map<string, number[]>();
private maxMessages: number;
private windowSize: number; // milliseconds
constructor(maxMessages: number, windowSizeMs: number) {
this.maxMessages = maxMessages;
this.windowSize = windowSizeMs;
}
isAllowed(clientId: string): boolean {
const now = Date.now();
const timestamps = this.windows.get(clientId) || [];
// Remove timestamps outside the window
const filtered = timestamps.filter(t => now - t < this.windowSize);
if (filtered.length >= this.maxMessages) {
this.windows.set(clientId, filtered);
return false;
}
filtered.push(now);
this.windows.set(clientId, filtered);
return true;
}
cleanup() {
const now = Date.now();
this.windows.forEach((timestamps, clientId) => {
const filtered = timestamps.filter(t => now - t < this.windowSize);
if (filtered.length === 0) {
this.windows.delete(clientId);
} else {
this.windows.set(clientId, filtered);
}
});
}
}
// Allow 50 messages per 10 seconds per client
const rateLimiter = new MessageRateLimiter(50, 10000);
// In message handler
ws.on('message', (data: Buffer) => {
if (!rateLimiter.isAllowed(clientId)) {
send(ws, {
type: 'error',
code: 'RATE_LIMITED',
message: 'Too many messages. Please slow down.',
});
return;
}
// Process message normally
handleMessage(clientId, client, JSON.parse(data.toString()));
});Chapter 7: Production Deployment Patterns
Connection Limits and Backpressure
Every WebSocket connection consumes server memory (typically 10-50KB per connection depending on your application). Set a maximum connection limit per server instance and reject new connections gracefully when the limit is reached:
const MAX_CONNECTIONS = 50000;
server.on('upgrade', (request, socket, head) => {
if (clients.size >= MAX_CONNECTIONS) {
socket.write('HTTP/1.1 503 Service Unavailable\r\n');
socket.write('Retry-After: 30\r\n');
socket.write('\r\n');
socket.destroy();
return;
}
// Continue with normal upgrade
});Graceful Shutdown
When deploying a new version, you need to gracefully drain existing connections. The process: stop accepting new connections, send a "reconnect" message to all connected clients, wait for clients to disconnect (with a timeout), and then shut down the server.
// Graceful shutdown handler
process.on('SIGTERM', async () => {
console.log('SIGTERM received, starting graceful shutdown...');
// 1. Stop accepting new connections
server.close();
// 2. Notify all clients to reconnect
// (they'll connect to the new server instance)
clients.forEach((client) => {
send(client.ws, {
type: 'reconnect',
reason: 'server_restart',
delay: Math.random() * 5000, // Stagger reconnections
});
});
// 3. Wait for clients to disconnect (max 30 seconds)
const drainTimeout = setTimeout(() => {
console.log('Drain timeout, forcibly closing remaining connections');
clients.forEach((client) => {
client.ws.terminate();
});
}, 30000);
// 4. Check periodically if all clients have disconnected
const checkInterval = setInterval(() => {
if (clients.size === 0) {
console.log('All clients disconnected, shutting down');
clearInterval(checkInterval);
clearTimeout(drainTimeout);
process.exit(0);
}
}, 1000);
});Monitoring WebSocket Applications
Key metrics to monitor: total active connections (gauge), connections per second (rate), messages sent/received per second (rate), message latency (p50, p95, p99), connection duration distribution, error rate by type (connection failures, message parse errors, rate limit hits), memory usage per connection, and Redis pub/sub lag (for multi-instance setups).
Essential alerts: active connections approaching server limit (warning at 80%, critical at 95%), message latency p95 exceeding threshold (e.g., 500ms), connection error rate exceeding threshold (e.g., 5%), Redis pub/sub connection lost, and memory usage exceeding limits.
Chapter 8: Common Architectural Patterns
Chat Application
Rooms (channels), message history (store in database, serve via HTTP on room join), read receipts (ack messages with "read" status), typing indicators (throttled to once per 3 seconds), presence (online/offline status via heartbeats), and message threading (reply-to references).
Live Dashboard
Server pushes metric updates at fixed intervals (e.g., every second). Client subscribes to specific metric streams. Use binary frames for high-frequency numeric data to minimize bandwidth. Implement backpressure — if the client can't process messages fast enough, buffer server-side and send aggregated updates.
Collaborative Editing
The most complex real-time pattern. Requires operational transformation (OT) or conflict-free replicated data types (CRDTs) to handle concurrent edits without conflicts. Every keystroke generates an operation that's broadcast to all collaborators and applied in a consistent order. Libraries like Yjs and Automerge provide CRDT implementations that handle the conflict resolution automatically.
Notification System
Server pushes notifications to specific users (not broadcast). Store notifications in a database for persistence. Mark notifications as read via HTTP API. Use WebSocket only for real-time delivery — if the user is offline, they'll see notifications when they next load the page (fetched via HTTP).
WebSockets are a powerful tool for real-time communication, but they add operational complexity compared to HTTP. Use them when you genuinely need real-time, bidirectional communication — and use the simpler alternatives (polling, SSE) when they're sufficient.
ZeonEdge builds production-grade real-time applications using WebSockets, from live chat and collaboration tools to real-time dashboards and notification systems. Contact us to discuss your real-time application needs.
Priya Sharma
Full-Stack Developer and open-source contributor with a passion for performance and developer experience.