Files
skills/public/protocols-websocket-protocols.html
zeekay 747dafba10 Register WebMCP tools on every page, and name each page's twin from site.py
Every page now loads /webmcp.js, scripts/webmcp.ts with its types
stripped (npm run webmcp). Where the browser has document.modelContext
it registers two read-only tools: search_skills over the published
skills index, and get_skill, which returns a skill's markdown checked
against the index digest. The markdown alternate link moves from
build.py to site.py, so CI holds every page to it.

The API catalog gains the site itself (llms.txt and the skills index)
and hanzo.ai/agents; the live discovery check now fetches every
catalog link. tests/site.mjs drives the tools through a recording
modelContext, and checks a browser without one loads clean.
2026-10-26 20:57:05 -07:00

662 lines
32 KiB
HTML

<!doctype html>
<html lang="en"><head>
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
<title>protocols-websocket-protocols</title>
<meta name="color-scheme" content="dark">
<style>
/* Committed to one visual world: a dark instrument panel. No light variant —
the dot field and the hairline rules only read on black, and a naive
inversion would wash both out. Every colour is painted explicitly so the page
never borrows a host background. */
@font-face{font-family:'Zen';src:url('/fonts/Zen-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen';src:url('/fonts/Zen-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Variable.woff2') format('woff2');font-weight:100 900;font-style:normal;font-display:swap}
@font-face{font-family:'Zen Mono';src:url('/fonts/ZenMono-Italic-Variable.woff2') format('woff2');font-weight:100 900;font-style:italic;font-display:swap}
@font-face{font-family:'Zen Pixel Square';src:url('/fonts/ZenPixel-Square.woff2') format('woff2');font-style:normal;font-display:swap}
:root{
--ink:#f4f4f2; --soft:#9c9c98; --faint:#6a6a66; --ground:#000; --panel:#0a0a0a;
--line:#232323; --line-hi:#3a3a3a; --accent:#f4f4f2;
--font-zen-sans:'Zen',-apple-system,BlinkMacSystemFont,"Segoe UI",Helvetica,Arial,sans-serif;
--font-zen-mono:'Zen Mono',ui-monospace,"SF Mono",SFMono-Regular,Menlo,Consolas,monospace;
--font-zen-pixel-square:'Zen Pixel Square',monospace;
--mono:var(--font-zen-mono);
--sans:var(--font-zen-sans);
/* Controls are pills and surfaces are soft, as on hanzo.ai. */
--r:999px; --r-soft:14px;
}
*{box-sizing:border-box}
html{-webkit-text-size-adjust:100%}
body{margin:0;background:var(--ground);color:var(--ink);font-family:var(--sans);
font-size:16px;line-height:1.65;-webkit-font-smoothing:antialiased}
.wrap{max-width:60rem;margin:0 auto;padding:0 1.75rem}
/* The dot field. A halftone made of one repeating radial-gradient, faded out
along the diagonal by a mask so it reads as a wave rather than wallpaper. */
/* No overflow clip here: the dot field is inset to the box already, and a clip
would cut off the copy-prompt menu. */
.hero{position:relative;border-bottom:1px solid var(--line)}
.hero::before{content:"";position:absolute;inset:0;
background-image:radial-gradient(var(--line-hi) 1px, transparent 1px);
background-size:7px 7px;
-webkit-mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
mask-image:linear-gradient(115deg,#000 0%,rgba(0,0,0,.55) 38%,transparent 72%);
pointer-events:none}
.hero .wrap{position:relative;padding-top:5.5rem;padding-bottom:4rem}
nav{border-bottom:1px solid var(--line)}
nav .in{max-width:60rem;margin:0 auto;padding:1.1rem 1.75rem;display:flex;
justify-content:space-between;align-items:center;gap:1rem}
.brand{font-family:var(--mono);font-size:.85rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--ink);text-decoration:none;
display:inline-flex;align-items:center;gap:.6rem}
.brand i{font-style:normal;color:var(--faint)}
.mark{width:1.15em;height:1.15em;display:block;flex:0 0 auto}
nav a.up{font-family:var(--mono);font-size:.72rem;letter-spacing:.14em;
text-transform:uppercase;color:var(--soft);text-decoration:none}
nav a.up:hover{color:var(--ink)}
h1{font-family:var(--mono);font-size:clamp(2rem,5.4vw,3.4rem);line-height:1.12;
letter-spacing:-.02em;margin:0 0 1.1rem;font-weight:500;text-wrap:balance}
h1 em{font-style:normal;color:var(--faint)}
.lede{color:var(--soft);font-size:1.05rem;max-width:52ch;margin:0 0 2.25rem}
.btns{display:flex;flex-wrap:wrap;gap:.7rem;margin:0 0 .5rem;align-items:center}
.btn{display:inline-flex;align-items:center;gap:.5rem;font-family:var(--mono);
font-size:.72rem;letter-spacing:.14em;text-transform:uppercase;
padding:.8rem 1.4rem;border:1px solid var(--line-hi);border-radius:var(--r);
color:var(--ink);text-decoration:none;background:transparent;cursor:pointer;
line-height:1.2;font-weight:400}
.btn:hover{background:#141414;text-decoration:none;border-color:var(--soft)}
.btn.solid{background:var(--ink);color:#000;border-color:var(--ink)}
.btn.solid:hover{background:#d8d8d4}
.btn .chev{width:.7em;height:.7em;flex:0 0 auto;transition:transform .15s ease}
.btn[aria-expanded="true"] .chev{transform:rotate(180deg)}
/* Copy-prompt selector. Each row copies the prompt for its own target. */
.copy{position:relative;display:inline-flex}
.menu{position:absolute;top:calc(100% + .5rem);left:0;z-index:20;min-width:21rem;
background:var(--panel);border:1px solid var(--line-hi);border-radius:var(--r-soft);
padding:.4rem;display:flex;flex-direction:column;
box-shadow:0 12px 32px rgba(0,0,0,.75)}
.menu[hidden]{display:none}
.mi{display:flex;align-items:center;gap:.7rem;width:100%;text-align:left;
padding:.62rem .8rem;border:0;border-radius:calc(var(--r-soft) - .35rem);
background:transparent;color:var(--ink);font-family:var(--mono);font-size:.76rem;
letter-spacing:.04em;text-decoration:none;cursor:pointer;line-height:1.3;
white-space:nowrap}
.mi:hover,.mi:focus-visible{background:#181818;outline:none}
.mi .mark{width:1.05rem;height:1.05rem;color:var(--soft)}
.mi:hover .mark{color:var(--ink)}
.mi u{margin-left:auto;color:var(--faint);text-decoration:none;font-size:.68rem;
letter-spacing:.1em;text-transform:uppercase}
/* Works-with bar: one scrolling row, name and mark per agent. */
.strip{border-bottom:1px solid var(--line);background:var(--panel)}
.strip .in{max-width:60rem;margin:0 auto;padding:.9rem 1.75rem;display:flex;
align-items:center;gap:1.25rem;font-family:var(--mono);font-size:.72rem;
letter-spacing:.1em;text-transform:uppercase;color:var(--faint)}
.strip b{color:var(--soft);font-weight:400;flex:0 0 auto;
border-right:1px solid var(--line);padding-right:1.25rem;align-self:stretch;
display:flex;align-items:center}
.bar{display:flex;align-items:center;gap:.5rem;flex:1 1 auto;min-width:0;
overflow-x:auto;scrollbar-width:none;scroll-snap-type:x proximity;
-webkit-overflow-scrolling:touch;
-webkit-mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent);
mask-image:linear-gradient(90deg,#000 calc(100% - 3rem),transparent)}
.bar::-webkit-scrollbar{display:none}
.agent{display:inline-flex;align-items:center;gap:.45rem;flex:0 0 auto;
padding:.4rem .85rem;border:1px solid var(--line);border-radius:var(--r);
color:var(--soft);white-space:nowrap;scroll-snap-align:start;
text-decoration:none;background:var(--ground)}
.agent:hover{color:var(--ink);border-color:var(--line-hi);text-decoration:none}
.agent .mark{width:.95rem;height:.95rem}
h2{font-family:var(--mono);font-size:1.1rem;letter-spacing:-.01em;margin:2.75rem 0 .75rem;font-weight:500}
h3{font-size:1rem;margin:2rem 0 .5rem;font-weight:600}
h4,h5,h6{font-size:.94rem;margin:1.5rem 0 .5rem;font-weight:600}
p{margin:0 0 1rem;max-width:70ch}
ul,ol{margin:0 0 1rem;padding-left:1.35rem;max-width:70ch}
li{margin:.22rem 0}
a{color:var(--ink);text-decoration:underline;text-underline-offset:3px;
text-decoration-color:var(--line-hi)}
a:hover{text-decoration-color:var(--ink)}
a:focus-visible{outline:1px solid var(--ink);outline-offset:3px}
code{font-family:var(--mono);font-size:.85em;background:var(--panel);
border:1px solid var(--line);border-radius:5px;padding:.1em .36em}
pre{background:var(--panel);border:1px solid var(--line);padding:1rem 1.1rem;
border-radius:var(--r-soft);overflow-x:auto;margin:0 0 1.25rem}
pre code{background:none;border:0;padding:0;font-size:.82rem;line-height:1.7}
blockquote{margin:0 0 1rem;padding-left:1rem;border-left:1px solid var(--line-hi);color:var(--soft)}
hr{border:0;border-top:1px solid var(--line);margin:2.5rem 0}
table{border-collapse:collapse;width:100%;margin:0 0 1.25rem;font-size:.92rem;
display:block;overflow-x:auto}
th,td{border:1px solid var(--line);padding:.5rem .7rem;text-align:left}
.curl{display:block;background:var(--panel);border:1px solid var(--line);
border-radius:var(--r-soft);padding:.95rem 1.1rem;font-family:var(--mono);
font-size:.8rem;color:var(--soft);overflow-x:auto;margin:0 0 2.5rem;
white-space:pre;line-height:1.9}
.curl b{color:var(--ink);font-weight:400}
.curl i{font-style:normal;color:var(--faint)}
/* index */
#q{width:100%;padding:.85rem 1.2rem;font-family:var(--mono);font-size:.85rem;color:var(--ink);
background:var(--panel);border:1px solid var(--line);border-radius:var(--r);margin:0 0 .6rem}
#q::placeholder{color:var(--faint);text-transform:uppercase;letter-spacing:.1em;font-size:.72rem}
#q:focus{outline:none;border-color:var(--soft)}
#count{color:var(--faint);font-family:var(--mono);font-size:.72rem;letter-spacing:.1em;
text-transform:uppercase;margin:0 0 2rem}
.cat{margin:2.5rem 0 .5rem;font-family:var(--mono);font-size:.7rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);border-bottom:1px solid var(--line);
padding-bottom:.45rem}
.row{display:block;padding:.6rem .9rem;margin:0 -.9rem;border-bottom:1px solid var(--line);
border-radius:var(--r-soft);text-decoration:none}
.row:hover{background:#0a0a0a}
.nm{font-family:var(--mono);font-size:.84rem;color:var(--ink);display:block}
.ds{color:var(--soft);font-size:.9rem;display:block;margin-top:.12rem}
footer{margin-top:4rem;padding:2rem 0 4rem;border-top:1px solid var(--line);
color:var(--faint);font-size:.85rem}
footer a{color:var(--soft)}
.fmap{display:grid;gap:1.75rem;grid-template-columns:repeat(auto-fit,minmax(11rem,1fr));
margin:0 0 2rem;font-size:.85rem}
.fmap b{display:block;font-family:var(--mono);font-size:.68rem;letter-spacing:.16em;
text-transform:uppercase;color:var(--faint);font-weight:400;margin:0 0 .6rem;
border-bottom:1px solid var(--line);padding-bottom:.4rem}
.fmap a{display:inline-block;color:var(--ink);text-decoration:none;margin:.3rem .35rem 0 0}
.fmap a:hover{text-decoration:underline}
.fmap div{color:var(--faint);line-height:1.5}
.fend{border-top:1px solid var(--line);padding-top:1.25rem;font-size:.82rem}
@media (max-width:640px){
.hero .wrap{padding-top:3.25rem;padding-bottom:2.75rem}
.btns{gap:.5rem}
.btn{padding:.75rem 1.15rem;font-size:.68rem}
.copy,.copy .btn{width:100%;justify-content:center}
.menu{left:0;right:0;min-width:0}
.strip .in{flex-direction:column;align-items:flex-start;gap:.6rem;padding:.9rem 1.75rem}
.strip b{border-right:0;padding-right:0}
.bar{width:100%}
}
</style>
<link rel="icon" href="/favicon.svg">
<link rel="canonical" href="https://hanzoskills.com/protocols-websocket-protocols">
<link rel="alternate" type="text/markdown" href="/protocols-websocket-protocols.md">
<script type="module" src="/webmcp.js"></script>
</head>
<!-- Reading this with a machine? Every page here is also plain markdown.
This one: https://hanzoskills.com/protocols-websocket-protocols.md
Index: https://hanzoskills.com/llms.txt
Corpus: https://hanzoskills.com/all.md
Append .md to any path for the markdown twin. -->
<body>
<nav><div class="in">
<a class="brand" href="/"><svg class="mark" viewBox="0 0 67 67" fill="currentColor" aria-hidden="true"><path d="M22.21 67V44.6369H0V67H22.21Z"/><path d="M66.7038 22.3184H22.2534L0.0878906 44.6367H44.4634L66.7038 22.3184Z"/><path d="M22.21 0H0V22.3184H22.21V0Z"/><path d="M66.7198 0H44.5098V22.3184H66.7198V0Z"/><path d="M66.7198 67V44.6369H44.5098V67H66.7198Z"/></svg> HANZO<i>SKILLS</i></a>
<a class="up" href="/">All skills</a>
</div></nav>
<div class="wrap">
<h1>protocols-websocket-protocols</h1><p class="lede">WebSocket protocol implementation, scaling, and production deployment</p><h1>WebSocket Protocols</h1>
<p><strong>Scope</strong>: WebSocket protocol (RFC 6455), connection management, load balancing, scaling strategies, security <strong>Lines</strong>: ~400 <strong>Last Updated</strong>: 2025-10-27</p>
<h2>When to Use This Skill</h2>
<p>Activate this skill when:</p>
<ul><li>Implementing WebSocket servers from scratch</li><li>Designing real-time bidirectional communication systems</li><li>Scaling WebSocket applications horizontally</li><li>Configuring load balancers for WebSocket traffic (nginx, HAProxy)</li><li>Implementing authentication and authorization for WebSocket connections</li><li>Setting up heartbeat and connection health monitoring</li><li>Deploying production WebSocket infrastructure</li><li>Troubleshooting WebSocket connection issues</li><li>Optimizing WebSocket performance and throughput</li></ul>
<h2>Core Concepts</h2>
<h3>WebSocket Protocol</h3>
<p><strong>WebSocket</strong> (RFC 6455): Full-duplex communication protocol over a single TCP connection.</p>
<p><strong>Key characteristics</strong>:</p>
<ul><li><strong>Upgrade from HTTP</strong>: Starts as HTTP/1.1 request, upgrades to WebSocket protocol</li><li><strong>Persistent connection</strong>: Long-lived connection (not request-response)</li><li><strong>Bidirectional</strong>: Both client and server can send messages independently</li><li><strong>Low overhead</strong>: 2-byte frame header (vs HTTP headers)</li><li><strong>Frame-based</strong>: Messages sent as frames (text, binary, control)</li><li><strong>Built-in ping/pong</strong>: Connection health checking</li></ul>
<p><strong>Architecture</strong>:</p>
<pre><code>Client → HTTP Upgrade Request → Server
← 101 Switching Protocols ←
↔ WebSocket Frames (bidirectional) ↔</code></pre>
<hr>
<h2>WebSocket Handshake</h2>
<h3>Client Request</h3>
<pre><code class="lang-http">GET /chat HTTP/1.1
Host: server.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
Sec-WebSocket-Version: 13
Origin: http://example.com</code></pre>
<p><strong>Required headers</strong>:</p>
<ul><li><code>Upgrade: websocket</code> - Request protocol upgrade</li><li><code>Connection: Upgrade</code> - Signals upgrade intent</li><li><code>Sec-WebSocket-Key</code> - Base64-encoded random 16-byte value</li><li><code>Sec-WebSocket-Version: 13</code> - WebSocket protocol version</li></ul>
<p><strong>Optional headers</strong>:</p>
<ul><li><code>Origin</code> - For CORS validation</li><li><code>Sec-WebSocket-Protocol</code> - Subprotocol negotiation</li><li><code>Sec-WebSocket-Extensions</code> - Extension negotiation (compression)</li></ul>
<h3>Server Response</h3>
<pre><code class="lang-http">HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=</code></pre>
<p><strong>Sec-WebSocket-Accept calculation</strong>:</p>
<pre><code class="lang-python">import base64
import hashlib
def compute_accept(key: str) -&gt; str:
GUID = &quot;258EAFA5-E914-47DA-95CA-C5AB0DC85B11&quot;
sha1 = hashlib.sha1((key + GUID).encode()).digest()
return base64.b64encode(sha1).decode()</code></pre>
<hr>
<h2>Frame Structure</h2>
<h3>Frame Format</h3>
<pre><code> 0 1 2 3
0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1 2 3 4 5 6 7 8 9 0 1
+-+-+-+-+-------+-+-------------+-------------------------------+
|F|R|R|R| opcode|M| Payload len | Extended payload length |
|I|S|S|S| (4) |A| (7) | (16/64) |
|N|V|V|V| |S| | (if payload len==126/127) |
| |1|2|3| |K| | |
+-+-+-+-+-------+-+-------------+ - - - - - - - - - - - - - - - +
| Extended payload length continued, if payload len == 127 |
+ - - - - - - - - - - - - - - - +-------------------------------+
| |Masking-key, if MASK set to 1 |
+-------------------------------+-------------------------------+
| Masking-key (continued) | Payload Data |
+-------------------------------- - - - - - - - - - - - - - - - +
: Payload Data continued ... :
+ - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - +
| Payload Data continued ... |
+---------------------------------------------------------------+</code></pre>
<p><strong>Opcodes</strong>:</p>
<ul><li><code>0x0</code> - Continuation frame</li><li><code>0x1</code> - Text frame (UTF-8)</li><li><code>0x2</code> - Binary frame</li><li><code>0x8</code> - Close frame</li><li><code>0x9</code> - Ping frame</li><li><code>0xA</code> - Pong frame</li></ul>
<hr>
<h2>Python Server Implementation</h2>
<h3>Basic Server (websockets library)</h3>
<pre><code class="lang-python">import asyncio
import websockets
import json
from typing import Set
class WebSocketServer:
def __init__(self, host: str = &quot;0.0.0.0&quot;, port: int = 8765):
self.host = host
self.port = port
self.clients: Set[websockets.WebSocketServerProtocol] = set()
async def register(self, websocket: websockets.WebSocketServerProtocol):
&quot;&quot;&quot;Register new client connection&quot;&quot;&quot;
self.clients.add(websocket)
print(f&quot;Client connected. Total clients: {len(self.clients)}&quot;)
async def unregister(self, websocket: websockets.WebSocketServerProtocol):
&quot;&quot;&quot;Unregister client connection&quot;&quot;&quot;
self.clients.discard(websocket)
print(f&quot;Client disconnected. Total clients: {len(self.clients)}&quot;)
async def broadcast(self, message: str, exclude=None):
&quot;&quot;&quot;Broadcast message to all clients except sender&quot;&quot;&quot;
if self.clients:
tasks = [
client.send(message)
for client in self.clients
if client != exclude
]
await asyncio.gather(*tasks, return_exceptions=True)
async def handler(self, websocket: websockets.WebSocketServerProtocol, path: str):
&quot;&quot;&quot;Handle individual client connection&quot;&quot;&quot;
await self.register(websocket)
try:
async for message in websocket:
# Parse message
try:
data = json.loads(message)
msg_type = data.get(&quot;type&quot;)
if msg_type == &quot;ping&quot;:
await websocket.send(json.dumps({&quot;type&quot;: &quot;pong&quot;}))
elif msg_type == &quot;broadcast&quot;:
await self.broadcast(message, exclude=websocket)
else:
await websocket.send(json.dumps({
&quot;type&quot;: &quot;echo&quot;,
&quot;data&quot;: data
}))
except json.JSONDecodeError:
await websocket.send(json.dumps({
&quot;type&quot;: &quot;error&quot;,
&quot;message&quot;: &quot;Invalid JSON&quot;
}))
except websockets.exceptions.ConnectionClosed:
pass
finally:
await self.unregister(websocket)
def run(self):
&quot;&quot;&quot;Start WebSocket server&quot;&quot;&quot;
start_server = websockets.serve(
self.handler,
self.host,
self.port,
ping_interval=30, # Send ping every 30 seconds
ping_timeout=10, # Wait 10 seconds for pong
max_size=10 * 1024 * 1024 # 10 MB max message size
)
print(f&quot;WebSocket server starting on ws://{self.host}:{self.port}&quot;)
asyncio.get_event_loop().run_until_complete(start_server)
asyncio.get_event_loop().run_forever()
if __name__ == &quot;__main__&quot;:
server = WebSocketServer()
server.run()</code></pre>
<h3>Python Client</h3>
<pre><code class="lang-python">import asyncio
import websockets
import json
async def client():
uri = &quot;ws://localhost:8765&quot;
async with websockets.connect(uri) as websocket:
# Send message
await websocket.send(json.dumps({
&quot;type&quot;: &quot;message&quot;,
&quot;data&quot;: &quot;Hello, server!&quot;
}))
# Receive response
response = await websocket.recv()
data = json.loads(response)
print(f&quot;Received: {data}&quot;)
# Ping/pong
await websocket.send(json.dumps({&quot;type&quot;: &quot;ping&quot;}))
pong = await websocket.recv()
print(f&quot;Ping response: {pong}&quot;)
asyncio.run(client())</code></pre>
<hr>
<h2>Load Balancing and Scaling</h2>
<h3>Sticky Sessions (Required)</h3>
<p>WebSocket connections are stateful and must stay with the same backend server.</p>
<p><strong>Why needed</strong>:</p>
<ul><li>Connection state stored on specific server</li><li>Can&#x27;t switch servers mid-connection</li><li>Load balancer must route all frames from same client to same backend</li></ul>
<p><strong>Implementation strategies</strong>:</p>
<ol><li><strong>IP-based</strong>: Route based on client IP</li><li><strong>Cookie-based</strong>: Set cookie during HTTP upgrade</li><li><strong>Connection ID</strong>: Use WebSocket key for routing</li></ol>
<h3>nginx Configuration</h3>
<pre><code class="lang-nginx">upstream websocket_backend {
# IP hash for sticky sessions
ip_hash;
server backend1.example.com:8080;
server backend2.example.com:8080;
server backend3.example.com:8080;
}
server {
listen 80;
server_name ws.example.com;
location /ws {
# WebSocket proxying
proxy_pass http://websocket_backend;
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection &quot;upgrade&quot;;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
# Timeouts (increase for long-lived connections)
proxy_connect_timeout 7d;
proxy_send_timeout 7d;
proxy_read_timeout 7d;
# Disable buffering
proxy_buffering off;
}
}</code></pre>
<h3>HAProxy Configuration</h3>
<pre><code class="lang-haproxy">frontend websocket_front
bind *:80
default_backend websocket_back
backend websocket_back
# Sticky session using source IP
balance source
# Health check
option httpchk GET /health
http-check expect status 200
# Timeouts for long-lived connections
timeout tunnel 3600s
server ws1 backend1.example.com:8080 check
server ws2 backend2.example.com:8080 check
server ws3 backend3.example.com:8080 check</code></pre>
<hr>
<h2>Horizontal Scaling with Redis Pub/Sub</h2>
<h3>Problem</h3>
<p>Load-balanced WebSocket servers need to communicate to broadcast messages.</p>
<p><strong>Example</strong>: User A connects to Server 1, User B connects to Server 2. When A sends a message, Server 1 needs to notify Server 2 to send to B.</p>
<h3>Solution: Redis Pub/Sub</h3>
<pre><code class="lang-python">import asyncio
import websockets
import redis
import json
from typing import Set
class ScalableWebSocketServer:
def __init__(self, host: str = &quot;0.0.0.0&quot;, port: int = 8765):
self.host = host
self.port = port
self.clients: Set[websockets.WebSocketServerProtocol] = set()
# Redis for pub/sub
self.redis_client = redis.Redis(host=&#x27;localhost&#x27;, port=6379, decode_responses=True)
self.pubsub = self.redis_client.pubsub()
self.pubsub.subscribe(&#x27;websocket_broadcast&#x27;)
async def register(self, websocket: websockets.WebSocketServerProtocol):
self.clients.add(websocket)
async def unregister(self, websocket: websockets.WebSocketServerProtocol):
self.clients.discard(websocket)
async def local_broadcast(self, message: str):
&quot;&quot;&quot;Broadcast to local clients only&quot;&quot;&quot;
if self.clients:
tasks = [client.send(message) for client in self.clients]
await asyncio.gather(*tasks, return_exceptions=True)
async def global_broadcast(self, message: str):
&quot;&quot;&quot;Broadcast to all servers via Redis&quot;&quot;&quot;
self.redis_client.publish(&#x27;websocket_broadcast&#x27;, message)
async def redis_listener(self):
&quot;&quot;&quot;Listen for Redis pub/sub messages&quot;&quot;&quot;
for message in self.pubsub.listen():
if message[&#x27;type&#x27;] == &#x27;message&#x27;:
data = message[&#x27;data&#x27;]
await self.local_broadcast(data)
async def handler(self, websocket: websockets.WebSocketServerProtocol, path: str):
await self.register(websocket)
try:
async for message in websocket:
# Broadcast to all servers
await self.global_broadcast(message)
except websockets.exceptions.ConnectionClosed:
pass
finally:
await self.unregister(websocket)
def run(self):
# Start Redis listener in background
asyncio.create_task(self.redis_listener())
start_server = websockets.serve(self.handler, self.host, self.port)
asyncio.get_event_loop().run_until_complete(start_server)
asyncio.get_event_loop().run_forever()</code></pre>
<hr>
<h2>Security</h2>
<h3>Authentication</h3>
<p><strong>Option 1: Token in URL</strong></p>
<pre><code class="lang-javascript">// Client
const token = &quot;user-auth-token&quot;;
const ws = new WebSocket(`wss://api.example.com/ws?token=${token}`);</code></pre>
<pre><code class="lang-python"># Server: Extract token from query params
async def handler(websocket, path):
from urllib.parse import urlparse, parse_qs
query = parse_qs(urlparse(path).query)
token = query.get(&#x27;token&#x27;, [None])[0]
if not verify_token(token):
await websocket.close(code=4001, reason=&quot;Invalid token&quot;)
return
# Continue with authenticated connection</code></pre>
<p><strong>Option 2: Auth message after connection</strong></p>
<pre><code class="lang-javascript">// Client
const ws = new WebSocket(&quot;wss://api.example.com/ws&quot;);
ws.onopen = () =&gt; {
ws.send(JSON.stringify({ type: &quot;auth&quot;, token: &quot;user-token&quot; }));
};</code></pre>
<pre><code class="lang-python"># Server: Validate auth message within timeout
async def handler(websocket, path):
try:
# Wait for auth message (5 second timeout)
auth_msg = await asyncio.wait_for(websocket.recv(), timeout=5.0)
data = json.loads(auth_msg)
if data.get(&#x27;type&#x27;) != &#x27;auth&#x27; or not verify_token(data.get(&#x27;token&#x27;)):
await websocket.close(code=4002, reason=&quot;Authentication failed&quot;)
return
# Authenticated, continue
except asyncio.TimeoutError:
await websocket.close(code=4003, reason=&quot;Auth timeout&quot;)
return</code></pre>
<h3>TLS/SSL (wss://)</h3>
<pre><code class="lang-python">import ssl
ssl_context = ssl.SSLContext(ssl.PROTOCOL_TLS_SERVER)
ssl_context.load_cert_chain(&#x27;/path/to/cert.pem&#x27;, &#x27;/path/to/key.pem&#x27;)
start_server = websockets.serve(
handler,
&quot;0.0.0.0&quot;,
8765,
ssl=ssl_context
)</code></pre>
<h3>Origin Validation</h3>
<pre><code class="lang-python">async def handler(websocket, path):
# Check Origin header
origin = websocket.request_headers.get(&#x27;Origin&#x27;)
allowed_origins = [&#x27;https://example.com&#x27;, &#x27;https://app.example.com&#x27;]
if origin not in allowed_origins:
await websocket.close(code=4004, reason=&quot;Invalid origin&quot;)
return</code></pre>
<hr>
<h2>Connection Management</h2>
<h3>Heartbeat (Ping/Pong)</h3>
<p><strong>Purpose</strong>: Detect dead connections and keep connections alive through proxies.</p>
<pre><code class="lang-python"># Server: websockets library handles ping/pong automatically
start_server = websockets.serve(
handler,
&quot;0.0.0.0&quot;,
8765,
ping_interval=30, # Send ping every 30 seconds
ping_timeout=10 # Close if no pong within 10 seconds
)
# Client: Browser WebSocket API handles pong automatically
# Manual ping/pong for application-level heartbeat:
async def heartbeat(websocket):
while True:
await asyncio.sleep(30)
try:
await websocket.send(json.dumps({&quot;type&quot;: &quot;ping&quot;}))
except:
break</code></pre>
<h3>Graceful Shutdown</h3>
<pre><code class="lang-python">import signal
class WebSocketServer:
def __init__(self):
self.server = None
self.clients = set()
async def shutdown(self):
&quot;&quot;&quot;Gracefully close all connections&quot;&quot;&quot;
print(&quot;Shutting down...&quot;)
# Close all client connections
close_tasks = [
client.close(code=1001, reason=&quot;Server shutting down&quot;)
for client in self.clients
]
await asyncio.gather(*close_tasks, return_exceptions=True)
# Stop server
self.server.close()
await self.server.wait_closed()
def run(self):
loop = asyncio.get_event_loop()
# Handle SIGTERM/SIGINT
def signal_handler():
loop.create_task(self.shutdown())
loop.add_signal_handler(signal.SIGTERM, signal_handler)
loop.add_signal_handler(signal.SIGINT, signal_handler)
self.server = loop.run_until_complete(
websockets.serve(self.handler, &quot;0.0.0.0&quot;, 8765)
)
loop.run_forever()</code></pre>
<hr>
<h2>Anti-Patterns</h2>
<p>❌ <strong>Not using sticky sessions</strong>: Clients randomly routed to different backends ✅ Use <code>ip_hash</code> (nginx) or <code>balance source</code> (HAProxy)</p>
<p>❌ <strong>No heartbeat/ping</strong>: Dead connections stay open, waste resources ✅ Enable <code>ping_interval</code> and <code>ping_timeout</code></p>
<p>❌ <strong>No authentication</strong>: Anyone can connect ✅ Verify tokens during handshake or within timeout</p>
<p>❌ <strong>Ignoring Origin header</strong>: CSRF vulnerability ✅ Validate Origin against allowed list</p>
<p>❌ <strong>Synchronous blocking code</strong>: Blocks event loop, kills performance ✅ Use <code>async</code>/<code>await</code> for all I/O operations</p>
<p>❌ <strong>No message size limit</strong>: Memory exhaustion attack ✅ Set <code>max_size</code> parameter</p>
<p>❌ <strong>No rate limiting</strong>: Message flooding ✅ Implement token bucket or connection limits</p>
<hr>
<h2>Level 3: Resources</h2>
<h3>Overview</h3>
<p>This skill includes comprehensive Level 3 resources for deep WebSocket protocol implementation and production deployment.</p>
<p><strong>Resources include</strong>:</p>
<ul><li><strong>REFERENCE.md</strong> (3,200+ lines): Complete technical reference covering WebSocket protocol, scaling, security</li><li><strong>3 executable scripts</strong>: Config validation, server testing, connection benchmarking</li><li><strong>9 production examples</strong>: Complete implementations across languages, frameworks, and deployment scenarios</li></ul>
<h3>Quick Start</h3>
<p><strong>1. Validate WebSocket server config</strong>:</p>
<pre><code class="lang-bash">cd skills/protocols/websocket-protocols/resources/scripts
./validate_websocket_config.py --config /etc/nginx/nginx.conf --check-websocket</code></pre>
<p><strong>2. Test WebSocket server</strong>:</p>
<pre><code class="lang-bash">./test_websocket_server.py --url ws://localhost:8080 --test-all --json</code></pre>
<p><strong>3. Benchmark connections</strong>:</p>
<pre><code class="lang-bash">./benchmark_websocket.py --url ws://localhost:8080 --connections 1000 --duration 60</code></pre>
<p><strong>4. Deploy examples</strong>:</p>
<pre><code class="lang-bash">cd ../examples/docker
docker-compose up -d</code></pre>
<p><strong>See REFERENCE.md for complete documentation.</strong></p>
<hr>
<p><strong>Last Updated</strong>: 2025-10-27 <strong>Format Version</strong>: 1.0 (Atomic)</p>
<footer>
<div class="fmap">
<div><b>Build</b>
<a href="https://hanzo.app">hanzo.app</a> app builder
<a href="https://hanzo.codes">hanzo.codes</a> code with an agent
<a href="https://hanzoskills.com">hanzoskills.com</a> what an agent reads</div>
<div><b>Run</b>
<a href="https://console.hanzo.ai">console.hanzo.ai</a> cloud console
<a href="https://api.hanzo.ai">api.hanzo.ai</a> the API</div>
<div><b>Account</b>
<a href="https://hanzo.id">hanzo.id</a> sign in
<a href="https://pay.hanzo.ai">pay.hanzo.ai</a> top up
<a href="https://billing.hanzo.ai">billing.hanzo.ai</a> invoices and usage</div>
<div><b>Company</b>
<a href="https://hanzo.ai">hanzo.ai</a> canonical
<a href="https://hanzo.ventures">hanzo.ventures</a> ventures</div>
</div>
<div class="fend"><a href="/protocols-websocket-protocols.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
</footer>
</div></body></html>