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]>
740 lines
30 KiB
HTML
740 lines
30 KiB
HTML
<!doctype html>
|
|
<html lang="en"><head>
|
|
<meta charset="utf-8"><meta name="viewport" content="width=device-width,initial-scale=1">
|
|
<title>realtime-server-sent-events</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="/realtime-server-sent-events.md">
|
|
|
|
<link rel="icon" href="/favicon.svg">
|
|
<link rel="canonical" href="https://hanzoskills.com/realtime-server-sent-events">
|
|
</head>
|
|
<!-- Reading this with a machine? Every page here is also plain markdown.
|
|
This one: https://hanzoskills.com/realtime-server-sent-events.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>realtime-server-sent-events</h1><p class="lede">Scope: SSE protocol, event streams, automatic reconnection, and fallback strategies Lines: 343 Last Updated: 2025-10-18</p><h1>Server-Sent Events (SSE)</h1>
|
|
<p><strong>Scope</strong>: SSE protocol, event streams, automatic reconnection, and fallback strategies <strong>Lines</strong>: 343 <strong>Last Updated</strong>: 2025-10-18</p>
|
|
<h2>When to Use This Skill</h2>
|
|
<p>Use Server-Sent Events when you need:</p>
|
|
<ul><li><strong>Unidirectional streaming</strong>: Server pushes updates to client only</li><li><strong>Automatic reconnection</strong>: Built-in browser reconnection with Last-Event-ID</li><li><strong>Text-based data</strong>: JSON, plain text, or structured event streams</li><li><strong>HTTP compatibility</strong>: Works through most proxies and firewalls</li><li><strong>Simple implementation</strong>: Easier than WebSockets for one-way communication</li></ul>
|
|
<p><strong>Don't use</strong> when:</p>
|
|
<ul><li>Bidirectional communication needed (use WebSockets)</li><li>Binary data transmission required (use WebSockets)</li><li>Low latency critical (<100ms, use WebSockets)</li><li>Client needs to send frequent messages to server (use WebSockets)</li><li>IE11 support required without polyfills (use long polling)</li></ul>
|
|
<h2>Core Concepts</h2>
|
|
<h3>SSE Protocol</h3>
|
|
<pre><code>Client Server
|
|
| |
|
|
|-- GET /events ---------------->|
|
|
| Accept: text/event-stream |
|
|
| |
|
|
|<-- 200 OK --------------------|
|
|
| Content-Type: text/event- |
|
|
| stream |
|
|
| Cache-Control: no-cache |
|
|
| |
|
|
|<== Event Stream ===============|
|
|
| |
|
|
| data: message 1 |
|
|
| |
|
|
| data: message 2 |
|
|
| |</code></pre>
|
|
<p><strong>Key Features</strong>:</p>
|
|
<ul><li>Built on HTTP/1.1 (long-lived GET request)</li><li>Text-based protocol (UTF-8 encoded)</li><li>Automatic reconnection with exponential backoff</li><li>Event IDs for resuming from last received event</li><li>Multiple named event types</li></ul>
|
|
<h3>Event Format</h3>
|
|
<pre><code>event: message
|
|
id: 123
|
|
retry: 10000
|
|
data: {"text": "Hello"}
|
|
data: {"more": "data"}
|
|
</code></pre>
|
|
<p><strong>Fields</strong>:</p>
|
|
<ul><li><code>event</code>: Event type (default: "message")</li><li><code>id</code>: Event identifier for reconnection</li><li><code>retry</code>: Client reconnection time in milliseconds</li><li><code>data</code>: Event payload (can span multiple lines)</li><li>Empty line: Marks end of event</li></ul>
|
|
<h3>Connection Lifecycle</h3>
|
|
<pre><code>CONNECTING (0) → Initial connection or reconnecting
|
|
OPEN (1) → Connection established, receiving events
|
|
CLOSED (2) → Connection closed (will not reconnect)</code></pre>
|
|
<h2>Patterns</h2>
|
|
<h3>1. Basic Client Implementation</h3>
|
|
<pre><code class="lang-typescript">// TypeScript/JavaScript client
|
|
class SSEClient {
|
|
private eventSource: EventSource | null = null;
|
|
private url: string;
|
|
private listeners: Map<string, Set<(data: any) => void>> = new Map();
|
|
private reconnectAttempts = 0;
|
|
private maxReconnectAttempts = 5;
|
|
|
|
constructor(url: string) {
|
|
this.url = url;
|
|
}
|
|
|
|
connect(): Promise<void> {
|
|
return new Promise((resolve, reject) => {
|
|
try {
|
|
this.eventSource = new EventSource(this.url);
|
|
|
|
this.eventSource.onopen = () => {
|
|
console.log('SSE connected');
|
|
this.reconnectAttempts = 0;
|
|
resolve();
|
|
};
|
|
|
|
this.eventSource.onerror = (error) => {
|
|
console.error('SSE error:', error);
|
|
|
|
if (this.eventSource?.readyState === EventSource.CLOSED) {
|
|
this.handleDisconnect();
|
|
}
|
|
};
|
|
|
|
this.eventSource.onmessage = (event) => {
|
|
this.handleEvent('message', event.data);
|
|
};
|
|
} catch (error) {
|
|
reject(error);
|
|
}
|
|
});
|
|
}
|
|
|
|
on(eventType: string, handler: (data: any) => void) {
|
|
if (!this.listeners.has(eventType)) {
|
|
this.listeners.set(eventType, new Set());
|
|
|
|
// Register event listener with EventSource
|
|
if (this.eventSource && eventType !== 'message') {
|
|
this.eventSource.addEventListener(eventType, (event: MessageEvent) => {
|
|
this.handleEvent(eventType, event.data);
|
|
});
|
|
}
|
|
}
|
|
|
|
this.listeners.get(eventType)!.add(handler);
|
|
}
|
|
|
|
off(eventType: string, handler: (data: any) => void) {
|
|
this.listeners.get(eventType)?.delete(handler);
|
|
}
|
|
|
|
private handleEvent(eventType: string, data: string) {
|
|
const handlers = this.listeners.get(eventType);
|
|
if (!handlers) return;
|
|
|
|
let parsedData: any;
|
|
try {
|
|
parsedData = JSON.parse(data);
|
|
} catch {
|
|
parsedData = data;
|
|
}
|
|
|
|
handlers.forEach((handler) => {
|
|
try {
|
|
handler(parsedData);
|
|
} catch (error) {
|
|
console.error(`Error in ${eventType} handler:`, error);
|
|
}
|
|
});
|
|
}
|
|
|
|
private handleDisconnect() {
|
|
this.reconnectAttempts++;
|
|
|
|
if (this.reconnectAttempts <= this.maxReconnectAttempts) {
|
|
const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts - 1), 30000);
|
|
console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
|
|
|
|
setTimeout(() => {
|
|
this.connect().catch(console.error);
|
|
}, delay);
|
|
} else {
|
|
console.error('Max reconnection attempts reached');
|
|
}
|
|
}
|
|
|
|
close() {
|
|
this.eventSource?.close();
|
|
this.eventSource = null;
|
|
this.listeners.clear();
|
|
}
|
|
|
|
get readyState(): number {
|
|
return this.eventSource?.readyState ?? EventSource.CLOSED;
|
|
}
|
|
}
|
|
|
|
// Usage
|
|
const client = new SSEClient('/api/events');
|
|
await client.connect();
|
|
|
|
client.on('message', (data) => {
|
|
console.log('Default message:', data);
|
|
});
|
|
|
|
client.on('notification', (data) => {
|
|
console.log('Notification:', data);
|
|
});
|
|
|
|
client.on('update', (data) => {
|
|
console.log('Update:', data);
|
|
});</code></pre>
|
|
<h3>2. Server Implementation (Node.js/Express)</h3>
|
|
<pre><code class="lang-typescript">import express from 'express';
|
|
import { Request, Response } from 'express';
|
|
|
|
interface SSEConnection {
|
|
id: string;
|
|
res: Response;
|
|
lastEventId: number;
|
|
}
|
|
|
|
class SSEServer {
|
|
private connections: Map<string, SSEConnection> = new Map();
|
|
private eventCounter = 0;
|
|
|
|
setupRoutes(app: express.Application) {
|
|
app.get('/api/events', (req, res) => {
|
|
this.handleConnection(req, res);
|
|
});
|
|
}
|
|
|
|
private handleConnection(req: Request, res: Response) {
|
|
// Set SSE headers
|
|
res.setHeader('Content-Type', 'text/event-stream');
|
|
res.setHeader('Cache-Control', 'no-cache');
|
|
res.setHeader('Connection', 'keep-alive');
|
|
res.setHeader('X-Accel-Buffering', 'no'); // Disable nginx buffering
|
|
|
|
// Handle CORS if needed
|
|
res.setHeader('Access-Control-Allow-Origin', '*');
|
|
|
|
// Get last event ID for reconnection
|
|
const lastEventId = parseInt(req.headers['last-event-id'] as string || '0');
|
|
|
|
const connectionId = this.generateConnectionId();
|
|
const connection: SSEConnection = {
|
|
id: connectionId,
|
|
res,
|
|
lastEventId,
|
|
};
|
|
|
|
this.connections.set(connectionId, connection);
|
|
console.log(`Client ${connectionId} connected. Total: ${this.connections.size}`);
|
|
|
|
// Send initial connection event
|
|
this.sendEvent(connection, {
|
|
event: 'connected',
|
|
data: { connectionId, timestamp: Date.now() },
|
|
});
|
|
|
|
// Send missed events if reconnecting
|
|
if (lastEventId > 0) {
|
|
this.sendMissedEvents(connection, lastEventId);
|
|
}
|
|
|
|
// Handle client disconnect
|
|
req.on('close', () => {
|
|
this.connections.delete(connectionId);
|
|
console.log(`Client ${connectionId} disconnected. Total: ${this.connections.size}`);
|
|
});
|
|
|
|
// Keep connection alive with comments
|
|
const keepAliveInterval = setInterval(() => {
|
|
res.write(': keepalive\n\n');
|
|
}, 30000);
|
|
|
|
req.on('close', () => {
|
|
clearInterval(keepAliveInterval);
|
|
});
|
|
}
|
|
|
|
private sendEvent(connection: SSEConnection, event: {
|
|
event?: string;
|
|
id?: number;
|
|
data: any;
|
|
retry?: number;
|
|
}) {
|
|
const { res } = connection;
|
|
const { event: eventType = 'message', id, data, retry } = event;
|
|
|
|
try {
|
|
if (eventType) {
|
|
res.write(`event: ${eventType}\n`);
|
|
}
|
|
|
|
if (id !== undefined) {
|
|
res.write(`id: ${id}\n`);
|
|
}
|
|
|
|
if (retry !== undefined) {
|
|
res.write(`retry: ${retry}\n`);
|
|
}
|
|
|
|
const jsonData = typeof data === 'string' ? data : JSON.stringify(data);
|
|
const lines = jsonData.split('\n');
|
|
lines.forEach((line) => {
|
|
res.write(`data: ${line}\n`);
|
|
});
|
|
|
|
res.write('\n');
|
|
} catch (error) {
|
|
console.error('Error sending event:', error);
|
|
this.connections.delete(connection.id);
|
|
}
|
|
}
|
|
|
|
broadcast(event: { event?: string; data: any }) {
|
|
const eventId = ++this.eventCounter;
|
|
|
|
this.connections.forEach((connection) => {
|
|
this.sendEvent(connection, {
|
|
...event,
|
|
id: eventId,
|
|
});
|
|
});
|
|
}
|
|
|
|
sendToConnection(connectionId: string, event: { event?: string; data: any }) {
|
|
const connection = this.connections.get(connectionId);
|
|
if (connection) {
|
|
const eventId = ++this.eventCounter;
|
|
this.sendEvent(connection, {
|
|
...event,
|
|
id: eventId,
|
|
});
|
|
}
|
|
}
|
|
|
|
private sendMissedEvents(connection: SSEConnection, lastEventId: number) {
|
|
// In production, retrieve missed events from database or cache
|
|
// For demonstration, we'll send a synthetic event
|
|
this.sendEvent(connection, {
|
|
event: 'catchup',
|
|
data: { message: 'Caught up from event ' + lastEventId },
|
|
});
|
|
}
|
|
|
|
private generateConnectionId(): string {
|
|
return `conn_${Date.now()}_${Math.random().toString(36).substr(2, 9)}`;
|
|
}
|
|
}
|
|
|
|
// Usage
|
|
const app = express();
|
|
const sseServer = new SSEServer();
|
|
sseServer.setupRoutes(app);
|
|
|
|
// Broadcast to all clients
|
|
setInterval(() => {
|
|
sseServer.broadcast({
|
|
event: 'time',
|
|
data: { timestamp: Date.now() },
|
|
});
|
|
}, 5000);
|
|
|
|
app.listen(3000);</code></pre>
|
|
<h3>3. Authentication with SSE</h3>
|
|
<pre><code class="lang-typescript">// Client: Send auth token via query parameter or custom header
|
|
class AuthenticatedSSEClient extends SSEClient {
|
|
constructor(url: string, token: string) {
|
|
// Option 1: Token in query parameter
|
|
const authenticatedUrl = `${url}?token=${encodeURIComponent(token)}`;
|
|
super(authenticatedUrl);
|
|
}
|
|
}
|
|
|
|
// Server: Validate token before establishing connection
|
|
class AuthenticatedSSEServer extends SSEServer {
|
|
setupRoutes(app: express.Application) {
|
|
app.get('/api/events', this.authenticate, (req, res) => {
|
|
this.handleConnection(req, res);
|
|
});
|
|
}
|
|
|
|
private authenticate(req: Request, res: Response, next: express.NextFunction) {
|
|
const token = req.query.token as string || req.headers.authorization?.split(' ')[1];
|
|
|
|
if (!token) {
|
|
res.status(401).json({ error: 'Missing token' });
|
|
return;
|
|
}
|
|
|
|
if (!verifyToken(token)) {
|
|
res.status(403).json({ error: 'Invalid token' });
|
|
return;
|
|
}
|
|
|
|
// Attach user info to request
|
|
(req as any).userId = getUserIdFromToken(token);
|
|
next();
|
|
}
|
|
}</code></pre>
|
|
<h3>4. Fallback Pattern (Polyfill for Older Browsers)</h3>
|
|
<pre><code class="lang-typescript">// Polyfill using long polling for browsers without EventSource
|
|
class EventSourcePolyfill {
|
|
private url: string;
|
|
private listeners: Map<string, (event: MessageEvent) => void> = new Map();
|
|
private abortController: AbortController | null = null;
|
|
public readyState: number = 0;
|
|
public onopen: (() => void) | null = null;
|
|
public onerror: ((error: any) => void) | null = null;
|
|
public onmessage: ((event: MessageEvent) => void) | null = null;
|
|
|
|
constructor(url: string) {
|
|
this.url = url;
|
|
this.connect();
|
|
}
|
|
|
|
private async connect() {
|
|
this.readyState = 0; // CONNECTING
|
|
this.abortController = new AbortController();
|
|
|
|
try {
|
|
const response = await fetch(this.url, {
|
|
signal: this.abortController.signal,
|
|
});
|
|
|
|
if (!response.ok) {
|
|
throw new Error(`HTTP ${response.status}`);
|
|
}
|
|
|
|
this.readyState = 1; // OPEN
|
|
this.onopen?.();
|
|
|
|
const reader = response.body!.getReader();
|
|
const decoder = new TextDecoder();
|
|
let buffer = '';
|
|
|
|
while (true) {
|
|
const { done, value } = await reader.read();
|
|
if (done) break;
|
|
|
|
buffer += decoder.decode(value, { stream: true });
|
|
const events = buffer.split('\n\n');
|
|
buffer = events.pop() || '';
|
|
|
|
events.forEach((eventStr) => {
|
|
this.parseAndDispatchEvent(eventStr);
|
|
});
|
|
}
|
|
} catch (error) {
|
|
this.readyState = 2; // CLOSED
|
|
this.onerror?.(error);
|
|
}
|
|
}
|
|
|
|
private parseAndDispatchEvent(eventStr: string) {
|
|
const lines = eventStr.split('\n');
|
|
let eventType = 'message';
|
|
let data = '';
|
|
|
|
lines.forEach((line) => {
|
|
if (line.startsWith('event:')) {
|
|
eventType = line.substring(6).trim();
|
|
} else if (line.startsWith('data:')) {
|
|
data += line.substring(5).trim() + '\n';
|
|
}
|
|
});
|
|
|
|
const event = new MessageEvent(eventType, { data: data.trim() });
|
|
|
|
if (eventType === 'message' && this.onmessage) {
|
|
this.onmessage(event);
|
|
}
|
|
|
|
const listener = this.listeners.get(eventType);
|
|
listener?.(event);
|
|
}
|
|
|
|
addEventListener(type: string, listener: (event: MessageEvent) => void) {
|
|
this.listeners.set(type, listener);
|
|
}
|
|
|
|
close() {
|
|
this.abortController?.abort();
|
|
this.readyState = 2; // CLOSED
|
|
}
|
|
}
|
|
|
|
// Use native or polyfill
|
|
const EventSourceImpl = typeof EventSource !== 'undefined' ? EventSource : EventSourcePolyfill;
|
|
const eventSource = new EventSourceImpl('/api/events');</code></pre>
|
|
<h2>Quick Reference</h2>
|
|
<h3>Client API</h3>
|
|
<pre><code class="lang-typescript">// Create connection
|
|
const eventSource = new EventSource('/api/events');
|
|
|
|
// Listen to events
|
|
eventSource.onmessage = (event) => { /* Default message */ };
|
|
eventSource.addEventListener('custom', (event) => { /* Named event */ });
|
|
|
|
// Connection state
|
|
eventSource.onopen = () => { /* Connected */ };
|
|
eventSource.onerror = (error) => { /* Error or disconnect */ };
|
|
|
|
// Check state
|
|
eventSource.readyState // CONNECTING=0, OPEN=1, CLOSED=2
|
|
|
|
// Close connection
|
|
eventSource.close();</code></pre>
|
|
<h3>Server Response Format</h3>
|
|
<pre><code>HTTP/1.1 200 OK
|
|
Content-Type: text/event-stream
|
|
Cache-Control: no-cache
|
|
Connection: keep-alive
|
|
|
|
event: message
|
|
id: 1
|
|
data: {"text": "Hello"}
|
|
|
|
event: notification
|
|
id: 2
|
|
data: {"title": "New message"}
|
|
</code></pre>
|
|
<h3>Event Fields</h3>
|
|
<pre><code>event: <event-name> // Optional, default: "message"
|
|
id: <event-id> // Optional, for reconnection
|
|
retry: <milliseconds> // Optional, reconnection delay
|
|
data: <payload> // Required, can be multi-line</code></pre>
|
|
<h2>Anti-Patterns</h2>
|
|
<h3>❌ No Cache-Control Headers</h3>
|
|
<pre><code class="lang-typescript">// Wrong: Missing cache headers
|
|
app.get('/events', (req, res) => {
|
|
res.setHeader('Content-Type', 'text/event-stream');
|
|
// Missing Cache-Control header
|
|
});</code></pre>
|
|
<p><strong>Why it's bad</strong>: Proxies and CDNs may cache the event stream</p>
|
|
<p><strong>Better approach</strong>:</p>
|
|
<pre><code class="lang-typescript">res.setHeader('Cache-Control', 'no-cache');
|
|
res.setHeader('X-Accel-Buffering', 'no'); // Nginx</code></pre>
|
|
<h3>❌ Not Handling Reconnection</h3>
|
|
<pre><code class="lang-typescript">// Wrong: No last-event-id handling
|
|
app.get('/events', (req, res) => {
|
|
// Start sending all events from beginning
|
|
});</code></pre>
|
|
<p><strong>Why it's bad</strong>: Client receives duplicate events after reconnection</p>
|
|
<p><strong>Better approach</strong>:</p>
|
|
<pre><code class="lang-typescript">const lastEventId = parseInt(req.headers['last-event-id'] as string || '0');
|
|
sendMissedEvents(res, lastEventId);</code></pre>
|
|
<h3>❌ Buffering Issues</h3>
|
|
<pre><code class="lang-typescript">// Wrong: Large data without flushing
|
|
res.write(`data: ${largeObject}\n\n`);
|
|
// May be buffered by Node.js or proxy</code></pre>
|
|
<p><strong>Why it's bad</strong>: Events may be delayed or batched</p>
|
|
<p><strong>Better approach</strong>:</p>
|
|
<pre><code class="lang-typescript">res.write(`data: ${data}\n\n`);
|
|
res.flush?.(); // Flush immediately if available</code></pre>
|
|
<h3>❌ No Keep-Alive Comments</h3>
|
|
<pre><code class="lang-typescript">// Wrong: No keepalive mechanism
|
|
app.get('/events', (req, res) => {
|
|
// Connection may timeout after idle period
|
|
});</code></pre>
|
|
<p><strong>Why it's bad</strong>: Proxies may close idle connections</p>
|
|
<p><strong>Better approach</strong>:</p>
|
|
<pre><code class="lang-typescript">setInterval(() => {
|
|
res.write(': keepalive\n\n');
|
|
}, 30000);</code></pre>
|
|
<h2>Related Skills</h2>
|
|
<ul><li><strong>websocket-implementation.md</strong>: Alternative for bidirectional communication</li><li><strong>realtime-sync.md</strong>: Data synchronization patterns for SSE streams</li><li><strong>pubsub-patterns.md</strong>: Server-side message routing for SSE broadcasts</li><li><strong>network-resilience-patterns.md</strong>: Error handling and retry strategies</li></ul>
|
|
<hr>
|
|
<p><strong>Last Updated</strong>: 2025-10-18 <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="/realtime-server-sent-events.md">This page as plain text</a> · <a href="/llms.txt">Index for agents</a></div>
|
|
</footer>
|
|
</div></body></html> |