mirror of
https://github.com/hanzoai/skills.git
synced 2026-11-19 00:47:36 +00:00
hanzoskills.com/llms.txt now opens with the install line, the API reference index and the company index, so an agent that lands on any one of the three can find the rest. robots.txt claimed 537 documents while llms.txt counts 920. The number is gone from robots.txt; llms.txt derives it. public/ is regenerated from scripts/site.py, which it had fallen behind: the copy-prompt menu and agent bar were in the generator and not in the committed pages. tests/site.mjs passes against the result. Co-authored-by: Hanzo Dev <[email protected]>
662 lines
32 KiB
HTML
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="alternate" type="text/markdown" href="/protocols-websocket-protocols.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/protocols-websocket-protocols">
|
|
</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) -> str:
|
|
GUID = "258EAFA5-E914-47DA-95CA-C5AB0DC85B11"
|
|
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 = "0.0.0.0", port: int = 8765):
|
|
self.host = host
|
|
self.port = port
|
|
self.clients: Set[websockets.WebSocketServerProtocol] = set()
|
|
|
|
async def register(self, websocket: websockets.WebSocketServerProtocol):
|
|
"""Register new client connection"""
|
|
self.clients.add(websocket)
|
|
print(f"Client connected. Total clients: {len(self.clients)}")
|
|
|
|
async def unregister(self, websocket: websockets.WebSocketServerProtocol):
|
|
"""Unregister client connection"""
|
|
self.clients.discard(websocket)
|
|
print(f"Client disconnected. Total clients: {len(self.clients)}")
|
|
|
|
async def broadcast(self, message: str, exclude=None):
|
|
"""Broadcast message to all clients except sender"""
|
|
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):
|
|
"""Handle individual client connection"""
|
|
await self.register(websocket)
|
|
try:
|
|
async for message in websocket:
|
|
# Parse message
|
|
try:
|
|
data = json.loads(message)
|
|
msg_type = data.get("type")
|
|
|
|
if msg_type == "ping":
|
|
await websocket.send(json.dumps({"type": "pong"}))
|
|
elif msg_type == "broadcast":
|
|
await self.broadcast(message, exclude=websocket)
|
|
else:
|
|
await websocket.send(json.dumps({
|
|
"type": "echo",
|
|
"data": data
|
|
}))
|
|
except json.JSONDecodeError:
|
|
await websocket.send(json.dumps({
|
|
"type": "error",
|
|
"message": "Invalid JSON"
|
|
}))
|
|
except websockets.exceptions.ConnectionClosed:
|
|
pass
|
|
finally:
|
|
await self.unregister(websocket)
|
|
|
|
def run(self):
|
|
"""Start WebSocket server"""
|
|
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"WebSocket server starting on ws://{self.host}:{self.port}")
|
|
asyncio.get_event_loop().run_until_complete(start_server)
|
|
asyncio.get_event_loop().run_forever()
|
|
|
|
if __name__ == "__main__":
|
|
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 = "ws://localhost:8765"
|
|
|
|
async with websockets.connect(uri) as websocket:
|
|
# Send message
|
|
await websocket.send(json.dumps({
|
|
"type": "message",
|
|
"data": "Hello, server!"
|
|
}))
|
|
|
|
# Receive response
|
|
response = await websocket.recv()
|
|
data = json.loads(response)
|
|
print(f"Received: {data}")
|
|
|
|
# Ping/pong
|
|
await websocket.send(json.dumps({"type": "ping"}))
|
|
pong = await websocket.recv()
|
|
print(f"Ping response: {pong}")
|
|
|
|
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'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 "upgrade";
|
|
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 = "0.0.0.0", 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='localhost', port=6379, decode_responses=True)
|
|
self.pubsub = self.redis_client.pubsub()
|
|
self.pubsub.subscribe('websocket_broadcast')
|
|
|
|
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):
|
|
"""Broadcast to local clients only"""
|
|
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):
|
|
"""Broadcast to all servers via Redis"""
|
|
self.redis_client.publish('websocket_broadcast', message)
|
|
|
|
async def redis_listener(self):
|
|
"""Listen for Redis pub/sub messages"""
|
|
for message in self.pubsub.listen():
|
|
if message['type'] == 'message':
|
|
data = message['data']
|
|
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 = "user-auth-token";
|
|
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('token', [None])[0]
|
|
|
|
if not verify_token(token):
|
|
await websocket.close(code=4001, reason="Invalid token")
|
|
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("wss://api.example.com/ws");
|
|
ws.onopen = () => {
|
|
ws.send(JSON.stringify({ type: "auth", token: "user-token" }));
|
|
};</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('type') != 'auth' or not verify_token(data.get('token')):
|
|
await websocket.close(code=4002, reason="Authentication failed")
|
|
return
|
|
|
|
# Authenticated, continue
|
|
except asyncio.TimeoutError:
|
|
await websocket.close(code=4003, reason="Auth timeout")
|
|
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('/path/to/cert.pem', '/path/to/key.pem')
|
|
|
|
start_server = websockets.serve(
|
|
handler,
|
|
"0.0.0.0",
|
|
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('Origin')
|
|
allowed_origins = ['https://example.com', 'https://app.example.com']
|
|
|
|
if origin not in allowed_origins:
|
|
await websocket.close(code=4004, reason="Invalid origin")
|
|
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,
|
|
"0.0.0.0",
|
|
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({"type": "ping"}))
|
|
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):
|
|
"""Gracefully close all connections"""
|
|
print("Shutting down...")
|
|
|
|
# Close all client connections
|
|
close_tasks = [
|
|
client.close(code=1001, reason="Server shutting down")
|
|
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, "0.0.0.0", 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> |