Building WebSocket Server
Overview
Build scalable WebSocket servers for real-time bidirectional communication using the ws library, Socket.IO, or native framework WebSocket support. Handle connection lifecycle management, room/channel subscriptions, message broadcasting, heartbeat keepalive, and horizontal scaling with Redis pub/sub adapters.
Prerequisites
- Node.js 18+ with
ws or socket.io, or Python 3.10+ with websockets or FastAPI WebSocket, or Go with gorilla/websocket
- Redis for horizontal scaling with pub/sub adapter (Socket.IO Redis adapter, or manual pub/sub)
- Load balancer configured for WebSocket upgrade (sticky sessions or proper
Upgrade header forwarding)
- JWT or session-based authentication for connection handshake
- Monitoring for active connection counts and message throughput
Instructions
- Examine existing HTTP server configuration using Read and Grep to determine the framework and identify where WebSocket upgrade handling integrates.
- Create a WebSocket server instance attached to the existing HTTP server, configuring the upgrade path (e.g.,
/ws, /socket.io) and allowed origins.
- Implement connection authentication by validating JWT tokens or session cookies during the WebSocket handshake
upgrade event, rejecting unauthorized connections before protocol switch.
- Build a connection registry that tracks active clients with metadata (user ID, subscribed channels, connection time) for targeted message delivery.
- Define a message protocol using JSON envelopes with
type, channel, payload, and correlationId fields for structured bidirectional communication.
- Implement room/channel subscription logic allowing clients to join and leave named channels with server-side membership tracking.
- Add heartbeat ping/pong mechanism with configurable interval (default 30s) and timeout detection to clean up stale connections.
- Configure Redis pub/sub adapter for horizontal scaling so messages broadcast from any server instance reach all connected clients across the cluster.
- Write connection lifecycle tests covering connect, authenticate, subscribe, message exchange, reconnect, and graceful disconnect scenarios.
See ${CLAUDE_SKILL_DIR}/references/implementation.md for the full implementation guide.
Output
${CLAUDE_SKILL_DIR}/src/ws/server.js - WebSocket server setup and upgrade handling${CLAUDE_SKILL_DIR}/src/ws/handlers/ - Per-message-type handler functions${CLAUDE_SKILL_DIR}/src/ws/rooms.js - Room/channel subscription management${CLAUDE_SKILL_DIR}/src/ws/registry.js - Active connection tracking registry${CLAUDE_SKILL_DIR}/src/ws/heartbeat.js - Ping/pong keepalive logic${CLAUDE_SKILL_DIR}/src/ws/adapters/redis.js - Redis pub/sub adapter for scaling${CLAUDE_SKILL_DIR}/tests/ws/ - WebSocket connection and messaging tests
Error Handling
| Error |
Cause |
Solution |
| 401 during upgrade |
JWT token missing or expired in handshake query/headers |
Reject upgrade with HTTP 401 before WebSocket protocol switch completes |
| 1008 Policy Violation |
Client sends malformed message or violates protocol |
Send close frame with code 1008 and human-readable reason; log violation |
| 1006 Abnormal Closure |
Network interruption without close handshake |
Detect via heartbeat timeout; clean up connection registry; notify room members |
| Memory leak |
Connection registry grows unbounded from stale entries |
Implement heartbeat-based cleanup sweep every 60s; enforce max connections per server |
| Message storm |
Single client flooding messages beyond acceptable rate |
Apply per-connection message rate limiting; disconnect abusive clients with 1008 |
Refer to ${CLAUDE_SKILL_DIR}/references/errors.md for comprehensive error patterns.
Examples
Chat application: Multi-room chat server where clients join named rooms, receive member presence updates, and see real-time message delivery with typing indicators via separate message types.
Live dashboard: Server pushes metric updates to subscribed dashboard clients every second, with initial state snapshot on connection and incremental deltas thereafter.
Collaborative editing: Operational transformation relay server that receives edit operations from clients, transforms against concurrent operations, and broadcasts resolved changes to all document subscribers.
See ${CLAUDE_SKILL_DIR}/references/examples.md for additional examples.
Resources
1---2name: building-websocket-server3description: |4 Build scalable WebSocket servers for real-time bidirectional communication.5 Use when enabling real-time bidirectional communication.6 Trigger with phrases like "build WebSocket server", "add real-time API", or "implement WebSocket".7 8allowed-tools: Read, Write, Edit, Grep, Glob, Bash(api:websocket-*)9version: 1.0.010author: Jeremy Longshore <jeremy@intentsolutions.io>11license: MIT12compatible-with: claude-code, codex, openclaw13tags: [api, scaling, websocket-server]1415---1617# Building WebSocket Server1819## Overview2021Build scalable WebSocket servers for real-time bidirectional communication using the `ws` library, Socket.IO, or native framework WebSocket support. Handle connection lifecycle management, room/channel subscriptions, message broadcasting, heartbeat keepalive, and horizontal scaling with Redis pub/sub adapters.2223## Prerequisites2425- Node.js 18+ with `ws` or `socket.io`, or Python 3.10+ with `websockets` or FastAPI WebSocket, or Go with `gorilla/websocket`26- Redis for horizontal scaling with pub/sub adapter (Socket.IO Redis adapter, or manual pub/sub)27- Load balancer configured for WebSocket upgrade (sticky sessions or proper `Upgrade` header forwarding)28- JWT or session-based authentication for connection handshake29- Monitoring for active connection counts and message throughput3031## Instructions32331. Examine existing HTTP server configuration using Read and Grep to determine the framework and identify where WebSocket upgrade handling integrates.342. Create a WebSocket server instance attached to the existing HTTP server, configuring the upgrade path (e.g., `/ws`, `/socket.io`) and allowed origins.353. Implement connection authentication by validating JWT tokens or session cookies during the WebSocket handshake `upgrade` event, rejecting unauthorized connections before protocol switch.364. Build a connection registry that tracks active clients with metadata (user ID, subscribed channels, connection time) for targeted message delivery.375. Define a message protocol using JSON envelopes with `type`, `channel`, `payload`, and `correlationId` fields for structured bidirectional communication.386. Implement room/channel subscription logic allowing clients to join and leave named channels with server-side membership tracking.397. Add heartbeat ping/pong mechanism with configurable interval (default 30s) and timeout detection to clean up stale connections.408. Configure Redis pub/sub adapter for horizontal scaling so messages broadcast from any server instance reach all connected clients across the cluster.419. Write connection lifecycle tests covering connect, authenticate, subscribe, message exchange, reconnect, and graceful disconnect scenarios.4243See `${CLAUDE_SKILL_DIR}/references/implementation.md` for the full implementation guide.4445## Output4647- `${CLAUDE_SKILL_DIR}/src/ws/server.js` - WebSocket server setup and upgrade handling48- `${CLAUDE_SKILL_DIR}/src/ws/handlers/` - Per-message-type handler functions49- `${CLAUDE_SKILL_DIR}/src/ws/rooms.js` - Room/channel subscription management50- `${CLAUDE_SKILL_DIR}/src/ws/registry.js` - Active connection tracking registry51- `${CLAUDE_SKILL_DIR}/src/ws/heartbeat.js` - Ping/pong keepalive logic52- `${CLAUDE_SKILL_DIR}/src/ws/adapters/redis.js` - Redis pub/sub adapter for scaling53- `${CLAUDE_SKILL_DIR}/tests/ws/` - WebSocket connection and messaging tests5455## Error Handling5657| Error | Cause | Solution |58|-------|-------|----------|59| 401 during upgrade | JWT token missing or expired in handshake query/headers | Reject upgrade with HTTP 401 before WebSocket protocol switch completes |60| 1008 Policy Violation | Client sends malformed message or violates protocol | Send close frame with code 1008 and human-readable reason; log violation |61| 1006 Abnormal Closure | Network interruption without close handshake | Detect via heartbeat timeout; clean up connection registry; notify room members |62| Memory leak | Connection registry grows unbounded from stale entries | Implement heartbeat-based cleanup sweep every 60s; enforce max connections per server |63| Message storm | Single client flooding messages beyond acceptable rate | Apply per-connection message rate limiting; disconnect abusive clients with 1008 |6465Refer to `${CLAUDE_SKILL_DIR}/references/errors.md` for comprehensive error patterns.6667## Examples6869**Chat application**: Multi-room chat server where clients join named rooms, receive member presence updates, and see real-time message delivery with typing indicators via separate message types.7071**Live dashboard**: Server pushes metric updates to subscribed dashboard clients every second, with initial state snapshot on connection and incremental deltas thereafter.7273**Collaborative editing**: Operational transformation relay server that receives edit operations from clients, transforms against concurrent operations, and broadcasts resolved changes to all document subscribers.7475See `${CLAUDE_SKILL_DIR}/references/examples.md` for additional examples.7677## Resources7879- RFC 6455 The WebSocket Protocol80- Socket.IO documentation: https://socket.io/docs/v4/81- `ws` library: https://github.com/websockets/ws82- Redis pub/sub for WebSocket scaling patterns
jeremylongshore