22 KiB
name: realtime-websocket-implementation description: Use WebSocket implementation when you need:
WebSocket Implementation
Scope: WebSocket protocol, connection management, reconnection strategies, and heartbeat patterns Lines: 387 Last Updated: 2025-10-18
When to Use This Skill
Use WebSocket implementation when you need:
- Bidirectional communication: Full-duplex communication between client and server
- Low latency: Sub-100ms message delivery for chat, gaming, or trading applications
- Server push: Server needs to push updates without client polling
- Persistent connections: Long-lived connections for real-time data streams
- Binary data: Efficient transmission of binary protocols (protobuf, MessagePack)
Don't use when:
- Unidirectional data flow is sufficient (use Server-Sent Events)
- Client is behind restrictive proxies (WebSocket may be blocked)
- Simple HTTP requests would suffice (REST APIs are simpler)
- Broadcasting to many clients without client->server messages (SSE is lighter)
Core Concepts
WebSocket Protocol
Client Server
| |
|-- HTTP Upgrade Request ------->|
| |
|<-- 101 Switching Protocols ----|
| |
|<====== WebSocket Frames ======>|
| |
|-- Close Frame ---------------->|
|<-- Close Frame ----------------|
Key Features:
- Upgrade from HTTP/1.1 to WebSocket protocol
- Frame-based messaging (text or binary)
- Built-in ping/pong for connection health
- Close handshake for graceful shutdown
Connection States
CONNECTING (0) → Handshake in progress
OPEN (1) → Connection established, can send/receive
CLOSING (2) → Close handshake started
CLOSED (3) → Connection closed or failed
Frame Types
- Text frames: UTF-8 encoded strings
- Binary frames: Raw binary data
- Ping/Pong frames: Connection health check
- Close frames: Connection termination
- Continuation frames: Fragmented messages
Patterns
1. Basic Client Implementation (Browser)
// TypeScript/JavaScript client
class WebSocketClient {
private ws: WebSocket | null = null;
private url: string;
private reconnectAttempts = 0;
private maxReconnectAttempts = 5;
private reconnectDelay = 1000;
private heartbeatInterval: number | null = null;
private messageHandlers: Map<string, (data: any) => void> = new Map();
constructor(url: string) {
this.url = url;
}
connect(): Promise<void> {
return new Promise((resolve, reject) => {
this.ws = new WebSocket(this.url);
this.ws.onopen = () => {
console.log('WebSocket connected');
this.reconnectAttempts = 0;
this.startHeartbeat();
resolve();
};
this.ws.onmessage = (event) => {
this.handleMessage(event.data);
};
this.ws.onerror = (error) => {
console.error('WebSocket error:', error);
reject(error);
};
this.ws.onclose = (event) => {
console.log('WebSocket closed:', event.code, event.reason);
this.stopHeartbeat();
this.handleReconnect();
};
});
}
private handleMessage(data: string) {
try {
const message = JSON.parse(data);
const handler = this.messageHandlers.get(message.type);
if (handler) {
handler(message.data);
}
} catch (error) {
console.error('Failed to parse message:', error);
}
}
on(type: string, handler: (data: any) => void) {
this.messageHandlers.set(type, handler);
}
send(type: string, data: any) {
if (this.ws?.readyState === WebSocket.OPEN) {
this.ws.send(JSON.stringify({ type, data }));
} else {
console.error('WebSocket not connected');
}
}
private startHeartbeat() {
this.heartbeatInterval = window.setInterval(() => {
if (this.ws?.readyState === WebSocket.OPEN) {
this.ws.send(JSON.stringify({ type: 'ping' }));
}
}, 30000); // 30 seconds
}
private stopHeartbeat() {
if (this.heartbeatInterval !== null) {
clearInterval(this.heartbeatInterval);
this.heartbeatInterval = null;
}
}
private handleReconnect() {
if (this.reconnectAttempts < this.maxReconnectAttempts) {
this.reconnectAttempts++;
const delay = this.reconnectDelay * Math.pow(2, this.reconnectAttempts - 1);
console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
setTimeout(() => this.connect(), delay);
} else {
console.error('Max reconnection attempts reached');
}
}
close() {
this.stopHeartbeat();
this.ws?.close(1000, 'Client closing');
}
}
// Usage
const client = new WebSocketClient('wss://api.example.com/ws');
await client.connect();
client.on('message', (data) => {
console.log('Received:', data);
});
client.send('chat', { text: 'Hello, world!' });
2. Basic Server Implementation (Node.js)
// Using ws library
import { WebSocketServer, WebSocket } from 'ws';
import http from 'http';
interface Client {
ws: WebSocket;
id: string;
rooms: Set<string>;
lastPing: number;
}
class WebSocketServerManager {
private wss: WebSocketServer;
private clients: Map<string, Client> = new Map();
private rooms: Map<string, Set<string>> = new Map();
constructor(server: http.Server) {
this.wss = new WebSocketServer({ server });
this.initialize();
}
private initialize() {
this.wss.on('connection', (ws, req) => {
const id = this.generateClientId();
const client: Client = {
ws,
id,
rooms: new Set(),
lastPing: Date.now(),
};
this.clients.set(id, client);
console.log(`Client ${id} connected. Total clients: ${this.clients.size}`);
ws.on('message', (data) => {
this.handleMessage(client, data.toString());
});
ws.on('close', () => {
this.handleDisconnect(client);
});
ws.on('error', (error) => {
console.error(`Client ${id} error:`, error);
});
ws.on('pong', () => {
client.lastPing = Date.now();
});
// Send welcome message
this.sendToClient(client, 'connected', { id });
});
// Start heartbeat check
this.startHeartbeat();
}
private handleMessage(client: Client, data: string) {
try {
const message = JSON.parse(data);
switch (message.type) {
case 'ping':
this.sendToClient(client, 'pong', {});
break;
case 'join':
this.joinRoom(client, message.data.room);
break;
case 'leave':
this.leaveRoom(client, message.data.room);
break;
case 'broadcast':
this.broadcast(message.data.room, message.data);
break;
default:
console.log(`Unknown message type: ${message.type}`);
}
} catch (error) {
console.error('Failed to parse message:', error);
}
}
private sendToClient(client: Client, type: string, data: any) {
if (client.ws.readyState === WebSocket.OPEN) {
client.ws.send(JSON.stringify({ type, data }));
}
}
private joinRoom(client: Client, room: string) {
client.rooms.add(room);
if (!this.rooms.has(room)) {
this.rooms.set(room, new Set());
}
this.rooms.get(room)!.add(client.id);
console.log(`Client ${client.id} joined room ${room}`);
}
private leaveRoom(client: Client, room: string) {
client.rooms.delete(room);
this.rooms.get(room)?.delete(client.id);
console.log(`Client ${client.id} left room ${room}`);
}
private broadcast(room: string, data: any) {
const clientIds = this.rooms.get(room);
if (!clientIds) return;
clientIds.forEach((clientId) => {
const client = this.clients.get(clientId);
if (client) {
this.sendToClient(client, 'broadcast', data);
}
});
}
private handleDisconnect(client: Client) {
// Remove from all rooms
client.rooms.forEach((room) => {
this.rooms.get(room)?.delete(client.id);
});
this.clients.delete(client.id);
console.log(`Client ${client.id} disconnected. Total clients: ${this.clients.size}`);
}
private startHeartbeat() {
setInterval(() => {
const now = Date.now();
this.clients.forEach((client) => {
if (now - client.lastPing > 60000) {
// No ping in 60 seconds, close connection
console.log(`Client ${client.id} timeout`);
client.ws.terminate();
return;
}
if (client.ws.readyState === WebSocket.OPEN) {
client.ws.ping();
}
});
}, 30000); // Check every 30 seconds
}
private generateClientId(): string {
return `client_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
}
}
// Usage
const server = http.createServer();
const wsManager = new WebSocketServerManager(server);
server.listen(8080);
3. Exponential Backoff Reconnection
class ReconnectingWebSocket {
private url: string;
private ws: WebSocket | null = null;
private reconnectAttempts = 0;
private maxReconnectDelay = 30000;
private minReconnectDelay = 1000;
private reconnectDecay = 1.5;
private shouldReconnect = true;
constructor(url: string) {
this.url = url;
}
connect(): Promise<void> {
return new Promise((resolve, reject) => {
this.ws = new WebSocket(this.url);
const timeout = setTimeout(() => {
this.ws?.close();
reject(new Error('Connection timeout'));
}, 10000);
this.ws.onopen = () => {
clearTimeout(timeout);
this.reconnectAttempts = 0;
resolve();
};
this.ws.onclose = () => {
clearTimeout(timeout);
if (this.shouldReconnect) {
this.scheduleReconnect();
}
};
this.ws.onerror = (error) => {
clearTimeout(timeout);
reject(error);
};
});
}
private scheduleReconnect() {
const delay = Math.min(
this.minReconnectDelay * Math.pow(this.reconnectDecay, this.reconnectAttempts),
this.maxReconnectDelay
);
// Add jitter to prevent thundering herd
const jitter = delay * 0.1 * Math.random();
const totalDelay = delay + jitter;
this.reconnectAttempts++;
console.log(`Reconnecting in ${totalDelay.toFixed(0)}ms (attempt ${this.reconnectAttempts})`);
setTimeout(() => {
if (this.shouldReconnect) {
this.connect().catch((error) => {
console.error('Reconnection failed:', error);
});
}
}, totalDelay);
}
disconnect() {
this.shouldReconnect = false;
this.ws?.close();
}
}
4. Authentication and Authorization
// Client-side: Send auth token on connection
class AuthenticatedWebSocket {
private ws: WebSocket | null = null;
async connect(url: string, token: string): Promise<void> {
return new Promise((resolve, reject) => {
// Option 1: Token in URL query parameter
this.ws = new WebSocket(`${url}?token=${token}`);
this.ws.onopen = () => {
// Option 2: Send auth message after connection
this.ws!.send(JSON.stringify({ type: 'auth', token }));
resolve();
};
this.ws.onerror = reject;
});
}
}
// Server-side: Verify token
interface AuthenticatedClient extends Client {
userId: string;
authenticated: boolean;
}
class AuthenticatedWebSocketServer {
private handleConnection(ws: WebSocket, req: http.IncomingMessage) {
const client: AuthenticatedClient = {
ws,
id: this.generateClientId(),
rooms: new Set(),
lastPing: Date.now(),
userId: '',
authenticated: false,
};
// Option 1: Extract token from URL
const url = new URL(req.url!, `http://${req.headers.host}`);
const token = url.searchParams.get('token');
if (token && this.verifyToken(token)) {
client.authenticated = true;
client.userId = this.getUserIdFromToken(token);
}
// Set authentication timeout
const authTimeout = setTimeout(() => {
if (!client.authenticated) {
ws.close(4001, 'Authentication timeout');
}
}, 5000);
ws.on('message', (data) => {
const message = JSON.parse(data.toString());
// Option 2: Handle auth message
if (message.type === 'auth') {
if (this.verifyToken(message.token)) {
client.authenticated = true;
client.userId = this.getUserIdFromToken(message.token);
clearTimeout(authTimeout);
this.sendToClient(client, 'auth_success', { userId: client.userId });
} else {
ws.close(4002, 'Invalid token');
}
return;
}
// Require authentication for other messages
if (!client.authenticated) {
ws.close(4003, 'Not authenticated');
return;
}
this.handleMessage(client, message);
});
}
private verifyToken(token: string): boolean {
// Implement JWT verification or session validation
return true; // Placeholder
}
private getUserIdFromToken(token: string): string {
// Extract user ID from token
return 'user_123'; // Placeholder
}
}
Quick Reference
Client Connection
// Basic connection
const ws = new WebSocket('wss://api.example.com/ws');
// With protocols
const ws = new WebSocket('wss://api.example.com/ws', ['v1.protocol']);
// Check state
ws.readyState // CONNECTING=0, OPEN=1, CLOSING=2, CLOSED=3
// Send data
ws.send('text message');
ws.send(new Uint8Array([1, 2, 3]));
ws.send(JSON.stringify({ type: 'message', data: {} }));
Event Handlers
ws.onopen = (event) => { /* Connection opened */ };
ws.onmessage = (event) => { /* Message received: event.data */ };
ws.onerror = (event) => { /* Error occurred */ };
ws.onclose = (event) => { /* Connection closed: event.code, event.reason */ };
Close Codes
1000: Normal closure
1001: Going away (page navigation)
1002: Protocol error
1003: Unsupported data
1006: Abnormal closure (no close frame)
1008: Policy violation
1009: Message too big
1011: Server error
4000-4999: Application-specific codes
Server Libraries
// Node.js: ws
import { WebSocketServer } from 'ws';
// Node.js: uWebSockets.js (high performance)
import uWS from 'uWebSockets.js';
// Python: websockets
import websockets
// Go: gorilla/websocket
import "github.com/gorilla/websocket"
Anti-Patterns
❌ No Reconnection Logic
// Wrong: No reconnection handling
const ws = new WebSocket(url);
ws.onclose = () => {
console.log('Disconnected'); // Connection lost forever
};
Why it's bad: Network issues, server restarts, or idle timeouts will permanently lose connection
Better approach:
class WebSocketClient {
private reconnect() {
setTimeout(() => this.connect(), this.getBackoffDelay());
}
}
❌ No Heartbeat/Keepalive
// Wrong: No connection health check
const ws = new WebSocket(url);
// Connection might be dead but readyState still shows OPEN
Why it's bad: Idle connections can be closed by proxies/load balancers without notification
Better approach:
setInterval(() => {
if (ws.readyState === WebSocket.OPEN) {
ws.send(JSON.stringify({ type: 'ping' }));
}
}, 30000);
❌ Sending Before Connection Open
// Wrong: Send immediately
const ws = new WebSocket(url);
ws.send('hello'); // Error: WebSocket is not open
Why it's bad: Messages sent before connection is established will throw errors
Better approach:
const ws = new WebSocket(url);
ws.onopen = () => {
ws.send('hello'); // Safe
};
❌ No Message Queuing During Reconnection
// Wrong: Drop messages during reconnection
send(data: any) {
if (this.ws?.readyState === WebSocket.OPEN) {
this.ws.send(data);
}
// Message is lost if not connected
}
Why it's bad: Messages sent during reconnection are silently lost
Better approach:
private queue: any[] = [];
send(data: any) {
if (this.ws?.readyState === WebSocket.OPEN) {
this.ws.send(data);
} else {
this.queue.push(data);
}
}
private flushQueue() {
while (this.queue.length > 0) {
this.ws!.send(this.queue.shift()!);
}
}
❌ No Error Handling for Invalid Messages
// Wrong: Assume all messages are valid JSON
ws.onmessage = (event) => {
const data = JSON.parse(event.data); // Can throw
handleMessage(data);
};
Why it's bad: Malformed messages crash the application
Better approach:
ws.onmessage = (event) => {
try {
const data = JSON.parse(event.data);
handleMessage(data);
} catch (error) {
console.error('Invalid message:', error);
}
};
Level 3: Resources
Comprehensive Reference
Location: ~/.hanzo/skills/realtime/websocket-implementation/resources/REFERENCE.md
The comprehensive reference (1,900+ lines) covers:
- WebSocket protocol fundamentals (RFC 6455)
- Connection lifecycle (handshake, frames, close)
- Frame structure and opcodes
- Message types (text, binary, ping/pong, close)
- Security considerations (origin validation, authentication, TLS)
- Scaling patterns (sticky sessions, Redis pub/sub, message queues)
- Reconnection strategies with exponential backoff
- Server implementations (Node.js ws, Python websockets, Go gorilla)
- Client implementations (browser, Node.js, Python)
- Testing strategies (unit, integration, load)
- Common patterns (chat, real-time dashboards, multiplayer games)
- Comparison with alternatives (SSE, long polling, HTTP/2)
- Production best practices (monitoring, logging, resource limits)
- Troubleshooting guide
- Performance optimization techniques
Testing & Analysis Scripts
Location: ~/.hanzo/skills/realtime/websocket-implementation/resources/scripts/
test_websocket.py - WebSocket testing tool
- Test connectivity, echo, latency, ping/pong
- Support for text and binary messages
- Connection lifecycle testing
- Large message handling
- Reconnection testing
- JSON output for CI/CD integration
- Usage:
./test_websocket.py wss://api.example.com/ws --latency --count 20 --json
benchmark_connections.py - Connection benchmark tool
- Test concurrent connections (100s to 1000s)
- Measure connection establishment time
- Throughput metrics (messages/sec, bytes/sec)
- Gradual ramp-up support
- Duration-based load testing
- Detailed per-connection statistics
- Usage:
./benchmark_connections.py ws://localhost:8080 --connections 1000 --duration 60
analyze_traffic.sh - Traffic analysis tool
- Capture WebSocket traffic with tcpdump
- Analyze with tshark for detailed inspection
- WebSocket handshake detection
- Frame type breakdown (text, binary, ping, pong, close)
- Payload size statistics
- Connection duration analysis
- JSON output for tooling integration
- Usage:
./analyze_traffic.sh --interface eth0 --port 8080 --duration 60 --analyze
Production Examples
Location: ~/.hanzo/skills/realtime/websocket-implementation/resources/examples/
Node.js Server (node/websocket-server.js)
- Production-ready WebSocket server using 'ws' library
- Room-based messaging with broadcast support
- Rate limiting and connection metrics
- Ping/pong heartbeat with timeout detection
- Graceful shutdown handling
- Health check and metrics endpoints
- Message routing and validation
Node.js Client (node/websocket-client.js)
- Robust client with exponential backoff reconnection
- Message queueing during disconnection
- Heartbeat detection with automatic reconnect
- State machine management
- Event-driven architecture
- TypeScript-ready implementation
Python Server (python/websocket_server.py)
- Async/await server using 'websockets' library
- Room management and broadcasting
- Token bucket rate limiting
- Built-in ping/pong support
- Metrics reporting
- Signal handling for graceful shutdown
Python Client (python/websocket_client.py)
- Async client with reconnection logic
- Message queueing and batching
- Callback-based event handling
- Heartbeat monitoring
- Connection state tracking
React Hook (react/useWebSocket.tsx)
- Custom hook for React applications
- Automatic reconnection with state management
- Message queueing during reconnection
- TypeScript support
- Example components (chat room, connection status)
- Optimized for React 18+ patterns
Docker Deployment (docker/)
- Multi-container setup with docker-compose
- Scalable WebSocket servers with Redis pub/sub
- Nginx load balancer with sticky sessions
- Prometheus + Grafana monitoring
- Health checks and auto-restart
- Production-ready configuration
Usage Examples
# Test WebSocket server connectivity and latency
./resources/scripts/test_websocket.py wss://api.example.com/ws --latency --count 10
# Benchmark 1000 concurrent connections
./resources/scripts/benchmark_connections.py ws://localhost:8080 \
--connections 1000 --duration 60 --ramp-up 30
# Analyze WebSocket traffic
./resources/scripts/analyze_traffic.sh \
--interface eth0 --port 8080 --duration 300 --analyze
# Run Node.js server
cd resources/examples/node && npm install && node websocket-server.js
# Run Python server
cd resources/examples/python && python websocket_server.py --port 8080
# Deploy with Docker
cd resources/examples/docker && docker-compose up -d
docker-compose scale websocket=3 # Scale to 3 instances
Related Skills
- server-sent-events.md: Alternative for unidirectional server-to-client streaming
- realtime-sync.md: Conflict resolution and data synchronization over WebSockets
- pubsub-patterns.md: Message routing and fan-out patterns for WebSocket servers
- network-resilience-patterns.md: Advanced retry, circuit breaker, and timeout patterns
Last Updated: 2025-10-27 Format Version: 1.0 (Atomic)