WebSocket

Implement reliable WebSocket connections with proper reconnection, heartbeats, and scaling.

Security Scan

This is an instruction-only skill giving best-practice guidance for implementing WebSocket connections; its requirements and instructions are coherent with its stated purpose and it makes no unexpected system or credential demands.

Purpose & Capability

The SKILL.md content matches the name/description: reconnection, heartbeats, scaling, auth, proxy config and common mistakes for WebSockets. No unrelated environment variables, binaries, or install steps are requested.

Instruction Scope

Runtime instructions are developer guidance and do not direct the agent to read files, access credentials, call external endpoints, or transmit data. The examples (Nginx snippet, config values) are appropriate for the stated goal and scoped to WebSocket implementation concerns.

Install Mechanism

No install spec and no code files — instruction-only skills have minimal disk/network footprint. Nothing will be downloaded or written by the skill itself.

Credentials

The skill declares no required environment variables, credentials, or config paths; the guidance references typical auth patterns but does not request secrets or external keys.

Persistence & Privilege

always:false and default invocation settings mean the skill is not force-included and has no elevated persistence. It does not request to modify other skills or system-wide settings.

Assessment

This skill is instruction-only and appears low-risk: it provides best practices and configuration snippets for WebSocket implementations and does not request credentials or install code. Before installing, consider that (1) the agent may use these instructions to generate code or recommendations—always review any code it outputs before running it; (2) if a later version adds install steps or required env vars, re-evaluate those changes; and (3) because the skill is allowed to be invoked by the model, review outputs for safety (e.g., do not paste secrets into prompts). Overall this skill is coherent with its stated purpose.

Reconnection (Always Forget)

• Connections drop silently—TCP FIN may never arrive; don't assume onclose fires
• Exponential backoff: 1s, 2s, 4s, 8s... cap at 30s—prevents thundering herd on server recovery
• Add jitter: delay * (0.5 + Math.random())—prevents synchronized reconnection storms
• Track reconnection state—queue messages during reconnect, replay after
• Max retry limit then surface error to user—don't retry forever silently

Heartbeats (Critical)

• Ping/pong frames at protocol level—browser doesn't expose; use application-level ping
• Send ping every 30s, expect pong within 10s—no pong = connection dead, reconnect
• Server should ping too—detects dead clients, cleans up resources
• Idle timeout in proxies (60-120s typical)—heartbeat must be more frequent
• Don't rely on TCP keepalive—too infrequent, not reliable through proxies

Connection State

• readyState: 0=CONNECTING, 1=OPEN, 2=CLOSING, 3=CLOSED—check before sending
• Buffer messages while CONNECTING—send after OPEN
• bufferedAmount shows queued bytes—pause sending if backpressure building
• Multiple tabs = multiple connections—coordinate via BroadcastChannel or SharedWorker

Authentication

• Token in URL query: wss://host/ws?token=xxx—simple but logged in access logs
• First message auth: connect, send token, wait for ack—cleaner but more round trips
• Cookie auth: works if same origin—but no custom headers in WebSocket
• Reauthenticate after reconnect—don't assume previous session valid

Scaling Challenges

• WebSocket connections are stateful—can't round-robin between servers
• Sticky sessions: route by client ID to same server—or use Redis pub/sub for broadcast
• Each connection holds memory—thousands of connections = significant RAM
• Graceful shutdown: send close frame, wait for clients to reconnect elsewhere

Nginx/Proxy Config

proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection "upgrade";
proxy_read_timeout 3600s;

• Without these headers, upgrade fails—connection closes immediately
• proxy_read_timeout must exceed your ping interval—default 60s too short
• Load balancer health checks: separate HTTP endpoint, not WebSocket

Close Codes

• 1000: normal closure; 1001: going away (page close)
• 1006: abnormal (no close frame received)—usually network issue
• 1008: policy violation; 1011: server error
• 4000-4999: application-defined—use for auth failure, rate limit, etc.
• Always send close code and reason—helps debugging

Message Handling

• Text frames for JSON; binary frames for blobs/protobuf—don't mix without framing
• No guaranteed message boundaries in TCP—but WebSocket handles framing for you
• Order preserved per connection—messages arrive in send order
• Large messages may fragment—library handles reassembly; set max message size server-side

Security

• Validate Origin header on handshake—prevent cross-site WebSocket hijacking
• Same-origin policy doesn't apply—any page can connect to your WebSocket server
• Rate limit per connection—one client can flood with messages
• Validate every message—malicious clients can send anything after connecting

Common Mistakes

• No heartbeat—connection appears alive but is dead; messages go nowhere
• Reconnect without backoff—hammers server during outage, prolongs recovery
• Storing state only in connection—lost on reconnect; persist critical state externally
• Huge messages—blocks event loop; stream large data via chunking
• Not handling bufferedAmount—memory grows unbounded if client slower than server