# Websocket Engineer > Real-time communication expertise covering WebSocket protocol, Socket.IO patterns, connection lifecycle, room and channel management, reconnection strategies, scaling WebSockets, SSE vs WebSocket, heartbeat/ping-pong, and message serialization. Use when the user asks about websocket engineer, websocket engineer best practices, or needs guidance on websocket engineer implementation. Do NOT use when the user needs a different specialized skill or is asking about an unrelated technology domain. - Skill: `ferroxlabs/websocket-engineer` (Agent Skill, multi-file: 2 files) - Install (CLI): `npx skillmds@latest add ferroxlabs/websocket-engineer` - Raw SKILL.md: https://api.skillmd.com/api/skills/ferroxlabs/websocket-engineer/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - License: Apache-2.0 - Author: FerroxLabs (https://skillmd.com/u/ferroxlabs) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/ferroxlabs/websocket-engineer --- # WebSocket Engineer ## Purpose Design and implement real-time communication systems using WebSockets and related technologies. This skill covers protocol fundamentals, architecture patterns, scaling strategies, and the decision framework for choosing between real-time technologies. ## Technology Selection ### Decision Matrix ``` NEED TECHNOLOGY ----------------------------------------------------------- Unidirectional (server -> client) Server-Sent Events (SSE) Bidirectional, simple Native WebSocket Bidirectional + features Socket.IO High-frequency data (gaming) WebSocket + binary Occasional updates HTTP polling / long-polling SSE vs WebSocket: SSE: + Simple (just HTTP) + Auto-reconnection built in + Works through proxies/firewalls easily + Event ID for resuming # ... (condensed) ... + Acknowledgments (request-reply) + Binary support - Additional library dependency - Larger payload (protocol overhead) - Not a standard protocol ``` ## WebSocket Protocol ### Connection Lifecycle ``` 1. HANDSHAKE (HTTP Upgrade) Client -> Server: GET /ws HTTP/1.1 Connection: Upgrade Upgrade: websocket Sec-WebSocket-Key: dGhlIHNhbXBsZS... Sec-WebSocket-Version: 13 Server -> Client: HTTP/1.1 101 Switching Protocols Connection: Upgrade Upgrade: websocket Sec-WebSocket-Accept: s3pPLMBiTxaQ9k... 2. DATA TRANSFER Bidirectional frames (text or binary) # ... (condensed) ... 1003 Unsupported data type 1006 Abnormal closure (no close frame received) 1008 Policy violation 1009 Message too big 1011 Unexpected server error ``` ### Native WebSocket Server (Node.js) ```ts import { WebSocketServer, WebSocket } from 'ws'; import { createServer } from 'http'; const server = createServer(); const wss = new WebSocketServer({ server }); // Authentication during upgrade server.on('upgrade', (request, socket, head) => { const token = new URL(request.url!, `[reference URL]).searchParams.get('token'); try { const user = verifyToken(token!); wss.handleUpgrade(request, socket, head, (ws) => { (ws as any).user = user; # ... (condensed) ... }, 30000); // Every 30 seconds wss.on('close', () => clearInterval(heartbeatInterval)); server.listen(3000); ``` ## Socket.IO Patterns ### Server Setup ```ts import { Server } from 'socket.io'; import { createServer } from 'http'; const httpServer = createServer(); const io = new Server(httpServer, { cors: { origin: ['[reference URL]'], credentials: true, }, pingTimeout: 60000, pingInterval: 25000, maxHttpBufferSize: 1e6, // 1MB max message size connectionStateRecovery: { maxDisconnectionDuration: 2 * 60 * 1000, // 2 minutes # ... (condensed) ... // Disconnect socket.on('disconnect', (reason) => { console.log(`Disconnected: ${user.id} (${reason})`); }); }); ``` ### Client Setup ```ts import { io, Socket } from 'socket.io-client'; function createSocket(token: string): Socket { const socket = io('[reference URL]', { auth: { token }, reconnection: true, reconnectionAttempts: 10, reconnectionDelay: 1000, reconnectionDelayMax: 30000, timeout: 10000, transports: ['websocket'], // Skip polling, go straight to WS }); socket.on('connect', () => { # ... (condensed) ... if (response.error) reject(new Error(response.error)); else resolve(response); }); }); } ``` ## Room/Channel Management ### Room Patterns ```ts // Namespace for feature separation const chatNamespace = io.of('/chat'); const notificationNamespace = io.of('/notifications'); // Each namespace has independent middleware and event handlers chatNamespace.use(chatAuthMiddleware); notificationNamespace.use(notificationAuthMiddleware); // Room operations // Join: socket.join('room:abc') // Leave: socket.leave('room:abc') // Emit to room: io.to('room:abc').emit('event', data) // Emit to room except sender: socket.to('room:abc').emit('event', data) // Get room members: io.in('room:abc').fetchSockets() # ... (condensed) ... chat: (id: string) => `chat:${id}`, document: (id: string) => `doc:${id}`, user: (id: string) => `user:${id}`, // Personal notifications org: (id: string) => `org:${id}`, // Organization-wide }; ``` ## Reconnection Strategy ```ts // Exponential backoff with jitter class ReconnectionManager { private attempt = 0; private maxAttempts = 10; private baseDelay = 1000; // 1 second private maxDelay = 30000; // 30 seconds private timer: ReturnType | null = null; scheduleReconnect(connect: () => void): void { if (this.attempt >= this.maxAttempts) { console.error('Max reconnection attempts reached'); return; } # ... (condensed) ... cancel(): void { if (this.timer) clearTimeout(this.timer); } } ``` ## Scaling WebSockets ### Horizontal Scaling with Redis Adapter ```ts import { Server } from 'socket.io'; import { createAdapter } from '@socket.io/redis-adapter'; import { createClient } from 'redis'; // Each server instance connects to Redis const pubClient = createClient({ url: REDIS_URL }); const subClient = pubClient.duplicate(); await Promise.all([pubClient.connect(), subClient.connect()]); const io = new Server(httpServer); io.adapter(createAdapter(pubClient, subClient)); // Now io.to('room').emit() works across all server instances // Redis Pub/Sub broadcasts to all connected Socket.IO servers ``` ### Architecture ``` [Load Balancer] (sticky sessions*) / | \ [Server 1] [Server 2] [Server 3] \ | / [Redis Adapter (Pub/Sub)] | [Redis Cluster] * Sticky sessions ensure a client always hits the same server. Required because WebSocket upgrade must go to the same server that received the initial HTTP request. With Socket.IO: use cookie-based affinity or client IP hash. With K8s: use session affinity on Ingress. ``` ### Scaling Considerations ``` CONNECTION LIMITS: - Each server: 10,000-50,000 connections (depends on memory/CPU) - Each connection: ~10KB base memory - 50,000 connections ~= 500MB just for connections - Linux: increase file descriptor limits (ulimit -n 1000000) MESSAGE THROUGHPUT: - JSON serialization is CPU-bound - Binary (MessagePack, Protobuf) reduces serialization overhead - Batch messages when possible (group updates) - Use compression for large payloads (permessage-deflate) PRESENCE TRACKING: - Use Redis Sets for online users per room - Use Redis Pub/Sub for presence change notifications - Don't query presence from individual server instances ``` ## Heartbeat / Ping-Pong ```ts // Server-side heartbeat (native WebSocket) const HEARTBEAT_INTERVAL = 30000; // 30 seconds const HEARTBEAT_TIMEOUT = 10000; // 10 seconds to respond function setupHeartbeat(wss: WebSocketServer) { const interval = scheduleRepeating(() => { wss.clients.forEach((ws) => { if (!(ws as any).isAlive) { console.log('Client unresponsive, terminating'); return ws.terminate(); } (ws as any).isAlive = false; ws.ping(); // Send ping frame }); # ... (condensed) ... const latency = Date.now() - msg.timestamp; metrics.recordLatency(latency); } }); } ``` ## Message Serialization ```ts // JSON (default, human-readable) ws.send(JSON.stringify({ type: 'message', data: { text: 'hello' } })); // MessagePack (binary, more compact) import { encode, decode } from '@msgpack/msgpack'; ws.send(encode({ type: 'message', data: { text: 'hello' } })); // Protocol Buffers (binary, schema-enforced) // Requires .proto schema definition const Message = proto.lookupType('Message'); const buffer = Message.encode({ type: 'message', text: 'hello' }).finish(); ws.send(buffer); // COMPARISON: // JSON: {"type":"message","text":"hello"} -> ~36 bytes // MessagePack: same structure -> ~26 bytes (28% smaller) // Protobuf: same structure -> ~15 bytes (58% smaller) // RECOMMENDATION: // Start with JSON (simplest, debuggable) // Switch to MessagePack if bandwidth is a concern // Use Protobuf for high-frequency, performance-critical scenarios ``` ## Server-Sent Events (SSE) ```ts // Server app.get('/api/events', (req, res) => { res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache', 'Connection': 'keep-alive', 'X-Accel-Buffering': 'no', // Disable Nginx buffering }); // Send initial connection event res.write(`data: ${JSON.stringify({ type: 'connected' })}\n\n`); // Send periodic heartbeat to keep connection alive const heartbeat = scheduleRepeating(() => { # ... (condensed) ... eventSource.addEventListener('message:new', (e) => { const message = JSON.parse(e.data); addMessageToUI(message); }); // Auto-reconnects with Last-Event-ID header ``` ## WebSocket Architecture Checklist - [ ] Technology selected (WebSocket, Socket.IO, SSE) based on requirements - [ ] Authentication implemented during connection upgrade - [ ] Heartbeat/ping-pong configured to detect stale connections - [ ] Reconnection strategy with exponential backoff and jitter - [ ] Room/channel management for grouping connections - [ ] Message format defined (JSON, MessagePack, or Protobuf) - [ ] Redis adapter configured for horizontal scaling - [ ] Sticky sessions enabled on load balancer - [ ] File descriptor limits increased on servers - [ ] Connection and message rate limiting implemented - [ ] Error handling for malformed messages - [ ] Graceful shutdown with close frames - [ ] Monitoring covers connection count, message throughput, latency - [ ] Presence tracking using Redis for cross-server accuracy ## When to Use **Use this skill when:** - Designing or implementing websocket engineer solutions - Reviewing or improving existing websocket engineer approaches - Making architectural or implementation decisions about websocket engineer - Learning websocket engineer patterns and best practices - Troubleshooting websocket engineer-related issues **Do NOT use this skill when:** - The question is about a fundamentally different technology domain - A more specific sibling skill covers the exact topic needed - The user needs a complete hands-on tutorial rather than expert guidance ## Output Format ```markdown # Websocket Engineer Analysis ## Context Assessment [Situation summary and constraints] ## Recommended Approach [Primary recommendation with rationale] ## Implementation Steps 1. [Step with specific details] 2. [Step with specific details] 3. [Step with specific details] ## Trade-offs and Considerations - [Key trade-off 1] - [Key trade-off 2] ## Next Steps - [Immediate action item] - [Follow-up action item] ``` ## Example **Input:** "Help me implement websocket engineer for a medium-scale production application" **Output:** A structured analysis covering current state assessment, recommended websocket engineer approach with specific patterns, implementation roadmap with milestones, and risk mitigation strategies tailored to the application scale and constraints. ## Edge Cases - **Legacy system integration:** When websocket engineer must coexist with legacy approaches, provide a gradual migration path rather than a complete rewrite - **Scale mismatch:** When the solution complexity exceeds the project scale, recommend a simpler approach and note when to revisit - **Team skill gaps:** When the team lacks experience with the recommended approach, include learning resources and simpler alternatives - **Conflicting requirements:** When constraints conflict (e.g., performance vs. maintainability), explicitly state the trade-off and recommend based on stated priorities