Skip to content
Skills Library
Programming · Building & coding

websocket-builder

/websocket-builder

When the user wants to build real-time features using WebSockets. Use when the user mentions "WebSocket," "real-time," "live updates," "socket," "ws," "push notifications," "live chat," "streaming data," or "bidirectional communication." Covers server setup, room management, authentication, reconnection handling, and scaling with Redis pub/sub. For data persistence, see realtime-database.

Repository
skills ↗
Licence
Apache-2.0
Last repository change
25.10.2026

Assessment and security

100/ 100Class: good
Format25 / 25
Frontmatter with name and description, valid name, description up to 1,024 characters, name matching the folder.
Discoverability25 / 25
Description explains when to use the skill, has a reasonable length and uses third person.
Content35 / 35
At least 150 words and at most 500 lines, headings, step lists, examples or code.
Hygiene15 / 15
No placeholders such as TODO, no Windows paths, with a licence.
Riskno signals detected in the scan
Files in this package
2
Scripts
0
HTML comments
0
URLs in SKILL.md
1
Deprecation

No signals detected. Repository changed on 25.10.2026, without references to retired models or APIs.

Licence

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

What it does and when to use it

When the user wants to build real-time features using WebSockets. Use when the user mentions "WebSocket," "real-time," "live updates," "socket," "ws," "push notifications," "live chat," "streaming data," or "bidirectional communication." Covers server setup, room management, authentication, reconnection handling, and scaling with Redis pub/sub. For data persistence, see realtime-database.

Triggers from the description

WebSocket,real-time,live updates,socket,ws,push notifications,live chat,streaming data,
Original author description

When the user wants to build real-time features using WebSockets. Use when the user mentions "WebSocket," "real-time," "live updates," "socket," "ws," "push notifications," "live chat," "streaming data," or "bidirectional communication." Covers server setup, room management, authentication, reconnection handling, and scaling with Redis pub/sub. For data persistence, see realtime-database.

How it works

  1. Overview
  2. Instructions
  3. Examples
  4. Guidelines
Original SKILL.md headings · 149 lines, 882 words
SKILL.md preview
---
name: websocket-builder
description: >-
  When the user wants to build real-time features using WebSockets. Use when the
  user mentions "WebSocket," "real-time," "live updates," "socket," "ws," "push
  notifications," "live chat," "streaming data," or "bidirectional communication."
  Covers server setup, room management, authentication, reconnection handling,
  and scaling with Redis pub/sub. For data persistence, see realtime-database.
license: Apache-2.0
compatibility: "Node.js 18+, Python 3.9+, or Go 1.21+"
metadata:
  author: terminal-skills
  version: "1.1.0"
  category: development
  tags: "websocket, real-time, backend, chat"
---

# WebSocket Builder

## Overview

Builds production-ready WebSocket servers for real-time features — chat, live dashboards, collaborative editing, notifications. Handles the hard parts: authentication during handshake, room/channel management, connection lifecycle, automatic reconnection, message ordering, and horizontal scaling via Redis pub/sub.

## Instructions

### 1. Server Setup

When setting up a WebSocket server:

- Attach to existing HTTP server (share the port)
- Use a mature library: `ws` for Node.js, `websockets` for Python, `gorilla/websocket` for Go
- Implement heartbeats: ping every 30 s and terminate any socket that has not answered the previous ping (the pattern in the `ws` README). Browsers answer pings automatically
- Set `maxPayload` explicitly. `ws` defaults to 100 MiB (104857600 bytes), not 64 KB: `new WebSocketServer({ noServer: true, maxPayload: 64 * 1024 })`
- Add connection limits per user (default: 5 concurrent connections)

### 2. Authentication

Authenticate during the WebSocket handshake, not after. The browser `WebSocket` API cannot set an `Authorization` header, so use one of these:

- **Cookie**: the session cookie is sent automatically on the upgrade request. Use this for same-site apps.
- **Short-lived token**: the app gets a JWT that expires in about 60 seconds from an authenticated endpoint and connects with `wss://host/ws?token=...`. Query strings end up in proxy and access logs, so never put a long-lived token there.

The server validates before it upgrades. `ws` documents `verifyClient` as discouraged, so do the check in the `upgrade` handler, as the `ws` README's client-authentication example does:

```javascript
import { createServer } from 'http';
import jwt from 'jsonwebtoken';
import { WebSocketServer } from 'ws';

const publicKey = process.env.JWT_PUBLIC_KEY; // PEM, from the secret store
const server = createServer();
const wss = new WebSocketServer({ noServer: true, maxPayload: 64 * 1024 });

wss.on('connection', (ws, req, user) => {
  ws.on('error', console.error);
  ws.on('message', (data) => {
    // Parse the JSON envelope and route by `event` (see Event Routing below)
  });
});

server.on('upgrade', (req, socket, head) => {
  socket.on('error', () => {}); // ignore resets before the upgrade completes
  let user;
  try {
    const token = new URL(req.url, 'http://localhost').searchParams.get('token') ?? '';
    user = jwt.verify(token, publicKey, { algorithms: ['RS256'], issuer: 'app' });
  } catch {
    socket.write('HTTP/1.1 401 Unauthorized\r\nConnection: close\r\n\r\n');
    socket.destroy();
    return;
  }
  wss.handleUpgrade(req, socket, head, (ws) => wss.emit('connection', ws, req, user));
});

server.listen(8080);
```

A client that sends no token gets `401` and the socket is closed before any frame is exchanged. Do NOT accept auth via a post-connection message — the connection is already open and resources allocated.

### 3. Room/Channel Management

```
RoomManager:
  join(socketId, roomId) — Add socket to room, notify members
  leave(socketId, roomId) — Remove socket, notify members
  broadcast(roomId, event, data, excludeSocketId?) — Send to all in room
  getMembers(roomId) — List connected user IDs
  getUserRooms(socketId) — List rooms for a socket

On connect: auto-join user's channel rooms from database
On disconnect: leave all rooms, broadcast presence update
```

### 4. Event Routing

Use a message format with event types:

```json
{ "event": "message.send", "data": { "channelId": "ch_1", "content": "Hello" }, "id": "client-uuid" }
```

Route events to handlers:

```
eventHandlers = {
  "message.send": handleMessageSend,
  "message.edit": handleMessageEdit,
  "typing.start": handleTypingStart,
  "presence.heartbeat": handleHeartbeat
}
```

Always include a client-generated `id` for idempotency and acknowledgment.

### 5. Scaling with Redis Pub/Sub

For multi-server deployments:

```
1. Each server subscribes to Redis channels matching room IDs
2. On broadcast: publish to Redis channel instead of local-only broadcast
3. Each server receives the publish and forwards to local sockets in that room
4. With Socket.IO, use `@socket.io/redis-adapter`. It works only with Socket.IO. With raw `ws`, subscribe with ioredis directly, using a dedicated subscriber connection: a connection in subscribe mode cannot run other commands
```

### 6. Reconnection Protocol

```
Client-side:
  1. On disconnect: attempt reconnect with exponential backoff (1s, 2s, 4s, max 30s)
  2. On reconnect: send last_event_id to server
  3. Server replays missed events since that ID
  4. Client merges with local state, deduplicating by event ID

Server-side:
  1. Keep recent events in Redis sorted set (TTL: 1 hour)
  2. On reconnect with last_event_id: return all events after that ID
  3. If ID is too old (beyond retention): send full state refresh
```

## Examples

### Example 1: Chat WebSocket Server (Node.js)

**Prompt**: "Set up a WebSocket server for my Express app with rooms and JWT auth"

**Output**: Server with authenticated connections, room manager, event routing, ping/pong heartbeats, and reconnection support. Files: `ws/server.ts`, `ws/rooms.ts`, `ws/handlers/`, `ws/middleware/auth.ts`.

### Example 2: Live Dashboard (Python)

**Prompt**: "I need real-time updates for a monitoring dashboard. FastAPI backend, 500 concurrent viewers."

**Output**: WebSocket endpoint with broadcast-only channels (viewers don't send), Redis pub/sub for horizontal scaling, connection pooling, and automatic cleanup. Files: `realtime/server.py`, `realtime/broadcaster.py`, `realtime/redis_pubsub.py`.

## Guidelines

- **Always authenticate at handshake** — never after connection is open, and never with a long-lived token in the URL
- **Pin the JWT algorithm** — pass `algorithms` to `jwt.verify` so a token cannot pick its own algorithm
- **Use binary frames** for large payloads (images, files) — text frames for JSON
- **Implement backpressure** — if a client can't keep up, buffer then disconnect
- **Log connection lifecycle** — connect, disconnect, error, room join/leave (debugging is hard without this)
- **Test with connection drops** — kill connections mid-message to verify recovery
- **Set idle timeouts** — disconnect clients that stop sending heartbeats
- **Never trust client input** — validate every message against expected schema
Files in this package (2)
  • SKILL.md 7 KB
  • _scores.json 2 KB

Versions

The database has no other skills named websocket-builder.

Database snapshot: 13.11.2026 · package version 1727e7d88565 (SHA-256 digest of the entire package)

Downloads in the last 30 days: 0 · ranking

Report a problem with this skill: harmful content, incorrect descriptions or an author’s removal request.

Similar skills

  • 100websocket-engineer
    Use when building real-time communication systems with WebSockets or Socket.IO. Invoke for bidirectional messaging, horizontal scaling with Redis, presence tracking, room management.
  • 100websocket-engineer
    Use when building real-time communication systems with WebSockets or Socket.IO. Invoke for bidirectional messaging, horizontal scaling with Redis, presence tracking, room management.
  • 100realtime-websocket-patterns
    Implement real-time features with WebSockets, Server-Sent Events, and long polling. Covers connection management, room-based messaging, presence tracking, and scaling strategies. Triggers on WebSocket implementation, real-time communication, or live update feature requests.
  • 80role-fullstack:real-time-features
    Implement real-time features using WebSockets (Socket.io, ws), Server-Sent Events (SSE), Supabase Realtime, Firebase, or Pusher. Covers presence indicators, live cursors, CRDT-based collaborative editing (Yjs, Automerge), notifications with offline delivery, chat with optimistic…
  • 100socketio
    Socket.IO is a Node.js library for bidirectional, event-based real-time communication between browsers (or other clients) and a server, with WebSocket transport, HTTP long-polling fallback, automatic reconnection, rooms and namespaces. Use when a user asks to build a chat, live…
  • 100bun-websocket-server
    This skill should be used when the user asks about "WebSocket in Bun", "real-time communication", "Bun.serve websocket", "ws server", "socket connections", "pub/sub", "broadcasting messages", "WebSocket upgrade", or building real-time applications with Bun.

Feedback and reports

Your message goes to Bartosz Sokoliński. An email address is needed only for a reply. See the privacy policy.