System Design (HLD)WebSockets

WebSockets: Real-Time Bidirectional Communication

LevelIntermediate

Duration75 mins

TopicWebSockets

2 / 5

WebSocket Lifecycle

The Complete Journey of a WebSocket Connection

Every WebSocket connection tells a story with a beginning, middle, and end. Unlike HTTP's stateless transactions that complete in milliseconds, a WebSocket connection can persist for hours or even days, requiring careful management at each stage of its lifecycle.

Understanding this lifecycle isn't just academic—it's essential for building reliable real-time applications. Connection failures happen. Networks are unreliable. Servers restart. Clients lose connectivity. A robust WebSocket implementation anticipates these realities and handles them gracefully.

The WebSocket lifecycle comprises four distinct phases:

Opening Handshake — The HTTP upgrade process that establishes the connection
Open State — The active phase where bidirectional data exchange occurs
Closing Handshake — The graceful termination protocol
Closed State — Connection terminated; resources released

Each phase has its own mechanics, potential failure modes, and best practices. This page provides the comprehensive understanding needed to implement production-grade WebSocket systems.

What You Will Learn

By the end of this page, you will understand the complete WebSocket lifecycle including the opening handshake mechanism, connection states, the ping/pong keepalive protocol, graceful closure procedures, error handling patterns, and reconnection strategies that production applications require.

The Opening Handshake

The WebSocket lifecycle begins with the opening handshake, a carefully choreographed exchange that transforms an HTTP connection into a WebSocket connection. This handshake serves multiple purposes:

Protocol negotiation — Both parties agree to switch from HTTP to WebSocket protocol
Security validation — The server can verify the client's identity and origin
Subprotocol negotiation — Optional application-level protocol selection
Extension negotiation — Optional features like compression

The handshake is designed to work with existing HTTP infrastructure, ensuring WebSocket connections can traverse proxies, load balancers, and firewalls that understand HTTP but might block unknown protocols.

Complete Opening Handshake
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// ═══════════════════════════════════════════════════════════════
// CLIENT OPENING HANDSHAKE REQUEST
// ═══════════════════════════════════════════════════════════════
 
GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: chat, superchat       // Optional: subprotocol preferences
Sec-WebSocket-Extensions: permessage-deflate  // Optional: compression
Origin: http://example.com
Cookie: session=abc123                        // Normal HTTP cookies work
 
// ═══════════════════════════════════════════════════════════════
// REQUIRED HEADERS EXPLAINED
// ═══════════════════════════════════════════════════════════════
 
// Upgrade: websocket
//   - Signals intent to switch protocols
//   - Must be exactly "websocket" (case-insensitive)
 
// Connection: Upgrade  
//   - HTTP/1.1 hop-by-hop header indicating upgrade is desired
//   - Required for compliant upgrade
 
// Sec-WebSocket-Key: <base64-random>
//   - 16 random bytes, base64 encoded (24 characters)
//   - Server echoes transformed version to prove it understands WebSocket
//   - NOT for authentication—only protocol verification
 
// Sec-WebSocket-Version: 13
//   - Current WebSocket protocol version (RFC 6455)
//   - Older versions (8, 13) exist but 13 is standard
 
// ═══════════════════════════════════════════════════════════════
// SERVER SUCCESSFUL RESPONSE
// ═══════════════════════════════════════════════════════════════
 
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: chat                   // Server selected this subprotocol
 
// The Sec-WebSocket-Accept value is computed as:
// Base64(SHA-1(Sec-WebSocket-Key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"))
// This proves the server understood the WebSocket request

The Sec-WebSocket-Key / Accept mechanism:

This handshake includes a clever verification mechanism. The client sends a random key, and the server must return a computed value that proves it received and processed the WebSocket request. This prevents accidental connection upgrades by servers that don't understand WebSocket.

The server computes the Accept value by:

Concatenating the client's key with a fixed GUID (the "magic string")
Hashing with SHA-1
Base64 encoding the result

This is not authentication—it's protocol verification. Any proper WebSocket server can compute this. Authentication should be handled separately (via cookies, tokens in initial HTTP request, or first WebSocket message).

Handshake Failure Modes

The handshake can fail for many reasons: firewall blocking the upgrade, reverse proxy not forwarding upgrade headers, server returning wrong Accept value, CORS policy rejection, authentication failure, or server simply not supporting WebSocket on that path. Your client code must handle handshake failures gracefully—they're common in real-world networks.

Common Handshake Failure Responses
HTTP Status	Meaning	Common Cause	Client Action
400 Bad Request	Malformed request	Missing required headers	Check client implementation
401 Unauthorized	Authentication required	Missing/invalid credentials	Authenticate first, then retry
403 Forbidden	Origin rejected	CORS policy or server policy	Check Origin header is allowed
404 Not Found	Invalid path	Wrong endpoint URL	Verify WebSocket endpoint path
426 Upgrade Required	Wrong protocol version	Using unsupported WS version	Update client library
503 Service Unavailable	Server overloaded	Too many connections	Backoff and retry

Connection States

A WebSocket connection progresses through well-defined states during its lifecycle. Understanding these states is crucial because attempting operations in the wrong state causes errors. The WebSocket API exposes these states through the readyState property.

WebSocket Ready States
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// WebSocket.readyState values (defined in the WebSocket specification)
 
const WebSocket = {
    CONNECTING: 0,  // Connection is being established
    OPEN: 1,        // Connection is established and communication is possible
    CLOSING: 2,     // Connection is going through the closing handshake
    CLOSED: 3       // Connection is closed or couldn't be opened
};
 
// State transition diagram:
//
//   new WebSocket(url)
//          │
//          ▼
//    ┌─────────────┐      handshake       ┌─────────────┐
//    │ CONNECTING  │ ─────succeeds──────> │    OPEN     │
//    │  (readyState: 0)                   │ (readyState: 1) 
//    └─────────────┘                      └─────────────┘
//          │                                     │
//          │ handshake fails             close() or
//          │                             close received
//          │                                     │
//          │                                     ▼
//          │                             ┌─────────────┐
//          │                             │   CLOSING   │
//          │                             │ (readyState: 2)
//          │                             └─────────────┘
//          │                                     │
//          │                              close complete
//          │                                     │
//          ▼                                     ▼
//    ┌─────────────────────────────────────────────┐
//    │                   CLOSED                    │
//    │                (readyState: 3)              │
//    └─────────────────────────────────────────────┘

CONNECTING (0)

This state begins when you call new WebSocket(url) and lasts until the handshake completes (or fails). During this phase:

TCP connection is being established
HTTP upgrade request is sent
Waiting for server's 101 response
You cannot send data yet—doing so will throw an error

OPEN (1)

The connection is fully established.This is the active state where:

Both directions can send data freely
Messages are delivered reliably and in order
The connection remains open until explicitly closed or interrupted
This state can last milliseconds or days

CLOSING (2)

One party has initiated the close handshake:

close() was called locally, or close frame was received
No new messages can be sent
Waiting for the other party to acknowledge the close
Short-lived—typically completes within milliseconds to seconds

CLOSED (3)

The connection is terminated:

No further communication possible
Resources should be released
This is a terminal state—the connection cannot be reopened
A new WebSocket object must be created for reconnection

Proper State Checking
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// Always check state before sending
function safeSend(socket, message) {
    if (socket.readyState === WebSocket.OPEN) {
        socket.send(message);
        return true;
    }
    
    console.warn(`Cannot send: socket is ${getStateName(socket.readyState)}`);
    return false;
}
 
function getStateName(readyState) {
    switch(readyState) {
        case WebSocket.CONNECTING: return 'CONNECTING';
        case WebSocket.OPEN: return 'OPEN';
        case WebSocket.CLOSING: return 'CLOSING';
        case WebSocket.CLOSED: return 'CLOSED';
        default: return 'UNKNOWN';
    }
}
 
// Queuing messages during connection
class WebSocketClient {
    private socket: WebSocket;
    private messageQueue: string[] = [];
    
    connect(url: string) {
        this.socket = new WebSocket(url);
        
        this.socket.onopen = () => {
            // Flush queued messages once connected
            while (this.messageQueue.length > 0) {
                const msg = this.messageQueue.shift();
                this.socket.send(msg);
            }
        };
    }
    
    send(message: string) {
        if (this.socket.readyState === WebSocket.OPEN) {
            this.socket.send(message);
        } else if (this.socket.readyState === WebSocket.CONNECTING) {
            // Queue for later delivery
            this.messageQueue.push(message);
        } else {
            throw new Error('Cannot send: socket is closing or closed');
        }
    }
}

The Open State: Data Exchange

Once the handshake completes and the connection enters the OPEN state, the WebSocket is ready for bidirectional data exchange. This phase is where WebSockets deliver their value—low-latency, efficient messaging in both directions.

WebSocket Frame Types:

Data flows through the WebSocket connection as "frames"—small packets with minimal headers. The WebSocket protocol defines several frame types:

Text frames (opcode 0x1) — UTF-8 encoded text data
Binary frames (opcode 0x2) — Arbitrary binary data
Close frames (opcode 0x8) — Signals connection termination
Ping frames (opcode 0x9) — Keepalive request
Pong frames (opcode 0xA) — Response to ping
Continuation frames (opcode 0x0) — For fragmented messages

Text and binary frames carry application data. The other frame types are for protocol-level operations.

WebSocket Message Handling
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
// Client-side message handling
const socket = new WebSocket('wss://api.example.com/realtime');
 
// Receiving text data
socket.onmessage = (event) => {
    // event.data contains the message payload
    
    if (typeof event.data === 'string') {
        // Text frame received
        const data = JSON.parse(event.data);
        handleTextMessage(data);
    } else if (event.data instanceof Blob) {
        // Binary frame received (Blob by default in browsers)
        handleBinaryMessage(event.data);
    }
};
 
// To receive binary as ArrayBuffer instead of Blob:
socket.binaryType = 'arraybuffer';
 
socket.onmessage = (event) => {
    if (event.data instanceof ArrayBuffer) {
        const view = new DataView(event.data);
        // Process binary data
    }
};
 
// Sending different types
socket.send('Hello, World!');                    // Text frame
socket.send(JSON.stringify({ type: 'ping' }));   // Text frame (JSON)
socket.send(new Blob([data]));                   // Binary frame
socket.send(new Uint8Array([1, 2, 3, 4]));       // Binary frame
 
// Server-side (Node.js with 'ws' library)
import WebSocket, { WebSocketServer } from 'ws';
 
const wss = new WebSocketServer({ port: 8080 });
 
wss.on('connection', (ws) => {
    ws.on('message', (data, isBinary) => {
        if (isBinary) {
            // Binary message
            const buffer = data as Buffer;
            // Process binary data
        } else {
            // Text message
            const message = data.toString();
            const parsed = JSON.parse(message);
            handleMessage(ws, parsed);
        }
    });
    
    // Send to this client
    ws.send(JSON.stringify({ type: 'welcome' }));
    
    // Broadcast to all clients
    wss.clients.forEach((client) => {
        if (client.readyState === WebSocket.OPEN) {
            client.send(JSON.stringify({ type: 'broadcast', data: 'Hello!' }));
        }
    });
});

Message Framing Best Practice

WebSocket delivers complete messages—you don't need to handle partial reads or buffering. However, you should implement application-level message framing (typically JSON with a 'type' field) to distinguish different message kinds. This makes your protocol extensible and easier to debug.

Message Ordering Guarantees:

WebSockets run over TCP, which guarantees ordered, reliable delivery within a single direction. This means:

Messages sent in sequence arrive in the same sequence
Messages are never duplicated or lost (TCP handles retransmission)
Large messages are fragmented and reassembled automatically
There's no need for application-level sequence numbers for ordering

However, messages in opposite directions are independent. If the client sends messages A, B, C and the server sends X, Y, Z, the interleaving at the receiver is not guaranteed. A might arrive before X, or X might arrive before A—depending on network timing.

Ping/Pong Keepalive

Long-lived connections face a fundamental problem: silent failures. The TCP connection might be broken (network outage, server crash, firewall timeout) without either party knowing. The WebSocket protocol addresses this with a ping/pong mechanism that verifies connection liveness.

Why connections break silently:

NAT timeouts: Routers and firewalls track active connections. Idle connections may be evicted, breaking the path without notification.
Network changes: Mobile clients switching networks (WiFi to cellular) break TCP connections without graceful close.
Server crashes: If a server terminates abruptly, no close frame is sent. Clients remain unaware.
Half-open connections: TCP can enter states where one side believes the connection is open while the other has closed it.

Without active probing, these scenarios leave connections in a "zombie" state—appearing connected but unable to communicate.

Ping/Pong Implementation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
// ═══════════════════════════════════════════════════════════════
// SERVER-SIDE PING/PONG (Node.js with 'ws' library)
// ═══════════════════════════════════════════════════════════════
 
import WebSocket, { WebSocketServer } from 'ws';
 
const wss = new WebSocketServer({ port: 8080 });
 
const PING_INTERVAL = 30000; // 30 seconds
const PONG_TIMEOUT = 10000;  // 10 seconds to respond
 
wss.on('connection', (ws) => {
    let pingTimeout: NodeJS.Timeout;
    let isAlive = true;
    
    // Mark as alive when pong received
    ws.on('pong', () => {
        isAlive = true;
    });
    
    // Start ping interval
    const pingInterval = setInterval(() => {
        if (!isAlive) {
            // No pong received since last ping
            console.log('Client unresponsive, terminating connection');
            clearInterval(pingInterval);
            return ws.terminate(); // Forcefully close
        }
        
        isAlive = false;
        ws.ping(); // Send ping frame
        
        // Set timeout for pong response
        pingTimeout = setTimeout(() => {
            if (!isAlive) {
                console.log('Pong timeout, terminating');
                ws.terminate();
            }
        }, PONG_TIMEOUT);
    }, PING_INTERVAL);
    
    ws.on('close', () => {
        clearInterval(pingInterval);
        clearTimeout(pingTimeout);
    });
});
 
 
// ═══════════════════════════════════════════════════════════════
// CLIENT-SIDE PING/PONG
// ═══════════════════════════════════════════════════════════════
 
// Note: Browser WebSocket API doesn't expose ping/pong directly.
// Browsers automatically respond to server pings with pongs.
// For client-originated heartbeats, use application-level messages:
 
class WebSocketClient {
    private ws: WebSocket;
    private heartbeatInterval: number;
    private missedHeartbeats = 0;
    private maxMissedHeartbeats = 3;
    
    connect(url: string) {
        this.ws = new WebSocket(url);
        
        this.ws.onopen = () => {
            this.startHeartbeat();
        };
        
        this.ws.onmessage = (event) => {
            const msg = JSON.parse(event.data);
            
            if (msg.type === 'pong') {
                this.missedHeartbeats = 0; // Reset counter on pong
                return;
            }
            
            // Handle other messages...
        };
        
        this.ws.onclose = () => {
            this.stopHeartbeat();
        };
    }
    
    private startHeartbeat() {
        this.heartbeatInterval = window.setInterval(() => {
            if (this.missedHeartbeats >= this.maxMissedHeartbeats) {
                console.log('Server unresponsive, closing connection');
                this.ws.close();
                return;
            }
            
            if (this.ws.readyState === WebSocket.OPEN) {
                this.ws.send(JSON.stringify({ type: 'ping' }));
                this.missedHeartbeats++;
            }
        }, 30000);
    }
    
    private stopHeartbeat() {
        clearInterval(this.heartbeatInterval);
    }
}

Ping/Pong Configuration Guidelines
Parameter	Recommended Value	Trade-offs	Notes
Ping Interval	15-60 seconds	Shorter = faster detection, more traffic	Balance with NAT timeout (often 60s)
Pong Timeout	5-15 seconds	Shorter = faster detection, more false positives	Account for network latency
Max Missed Pongs	1-3	Higher = more tolerant of jitter	Lower for real-time critical apps
Server vs Client Ping	Server-initiated preferred	Browser API doesn't support client ping	Server has more control

Protocol-Level vs Application-Level Heartbeats

WebSocket's ping/pong frames are protocol-level and handled by the WebSocket layer. Browsers automatically respond to pings but don't expose the API to send them. For client-initiated heartbeats, use application-level messages (like JSON with type: 'ping'). Many production systems use both: protocol-level pings for connection health, application-level heartbeats for additional monitoring.

The Closing Handshake

Just as WebSocket connections require a handshake to open, they have a formal process for closing. This closing handshake ensures both parties know the connection is ending, allows in-flight messages to complete, and enables graceful resource cleanup.

Close frame contents:

When either party wants to close the connection, they send a close frame containing:

Status code (2 bytes): A numeric code indicating why the connection is closing
Reason (optional, up to 123 bytes): Human-readable explanation in UTF-8

The receiving party must respond with its own close frame (echoing the status code), after which both sides close the underlying TCP connection.

Close Handshake Flow
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
// ═══════════════════════════════════════════════════════════════
// GRACEFUL CLOSE INITIATED BY CLIENT
// ═══════════════════════════════════════════════════════════════
 
CLIENT                                  SERVER
   │                                       │
   │ readyState = OPEN                     │ readyState = OPEN
   │                                       │
   │──── CLOSE FRAME (1000, "bye") ─────>│ │
   │                                       │
   │ readyState = CLOSING                  │ (receives close)
   │                                       │
   │<───  CLOSE FRAME (1000, "bye") ────── │
   │                                       │
   │ (receives close response)             │ TCP close
   │ TCP close                             │ readyState = CLOSED
   │ readyState = CLOSED                   │
   │                                       │
 
 
// ═══════════════════════════════════════════════════════════════
// CLOSE CODES (RFC 6455)
// ═══════════════════════════════════════════════════════════════
 
const CLOSE_CODES = {
    NORMAL_CLOSURE:      1000,  // Normal closure; connection successfully completed
    GOING_AWAY:          1001,  // Endpoint going away (server shutdown, page navigation)
    PROTOCOL_ERROR:      1002,  // Termination due to protocol error
    UNSUPPORTED_DATA:    1003,  // Received data it cannot accept (e.g., text-only endpoint got binary)
    NO_STATUS_RECEIVED:  1005,  // Reserved—no status code was present (not sent on wire)
    ABNORMAL_CLOSURE:    1006,  // Reserved—connection closed abnormally (not sent on wire)
    INVALID_FRAME_DATA:  1007,  // Inconsistent data in message (e.g., invalid UTF-8 in text message)
    POLICY_VIOLATION:    1008,  // Generic policy violation (if no better code)
    MESSAGE_TOO_BIG:     1009,  // Message too large to process
    MANDATORY_EXT:       1010,  // Client expected extension server didn't negotiate
    INTERNAL_ERROR:      1011,  // Server encountered unexpected condition
    SERVICE_RESTART:     1012,  // Server restarting (client should reconnect)
    TRY_AGAIN_LATER:     1013,  // Server overloaded; client should reconnect later
    BAD_GATEWAY:         1014,  // Server acting as gateway received invalid response
    TLS_HANDSHAKE:       1015,  // Reserved—TLS handshake failed (not sent on wire)
    
    // Private use: 4000-4999 (application-specific codes)
    SESSION_EXPIRED:     4000,  // Example: Custom code for expired auth
    KICKED:              4001,  // Example: Custom code for forceful disconnect
};
 
 
// ═══════════════════════════════════════════════════════════════
// IMPLEMENTATION
// ═══════════════════════════════════════════════════════════════
 
// Client-side graceful close
function gracefulClose(socket, code = 1000, reason = 'Normal closure') {
    // Check state before closing
    if (socket.readyState === WebSocket.OPEN || 
        socket.readyState === WebSocket.CONNECTING) {
        socket.close(code, reason);
    }
}
 
// Server-side close handling
ws.on('close', (code, reason) => {
    console.log(`Connection closed: ${code} - ${reason}`);
    
    // Clean up application state
    removeFromActiveConnections(ws);
    notifyOtherUsers(ws.userId, 'left');
    
    // Log abnormal closures for investigation
    if (code !== 1000 && code !== 1001) {
        logAbnormalClose(ws, code, reason);
    }
});

Close vs Terminate

close() performs graceful shutdown (sends close frame, waits for response). terminate() immediately destroys the connection without handshake. Use terminate() only when the peer is unresponsive (failed ping/pong) or malicious. Graceful close allows in-flight messages to complete; terminate() may cause data loss.

Error Handling

WebSocket connections operate in unpredictable network environments. Robust error handling separates production-ready implementations from fragile prototypes. Understanding the types of errors and their appropriate responses is essential.

Error Categories

•Connection Errors — Handshake failures, DNS resolution failures, network unreachable. The connection never reaches OPEN state.
•Runtime Errors — Connection drops, protocol violations, message encoding errors. The connection was open but encountered problems.
•Application Errors — Invalid message format, authentication expiration, server-side exceptions. The connection is fine but application logic fails.
•Resource Errors — Memory limits, message size limits, connection limits. Infrastructure constraints are exceeded.

Comprehensive Error Handling
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
// Robust WebSocket client with proper error handling
class RobustWebSocket {
    private url: string;
    private ws: WebSocket | null = null;
    private reconnectAttempts = 0;
    private maxReconnectAttempts = 5;
    private reconnectDelay = 1000;
    private maxReconnectDelay = 30000;
    
    constructor(url: string) {
        this.url = url;
    }
    
    connect(): void {
        try {
            this.ws = new WebSocket(this.url);
            this.setupEventHandlers();
        } catch (error) {
            // Constructor can throw for invalid URLs
            console.error('Invalid WebSocket URL:', error);
            this.handleFatalError(error);
        }
    }
    
    private setupEventHandlers(): void {
        if (!this.ws) return;
        
        this.ws.onopen = () => {
            console.log('Connection established');
            this.reconnectAttempts = 0; // Reset on successful connection
            this.reconnectDelay = 1000;
        };
        
        this.ws.onerror = (event) => {
            // The error event doesn't contain useful information
            // in browsers (security restriction). The close event
            // that follows provides the actual details.
            console.error('WebSocket error occurred');
            // Note: onerror is always followed by onclose
        };
        
        this.ws.onclose = (event) => {
            console.log(`Connection closed: ${event.code} - ${event.reason}`);
            
            this.handleClose(event);
        };
        
        this.ws.onmessage = (event) => {
            try {
                const data = JSON.parse(event.data);
                this.handleMessage(data);
            } catch (error) {
                console.error('Failed to parse message:', error);
                // Don't close connection for parse errors—might be one bad message
            }
        };
    }
    
    private handleClose(event: CloseEvent): void {
        const { code, reason, wasClean } = event;
        
        // Decide whether to reconnect based on close code
        switch (code) {
            case 1000: // Normal closure
            case 1001: // Going away (navigation)
                // Intentional close, don't reconnect
                console.log('Clean shutdown, not reconnecting');
                break;
                
            case 1006: // Abnormal closure (no close frame received)
                // Connection dropped unexpectedly
                this.attemptReconnect('Connection lost');
                break;
                
            case 1011: // Server error
            case 1012: // Service restarting
            case 1013: // Try again later
                // Server-side issue, reconnect after delay
                this.attemptReconnect(`Server issue: ${code}`);
                break;
                
            case 4000: // Custom: Session expired
                // Re-authenticate before reconnecting
                this.handleAuthError();
                break;
                
            default:
                if (code >= 4000 && code < 5000) {
                    // Application-specific code
                    this.handleApplicationClose(code, reason);
                } else {
                    // Unknown code, attempt reconnect
                    this.attemptReconnect(`Unexpected close: ${code}`);
                }
        }
    }
    
    private attemptReconnect(reason: string): void {
        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
            console.error('Max reconnection attempts reached');
            this.handleFatalError(new Error('Connection failed after max attempts'));
            return;
        }
        
        this.reconnectAttempts++;
        const delay = Math.min(
            this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1),
            this.maxReconnectDelay
        );
        
        // Add jitter to prevent thundering herd
        const jitter = delay * 0.2 * Math.random();
        const actualDelay = delay + jitter;
        
        console.log(`Reconnecting in ${actualDelay}ms (attempt ${this.reconnectAttempts})`);
        
        setTimeout(() => this.connect(), actualDelay);
    }
    
    private handleFatalError(error: unknown): void {
        // Notify application of unrecoverable failure
        this.onFatalError?.(error);
    }
    
    private handleAuthError(): void {
        // Refresh auth and reconnect
        this.onAuthRequired?.();
    }
    
    // Callbacks for the application to implement
    onFatalError?: (error: unknown) => void;
    onAuthRequired?: () => void;
    handleMessage: (data: any) => void = () => {};
    handleApplicationClose: (code: number, reason: string) => void = () => {};
}

Reconnection Strategies

Production WebSocket applications must handle disconnections gracefully. Networks fail, servers restart, and clients go through tunnels. A robust reconnection strategy distinguishes resilient applications from those that frustrate users with connection errors.

Key reconnection principles:

1. Exponential Backoff with Jitter

After a failed connection attempt, wait before retrying—and increase the wait time exponentially. Add random jitter to prevent the "thundering herd" problem where thousands of clients reconnect simultaneously after a server restart.

2. Maximum Attempt Limits

Don't retry forever. After a reasonable number of attempts, inform the user and give them manual control. This prevents battery drain on mobile and resource waste when the server is truly unavailable.

3. State Recovery

After reconnection, restore application state. This might involve re-subscribing to channels, re-sending pending messages, or fetching missed events from a message history API.

4. Visibility-Aware Reconnection

Pause reconnection attempts when the browser tab is hidden or the app is backgrounded. Resume when focus returns.

Production Reconnection Implementation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
interface ReconnectionConfig {
    initialDelay: number;      // First retry delay (ms)
    maxDelay: number;          // Maximum delay (ms)
    maxAttempts: number;       // Give up after this many tries
    jitterFactor: number;      // 0-1, randomization factor
}
 
class ReconnectingWebSocket {
    private config: ReconnectionConfig = {
        initialDelay: 1000,
        maxDelay: 30000,
        maxAttempts: 10,
        jitterFactor: 0.3,
    };
    
    private url: string;
    private ws: WebSocket | null = null;
    private attempts = 0;
    private reconnectTimer: number | null = null;
    private forcedClose = false;
    private subscriptions: string[] = [];
    private pendingMessages: string[] = [];
    
    connect(url: string): void {
        this.url = url;
        this.forcedClose = false;
        this.doConnect();
    }
    
    private doConnect(): void {
        this.ws = new WebSocket(this.url);
        
        this.ws.onopen = () => {
            console.log('Connected');
            this.attempts = 0;
            
            // Restore state after reconnection
            this.restoreState();
        };
        
        this.ws.onclose = (event) => {
            if (this.forcedClose) {
                console.log('Connection closed intentionally');
                return;
            }
            
            // Check if tab is visible before reconnecting
            if (document.hidden) {
                // Wait for visibility change
                document.addEventListener('visibilitychange', () => {
                    if (!document.hidden) {
                        this.scheduleReconnect();
                    }
                }, { once: true });
            } else {
                this.scheduleReconnect();
            }
        };
    }
    
    private scheduleReconnect(): void {
        if (this.attempts >= this.config.maxAttempts) {
            this.onMaxAttemptsReached?.();
            return;
        }
        
        this.attempts++;
        
        // Calculate delay with exponential backoff
        const baseDelay = Math.min(
            this.config.initialDelay * Math.pow(2, this.attempts - 1),
            this.config.maxDelay
        );
        
        // Add jitter
        const jitter = baseDelay * this.config.jitterFactor * Math.random();
        const delay = baseDelay + jitter;
        
        console.log(`Reconnecting in ${Math.round(delay)}ms (attempt ${this.attempts})`);
        
        this.onReconnecting?.(this.attempts, delay);
        
        this.reconnectTimer = window.setTimeout(() => {
            this.doConnect();
        }, delay);
    }
    
    private restoreState(): void {
        // Re-subscribe to channels
        for (const channel of this.subscriptions) {
            this.send(JSON.stringify({ 
                type: 'subscribe', 
                channel 
            }));
        }
        
        // Send pending messages
        while (this.pendingMessages.length > 0) {
            const msg = this.pendingMessages.shift();
            this.ws?.send(msg!);
        }
        
        // Fetch missed messages from last known position
        this.send(JSON.stringify({
            type: 'sync',
            lastEventId: this.lastEventId
        }));
    }
    
    subscribe(channel: string): void {
        // Track subscription for restoration after reconnect
        if (!this.subscriptions.includes(channel)) {
            this.subscriptions.push(channel);
        }
        
        if (this.ws?.readyState === WebSocket.OPEN) {
            this.send(JSON.stringify({ type: 'subscribe', channel }));
        }
    }
    
    send(message: string): boolean {
        if (this.ws?.readyState === WebSocket.OPEN) {
            this.ws.send(message);
            return true;
        } else {
            // Queue for sending after reconnection
            this.pendingMessages.push(message);
            return false;
        }
    }
    
    close(): void {
        this.forcedClose = true;
        if (this.reconnectTimer) {
            clearTimeout(this.reconnectTimer);
        }
        this.ws?.close(1000, 'Client closing');
    }
    
    // Event callbacks
    onReconnecting?: (attempt: number, delay: number) => void;
    onMaxAttemptsReached?: () => void;
    lastEventId: string = '';
}

Libraries Handle This

Libraries like Socket.io, SockJS, and ReconnectingWebSocket implement sophisticated reconnection logic out of the box. In production, consider using these instead of building from scratch—they handle edge cases you might not anticipate.

Summary: Mastering the WebSocket Lifecycle

The WebSocket lifecycle—from opening handshake through data exchange to graceful closure—requires careful management for production applications. Let's consolidate the key concepts:

Key Takeaways

•The opening handshake upgrades HTTP to WebSocket — It uses HTTP initially (working with existing infrastructure) then switches to the lightweight WebSocket framing protocol.
•Four connection states govern behavior — CONNECTING, OPEN, CLOSING, CLOSED. Always check state before sending; queue messages during CONNECTING.
•Ping/pong keeps connections alive — Silent failures happen. Regular keepalive probing detects dead connections and enables timely recovery.
•Graceful closing uses close frames with status codes — Both parties exchange close frames. Use appropriate codes (1000 for normal, 4xxx for application-specific).
•Errors come in many forms — Connection, runtime, application, and resource errors each require different handling strategies.
•Reconnection requires exponential backoff with jitter — Never hammer the server. Back off, add randomness, and eventually give up or prompt the user.
•State recovery after reconnection is essential — Re-subscribe, replay pending messages, and sync any missed events for seamless user experience.

What's next:

Understanding the lifecycle of a single connection is foundational. But real applications have thousands or millions of concurrent connections. The next page examines scaling WebSocket connections—connection management at scale, horizontal scaling strategies, and the architectural patterns that enable WebSockets in distributed systems.

Page Complete

You now understand the complete WebSocket lifecycle from handshake to closure. You can implement proper state management, keepalive mechanisms, graceful shutdown, error handling, and reconnection strategies for production-grade WebSocket applications.

2 / 5

Loading learning content...

System Design (HLD)WebSockets

WebSockets: Real-Time Bidirectional Communication

LevelIntermediate

Duration75 mins

TopicWebSockets

2 / 5

WebSocket Lifecycle

The Complete Journey of a WebSocket Connection

The WebSocket lifecycle comprises four distinct phases:

Opening Handshake — The HTTP upgrade process that establishes the connection
Open State — The active phase where bidirectional data exchange occurs
Closing Handshake — The graceful termination protocol
Closed State — Connection terminated; resources released

Each phase has its own mechanics, potential failure modes, and best practices. This page provides the comprehensive understanding needed to implement production-grade WebSocket systems.

What You Will Learn

The Opening Handshake

Protocol negotiation — Both parties agree to switch from HTTP to WebSocket protocol
Security validation — The server can verify the client's identity and origin
Subprotocol negotiation — Optional application-level protocol selection
Extension negotiation — Optional features like compression

Complete Opening Handshake
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// ═══════════════════════════════════════════════════════════════
// CLIENT OPENING HANDSHAKE REQUEST
// ═══════════════════════════════════════════════════════════════
 
GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: x3JJHMbDL1EzLkh9GBhXDw==
Sec-WebSocket-Version: 13
Sec-WebSocket-Protocol: chat, superchat       // Optional: subprotocol preferences
Sec-WebSocket-Extensions: permessage-deflate  // Optional: compression
Origin: http://example.com
Cookie: session=abc123                        // Normal HTTP cookies work
 
// ═══════════════════════════════════════════════════════════════
// REQUIRED HEADERS EXPLAINED
// ═══════════════════════════════════════════════════════════════
 
// Upgrade: websocket
//   - Signals intent to switch protocols
//   - Must be exactly "websocket" (case-insensitive)
 
// Connection: Upgrade  
//   - HTTP/1.1 hop-by-hop header indicating upgrade is desired
//   - Required for compliant upgrade
 
// Sec-WebSocket-Key: <base64-random>
//   - 16 random bytes, base64 encoded (24 characters)
//   - Server echoes transformed version to prove it understands WebSocket
//   - NOT for authentication—only protocol verification
 
// Sec-WebSocket-Version: 13
//   - Current WebSocket protocol version (RFC 6455)
//   - Older versions (8, 13) exist but 13 is standard
 
// ═══════════════════════════════════════════════════════════════
// SERVER SUCCESSFUL RESPONSE
// ═══════════════════════════════════════════════════════════════
 
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: HSmrc0sMlYUkAGmm5OPpG2HaGWk=
Sec-WebSocket-Protocol: chat                   // Server selected this subprotocol
 
// The Sec-WebSocket-Accept value is computed as:
// Base64(SHA-1(Sec-WebSocket-Key + "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"))
// This proves the server understood the WebSocket request

The Sec-WebSocket-Key / Accept mechanism:

The server computes the Accept value by:

Concatenating the client's key with a fixed GUID (the "magic string")
Hashing with SHA-1
Base64 encoding the result

Handshake Failure Modes

Common Handshake Failure Responses
HTTP Status	Meaning	Common Cause	Client Action
400 Bad Request	Malformed request	Missing required headers	Check client implementation
401 Unauthorized	Authentication required	Missing/invalid credentials	Authenticate first, then retry
403 Forbidden	Origin rejected	CORS policy or server policy	Check Origin header is allowed
404 Not Found	Invalid path	Wrong endpoint URL	Verify WebSocket endpoint path
426 Upgrade Required	Wrong protocol version	Using unsupported WS version	Update client library
503 Service Unavailable	Server overloaded	Too many connections	Backoff and retry

Connection States

WebSocket Ready States
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
// WebSocket.readyState values (defined in the WebSocket specification)
 
const WebSocket = {
    CONNECTING: 0,  // Connection is being established
    OPEN: 1,        // Connection is established and communication is possible
    CLOSING: 2,     // Connection is going through the closing handshake
    CLOSED: 3       // Connection is closed or couldn't be opened
};
 
// State transition diagram:
//
//   new WebSocket(url)
//          │
//          ▼
//    ┌─────────────┐      handshake       ┌─────────────┐
//    │ CONNECTING  │ ─────succeeds──────> │    OPEN     │
//    │  (readyState: 0)                   │ (readyState: 1) 
//    └─────────────┘                      └─────────────┘
//          │                                     │
//          │ handshake fails             close() or
//          │                             close received
//          │                                     │
//          │                                     ▼
//          │                             ┌─────────────┐
//          │                             │   CLOSING   │
//          │                             │ (readyState: 2)
//          │                             └─────────────┘
//          │                                     │
//          │                              close complete
//          │                                     │
//          ▼                                     ▼
//    ┌─────────────────────────────────────────────┐
//    │                   CLOSED                    │
//    │                (readyState: 3)              │
//    └─────────────────────────────────────────────┘

CONNECTING (0)

This state begins when you call new WebSocket(url) and lasts until the handshake completes (or fails). During this phase:

TCP connection is being established
HTTP upgrade request is sent
Waiting for server's 101 response
You cannot send data yet—doing so will throw an error

OPEN (1)

The connection is fully established.This is the active state where:

Both directions can send data freely
Messages are delivered reliably and in order
The connection remains open until explicitly closed or interrupted
This state can last milliseconds or days

CLOSING (2)

One party has initiated the close handshake:

close() was called locally, or close frame was received
No new messages can be sent
Waiting for the other party to acknowledge the close
Short-lived—typically completes within milliseconds to seconds

CLOSED (3)

The connection is terminated:

No further communication possible
Resources should be released
This is a terminal state—the connection cannot be reopened
A new WebSocket object must be created for reconnection

Proper State Checking
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
// Always check state before sending
function safeSend(socket, message) {
    if (socket.readyState === WebSocket.OPEN) {
        socket.send(message);
        return true;
    }
    
    console.warn(`Cannot send: socket is ${getStateName(socket.readyState)}`);
    return false;
}
 
function getStateName(readyState) {
    switch(readyState) {
        case WebSocket.CONNECTING: return 'CONNECTING';
        case WebSocket.OPEN: return 'OPEN';
        case WebSocket.CLOSING: return 'CLOSING';
        case WebSocket.CLOSED: return 'CLOSED';
        default: return 'UNKNOWN';
    }
}
 
// Queuing messages during connection
class WebSocketClient {
    private socket: WebSocket;
    private messageQueue: string[] = [];
    
    connect(url: string) {
        this.socket = new WebSocket(url);
        
        this.socket.onopen = () => {
            // Flush queued messages once connected
            while (this.messageQueue.length > 0) {
                const msg = this.messageQueue.shift();
                this.socket.send(msg);
            }
        };
    }
    
    send(message: string) {
        if (this.socket.readyState === WebSocket.OPEN) {
            this.socket.send(message);
        } else if (this.socket.readyState === WebSocket.CONNECTING) {
            // Queue for later delivery
            this.messageQueue.push(message);
        } else {
            throw new Error('Cannot send: socket is closing or closed');
        }
    }
}

The Open State: Data Exchange

WebSocket Frame Types:

Data flows through the WebSocket connection as "frames"—small packets with minimal headers. The WebSocket protocol defines several frame types:

Text frames (opcode 0x1) — UTF-8 encoded text data
Binary frames (opcode 0x2) — Arbitrary binary data
Close frames (opcode 0x8) — Signals connection termination
Ping frames (opcode 0x9) — Keepalive request
Pong frames (opcode 0xA) — Response to ping
Continuation frames (opcode 0x0) — For fragmented messages

Text and binary frames carry application data. The other frame types are for protocol-level operations.

WebSocket Message Handling
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
// Client-side message handling
const socket = new WebSocket('wss://api.example.com/realtime');
 
// Receiving text data
socket.onmessage = (event) => {
    // event.data contains the message payload
    
    if (typeof event.data === 'string') {
        // Text frame received
        const data = JSON.parse(event.data);
        handleTextMessage(data);
    } else if (event.data instanceof Blob) {
        // Binary frame received (Blob by default in browsers)
        handleBinaryMessage(event.data);
    }
};
 
// To receive binary as ArrayBuffer instead of Blob:
socket.binaryType = 'arraybuffer';
 
socket.onmessage = (event) => {
    if (event.data instanceof ArrayBuffer) {
        const view = new DataView(event.data);
        // Process binary data
    }
};
 
// Sending different types
socket.send('Hello, World!');                    // Text frame
socket.send(JSON.stringify({ type: 'ping' }));   // Text frame (JSON)
socket.send(new Blob([data]));                   // Binary frame
socket.send(new Uint8Array([1, 2, 3, 4]));       // Binary frame
 
// Server-side (Node.js with 'ws' library)
import WebSocket, { WebSocketServer } from 'ws';
 
const wss = new WebSocketServer({ port: 8080 });
 
wss.on('connection', (ws) => {
    ws.on('message', (data, isBinary) => {
        if (isBinary) {
            // Binary message
            const buffer = data as Buffer;
            // Process binary data
        } else {
            // Text message
            const message = data.toString();
            const parsed = JSON.parse(message);
            handleMessage(ws, parsed);
        }
    });
    
    // Send to this client
    ws.send(JSON.stringify({ type: 'welcome' }));
    
    // Broadcast to all clients
    wss.clients.forEach((client) => {
        if (client.readyState === WebSocket.OPEN) {
            client.send(JSON.stringify({ type: 'broadcast', data: 'Hello!' }));
        }
    });
});

Message Framing Best Practice

Message Ordering Guarantees:

WebSockets run over TCP, which guarantees ordered, reliable delivery within a single direction. This means:

Messages sent in sequence arrive in the same sequence
Messages are never duplicated or lost (TCP handles retransmission)
Large messages are fragmented and reassembled automatically
There's no need for application-level sequence numbers for ordering

Ping/Pong Keepalive

Why connections break silently:

NAT timeouts: Routers and firewalls track active connections. Idle connections may be evicted, breaking the path without notification.
Network changes: Mobile clients switching networks (WiFi to cellular) break TCP connections without graceful close.
Server crashes: If a server terminates abruptly, no close frame is sent. Clients remain unaware.
Half-open connections: TCP can enter states where one side believes the connection is open while the other has closed it.

Without active probing, these scenarios leave connections in a "zombie" state—appearing connected but unable to communicate.

Ping/Pong Implementation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
// ═══════════════════════════════════════════════════════════════
// SERVER-SIDE PING/PONG (Node.js with 'ws' library)
// ═══════════════════════════════════════════════════════════════
 
import WebSocket, { WebSocketServer } from 'ws';
 
const wss = new WebSocketServer({ port: 8080 });
 
const PING_INTERVAL = 30000; // 30 seconds
const PONG_TIMEOUT = 10000;  // 10 seconds to respond
 
wss.on('connection', (ws) => {
    let pingTimeout: NodeJS.Timeout;
    let isAlive = true;
    
    // Mark as alive when pong received
    ws.on('pong', () => {
        isAlive = true;
    });
    
    // Start ping interval
    const pingInterval = setInterval(() => {
        if (!isAlive) {
            // No pong received since last ping
            console.log('Client unresponsive, terminating connection');
            clearInterval(pingInterval);
            return ws.terminate(); // Forcefully close
        }
        
        isAlive = false;
        ws.ping(); // Send ping frame
        
        // Set timeout for pong response
        pingTimeout = setTimeout(() => {
            if (!isAlive) {
                console.log('Pong timeout, terminating');
                ws.terminate();
            }
        }, PONG_TIMEOUT);
    }, PING_INTERVAL);
    
    ws.on('close', () => {
        clearInterval(pingInterval);
        clearTimeout(pingTimeout);
    });
});
 
 
// ═══════════════════════════════════════════════════════════════
// CLIENT-SIDE PING/PONG
// ═══════════════════════════════════════════════════════════════
 
// Note: Browser WebSocket API doesn't expose ping/pong directly.
// Browsers automatically respond to server pings with pongs.
// For client-originated heartbeats, use application-level messages:
 
class WebSocketClient {
    private ws: WebSocket;
    private heartbeatInterval: number;
    private missedHeartbeats = 0;
    private maxMissedHeartbeats = 3;
    
    connect(url: string) {
        this.ws = new WebSocket(url);
        
        this.ws.onopen = () => {
            this.startHeartbeat();
        };
        
        this.ws.onmessage = (event) => {
            const msg = JSON.parse(event.data);
            
            if (msg.type === 'pong') {
                this.missedHeartbeats = 0; // Reset counter on pong
                return;
            }
            
            // Handle other messages...
        };
        
        this.ws.onclose = () => {
            this.stopHeartbeat();
        };
    }
    
    private startHeartbeat() {
        this.heartbeatInterval = window.setInterval(() => {
            if (this.missedHeartbeats >= this.maxMissedHeartbeats) {
                console.log('Server unresponsive, closing connection');
                this.ws.close();
                return;
            }
            
            if (this.ws.readyState === WebSocket.OPEN) {
                this.ws.send(JSON.stringify({ type: 'ping' }));
                this.missedHeartbeats++;
            }
        }, 30000);
    }
    
    private stopHeartbeat() {
        clearInterval(this.heartbeatInterval);
    }
}

Ping/Pong Configuration Guidelines
Parameter	Recommended Value	Trade-offs	Notes
Ping Interval	15-60 seconds	Shorter = faster detection, more traffic	Balance with NAT timeout (often 60s)
Pong Timeout	5-15 seconds	Shorter = faster detection, more false positives	Account for network latency
Max Missed Pongs	1-3	Higher = more tolerant of jitter	Lower for real-time critical apps
Server vs Client Ping	Server-initiated preferred	Browser API doesn't support client ping	Server has more control

Protocol-Level vs Application-Level Heartbeats

The Closing Handshake

Close frame contents:

When either party wants to close the connection, they send a close frame containing:

Status code (2 bytes): A numeric code indicating why the connection is closing
Reason (optional, up to 123 bytes): Human-readable explanation in UTF-8

The receiving party must respond with its own close frame (echoing the status code), after which both sides close the underlying TCP connection.

Close Handshake Flow
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
// ═══════════════════════════════════════════════════════════════
// GRACEFUL CLOSE INITIATED BY CLIENT
// ═══════════════════════════════════════════════════════════════
 
CLIENT                                  SERVER
   │                                       │
   │ readyState = OPEN                     │ readyState = OPEN
   │                                       │
   │──── CLOSE FRAME (1000, "bye") ─────>│ │
   │                                       │
   │ readyState = CLOSING                  │ (receives close)
   │                                       │
   │<───  CLOSE FRAME (1000, "bye") ────── │
   │                                       │
   │ (receives close response)             │ TCP close
   │ TCP close                             │ readyState = CLOSED
   │ readyState = CLOSED                   │
   │                                       │
 
 
// ═══════════════════════════════════════════════════════════════
// CLOSE CODES (RFC 6455)
// ═══════════════════════════════════════════════════════════════
 
const CLOSE_CODES = {
    NORMAL_CLOSURE:      1000,  // Normal closure; connection successfully completed
    GOING_AWAY:          1001,  // Endpoint going away (server shutdown, page navigation)
    PROTOCOL_ERROR:      1002,  // Termination due to protocol error
    UNSUPPORTED_DATA:    1003,  // Received data it cannot accept (e.g., text-only endpoint got binary)
    NO_STATUS_RECEIVED:  1005,  // Reserved—no status code was present (not sent on wire)
    ABNORMAL_CLOSURE:    1006,  // Reserved—connection closed abnormally (not sent on wire)
    INVALID_FRAME_DATA:  1007,  // Inconsistent data in message (e.g., invalid UTF-8 in text message)
    POLICY_VIOLATION:    1008,  // Generic policy violation (if no better code)
    MESSAGE_TOO_BIG:     1009,  // Message too large to process
    MANDATORY_EXT:       1010,  // Client expected extension server didn't negotiate
    INTERNAL_ERROR:      1011,  // Server encountered unexpected condition
    SERVICE_RESTART:     1012,  // Server restarting (client should reconnect)
    TRY_AGAIN_LATER:     1013,  // Server overloaded; client should reconnect later
    BAD_GATEWAY:         1014,  // Server acting as gateway received invalid response
    TLS_HANDSHAKE:       1015,  // Reserved—TLS handshake failed (not sent on wire)
    
    // Private use: 4000-4999 (application-specific codes)
    SESSION_EXPIRED:     4000,  // Example: Custom code for expired auth
    KICKED:              4001,  // Example: Custom code for forceful disconnect
};
 
 
// ═══════════════════════════════════════════════════════════════
// IMPLEMENTATION
// ═══════════════════════════════════════════════════════════════
 
// Client-side graceful close
function gracefulClose(socket, code = 1000, reason = 'Normal closure') {
    // Check state before closing
    if (socket.readyState === WebSocket.OPEN || 
        socket.readyState === WebSocket.CONNECTING) {
        socket.close(code, reason);
    }
}
 
// Server-side close handling
ws.on('close', (code, reason) => {
    console.log(`Connection closed: ${code} - ${reason}`);
    
    // Clean up application state
    removeFromActiveConnections(ws);
    notifyOtherUsers(ws.userId, 'left');
    
    // Log abnormal closures for investigation
    if (code !== 1000 && code !== 1001) {
        logAbnormalClose(ws, code, reason);
    }
});

Close vs Terminate

Error Handling

Error Categories

•Connection Errors — Handshake failures, DNS resolution failures, network unreachable. The connection never reaches OPEN state.
•Runtime Errors — Connection drops, protocol violations, message encoding errors. The connection was open but encountered problems.
•Application Errors — Invalid message format, authentication expiration, server-side exceptions. The connection is fine but application logic fails.
•Resource Errors — Memory limits, message size limits, connection limits. Infrastructure constraints are exceeded.

Comprehensive Error Handling
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
// Robust WebSocket client with proper error handling
class RobustWebSocket {
    private url: string;
    private ws: WebSocket | null = null;
    private reconnectAttempts = 0;
    private maxReconnectAttempts = 5;
    private reconnectDelay = 1000;
    private maxReconnectDelay = 30000;
    
    constructor(url: string) {
        this.url = url;
    }
    
    connect(): void {
        try {
            this.ws = new WebSocket(this.url);
            this.setupEventHandlers();
        } catch (error) {
            // Constructor can throw for invalid URLs
            console.error('Invalid WebSocket URL:', error);
            this.handleFatalError(error);
        }
    }
    
    private setupEventHandlers(): void {
        if (!this.ws) return;
        
        this.ws.onopen = () => {
            console.log('Connection established');
            this.reconnectAttempts = 0; // Reset on successful connection
            this.reconnectDelay = 1000;
        };
        
        this.ws.onerror = (event) => {
            // The error event doesn't contain useful information
            // in browsers (security restriction). The close event
            // that follows provides the actual details.
            console.error('WebSocket error occurred');
            // Note: onerror is always followed by onclose
        };
        
        this.ws.onclose = (event) => {
            console.log(`Connection closed: ${event.code} - ${event.reason}`);
            
            this.handleClose(event);
        };
        
        this.ws.onmessage = (event) => {
            try {
                const data = JSON.parse(event.data);
                this.handleMessage(data);
            } catch (error) {
                console.error('Failed to parse message:', error);
                // Don't close connection for parse errors—might be one bad message
            }
        };
    }
    
    private handleClose(event: CloseEvent): void {
        const { code, reason, wasClean } = event;
        
        // Decide whether to reconnect based on close code
        switch (code) {
            case 1000: // Normal closure
            case 1001: // Going away (navigation)
                // Intentional close, don't reconnect
                console.log('Clean shutdown, not reconnecting');
                break;
                
            case 1006: // Abnormal closure (no close frame received)
                // Connection dropped unexpectedly
                this.attemptReconnect('Connection lost');
                break;
                
            case 1011: // Server error
            case 1012: // Service restarting
            case 1013: // Try again later
                // Server-side issue, reconnect after delay
                this.attemptReconnect(`Server issue: ${code}`);
                break;
                
            case 4000: // Custom: Session expired
                // Re-authenticate before reconnecting
                this.handleAuthError();
                break;
                
            default:
                if (code >= 4000 && code < 5000) {
                    // Application-specific code
                    this.handleApplicationClose(code, reason);
                } else {
                    // Unknown code, attempt reconnect
                    this.attemptReconnect(`Unexpected close: ${code}`);
                }
        }
    }
    
    private attemptReconnect(reason: string): void {
        if (this.reconnectAttempts >= this.maxReconnectAttempts) {
            console.error('Max reconnection attempts reached');
            this.handleFatalError(new Error('Connection failed after max attempts'));
            return;
        }
        
        this.reconnectAttempts++;
        const delay = Math.min(
            this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1),
            this.maxReconnectDelay
        );
        
        // Add jitter to prevent thundering herd
        const jitter = delay * 0.2 * Math.random();
        const actualDelay = delay + jitter;
        
        console.log(`Reconnecting in ${actualDelay}ms (attempt ${this.reconnectAttempts})`);
        
        setTimeout(() => this.connect(), actualDelay);
    }
    
    private handleFatalError(error: unknown): void {
        // Notify application of unrecoverable failure
        this.onFatalError?.(error);
    }
    
    private handleAuthError(): void {
        // Refresh auth and reconnect
        this.onAuthRequired?.();
    }
    
    // Callbacks for the application to implement
    onFatalError?: (error: unknown) => void;
    onAuthRequired?: () => void;
    handleMessage: (data: any) => void = () => {};
    handleApplicationClose: (code: number, reason: string) => void = () => {};
}

Reconnection Strategies

Key reconnection principles:

1. Exponential Backoff with Jitter

2. Maximum Attempt Limits

3. State Recovery

After reconnection, restore application state. This might involve re-subscribing to channels, re-sending pending messages, or fetching missed events from a message history API.

4. Visibility-Aware Reconnection

Pause reconnection attempts when the browser tab is hidden or the app is backgrounded. Resume when focus returns.

Production Reconnection Implementation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
interface ReconnectionConfig {
    initialDelay: number;      // First retry delay (ms)
    maxDelay: number;          // Maximum delay (ms)
    maxAttempts: number;       // Give up after this many tries
    jitterFactor: number;      // 0-1, randomization factor
}
 
class ReconnectingWebSocket {
    private config: ReconnectionConfig = {
        initialDelay: 1000,
        maxDelay: 30000,
        maxAttempts: 10,
        jitterFactor: 0.3,
    };
    
    private url: string;
    private ws: WebSocket | null = null;
    private attempts = 0;
    private reconnectTimer: number | null = null;
    private forcedClose = false;
    private subscriptions: string[] = [];
    private pendingMessages: string[] = [];
    
    connect(url: string): void {
        this.url = url;
        this.forcedClose = false;
        this.doConnect();
    }
    
    private doConnect(): void {
        this.ws = new WebSocket(this.url);
        
        this.ws.onopen = () => {
            console.log('Connected');
            this.attempts = 0;
            
            // Restore state after reconnection
            this.restoreState();
        };
        
        this.ws.onclose = (event) => {
            if (this.forcedClose) {
                console.log('Connection closed intentionally');
                return;
            }
            
            // Check if tab is visible before reconnecting
            if (document.hidden) {
                // Wait for visibility change
                document.addEventListener('visibilitychange', () => {
                    if (!document.hidden) {
                        this.scheduleReconnect();
                    }
                }, { once: true });
            } else {
                this.scheduleReconnect();
            }
        };
    }
    
    private scheduleReconnect(): void {
        if (this.attempts >= this.config.maxAttempts) {
            this.onMaxAttemptsReached?.();
            return;
        }
        
        this.attempts++;
        
        // Calculate delay with exponential backoff
        const baseDelay = Math.min(
            this.config.initialDelay * Math.pow(2, this.attempts - 1),
            this.config.maxDelay
        );
        
        // Add jitter
        const jitter = baseDelay * this.config.jitterFactor * Math.random();
        const delay = baseDelay + jitter;
        
        console.log(`Reconnecting in ${Math.round(delay)}ms (attempt ${this.attempts})`);
        
        this.onReconnecting?.(this.attempts, delay);
        
        this.reconnectTimer = window.setTimeout(() => {
            this.doConnect();
        }, delay);
    }
    
    private restoreState(): void {
        // Re-subscribe to channels
        for (const channel of this.subscriptions) {
            this.send(JSON.stringify({ 
                type: 'subscribe', 
                channel 
            }));
        }
        
        // Send pending messages
        while (this.pendingMessages.length > 0) {
            const msg = this.pendingMessages.shift();
            this.ws?.send(msg!);
        }
        
        // Fetch missed messages from last known position
        this.send(JSON.stringify({
            type: 'sync',
            lastEventId: this.lastEventId
        }));
    }
    
    subscribe(channel: string): void {
        // Track subscription for restoration after reconnect
        if (!this.subscriptions.includes(channel)) {
            this.subscriptions.push(channel);
        }
        
        if (this.ws?.readyState === WebSocket.OPEN) {
            this.send(JSON.stringify({ type: 'subscribe', channel }));
        }
    }
    
    send(message: string): boolean {
        if (this.ws?.readyState === WebSocket.OPEN) {
            this.ws.send(message);
            return true;
        } else {
            // Queue for sending after reconnection
            this.pendingMessages.push(message);
            return false;
        }
    }
    
    close(): void {
        this.forcedClose = true;
        if (this.reconnectTimer) {
            clearTimeout(this.reconnectTimer);
        }
        this.ws?.close(1000, 'Client closing');
    }
    
    // Event callbacks
    onReconnecting?: (attempt: number, delay: number) => void;
    onMaxAttemptsReached?: () => void;
    lastEventId: string = '';
}

Libraries Handle This

Summary: Mastering the WebSocket Lifecycle

The WebSocket lifecycle—from opening handshake through data exchange to graceful closure—requires careful management for production applications. Let's consolidate the key concepts:

Key Takeaways

•The opening handshake upgrades HTTP to WebSocket — It uses HTTP initially (working with existing infrastructure) then switches to the lightweight WebSocket framing protocol.
•Four connection states govern behavior — CONNECTING, OPEN, CLOSING, CLOSED. Always check state before sending; queue messages during CONNECTING.
•Ping/pong keeps connections alive — Silent failures happen. Regular keepalive probing detects dead connections and enables timely recovery.
•Graceful closing uses close frames with status codes — Both parties exchange close frames. Use appropriate codes (1000 for normal, 4xxx for application-specific).
•Errors come in many forms — Connection, runtime, application, and resource errors each require different handling strategies.
•Reconnection requires exponential backoff with jitter — Never hammer the server. Back off, add randomness, and eventually give up or prompt the user.
•State recovery after reconnection is essential — Re-subscribe, replay pending messages, and sync any missed events for seamless user experience.

What's next:

Page Complete

2 / 5