Files
skills/public/realtime-server-sent-events.html
zeekayandHanzo Dev 9e10c1c10e Each llms index points at the other two
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]>
2026-09-11 00:27:59 -07:00

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&#x27;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 (&lt;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 ----------------&gt;|
| Accept: text/event-stream |
| |
|&lt;-- 200 OK --------------------|
| Content-Type: text/event- |
| stream |
| Cache-Control: no-cache |
| |
|&lt;== 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: {&quot;text&quot;: &quot;Hello&quot;}
data: {&quot;more&quot;: &quot;data&quot;}
</code></pre>
<p><strong>Fields</strong>:</p>
<ul><li><code>event</code>: Event type (default: &quot;message&quot;)</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&lt;string, Set&lt;(data: any) =&gt; void&gt;&gt; = new Map();
private reconnectAttempts = 0;
private maxReconnectAttempts = 5;
constructor(url: string) {
this.url = url;
}
connect(): Promise&lt;void&gt; {
return new Promise((resolve, reject) =&gt; {
try {
this.eventSource = new EventSource(this.url);
this.eventSource.onopen = () =&gt; {
console.log(&#x27;SSE connected&#x27;);
this.reconnectAttempts = 0;
resolve();
};
this.eventSource.onerror = (error) =&gt; {
console.error(&#x27;SSE error:&#x27;, error);
if (this.eventSource?.readyState === EventSource.CLOSED) {
this.handleDisconnect();
}
};
this.eventSource.onmessage = (event) =&gt; {
this.handleEvent(&#x27;message&#x27;, event.data);
};
} catch (error) {
reject(error);
}
});
}
on(eventType: string, handler: (data: any) =&gt; void) {
if (!this.listeners.has(eventType)) {
this.listeners.set(eventType, new Set());
// Register event listener with EventSource
if (this.eventSource &amp;&amp; eventType !== &#x27;message&#x27;) {
this.eventSource.addEventListener(eventType, (event: MessageEvent) =&gt; {
this.handleEvent(eventType, event.data);
});
}
}
this.listeners.get(eventType)!.add(handler);
}
off(eventType: string, handler: (data: any) =&gt; 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) =&gt; {
try {
handler(parsedData);
} catch (error) {
console.error(`Error in ${eventType} handler:`, error);
}
});
}
private handleDisconnect() {
this.reconnectAttempts++;
if (this.reconnectAttempts &lt;= this.maxReconnectAttempts) {
const delay = Math.min(1000 * Math.pow(2, this.reconnectAttempts - 1), 30000);
console.log(`Reconnecting in ${delay}ms (attempt ${this.reconnectAttempts})`);
setTimeout(() =&gt; {
this.connect().catch(console.error);
}, delay);
} else {
console.error(&#x27;Max reconnection attempts reached&#x27;);
}
}
close() {
this.eventSource?.close();
this.eventSource = null;
this.listeners.clear();
}
get readyState(): number {
return this.eventSource?.readyState ?? EventSource.CLOSED;
}
}
// Usage
const client = new SSEClient(&#x27;/api/events&#x27;);
await client.connect();
client.on(&#x27;message&#x27;, (data) =&gt; {
console.log(&#x27;Default message:&#x27;, data);
});
client.on(&#x27;notification&#x27;, (data) =&gt; {
console.log(&#x27;Notification:&#x27;, data);
});
client.on(&#x27;update&#x27;, (data) =&gt; {
console.log(&#x27;Update:&#x27;, data);
});</code></pre>
<h3>2. Server Implementation (Node.js/Express)</h3>
<pre><code class="lang-typescript">import express from &#x27;express&#x27;;
import { Request, Response } from &#x27;express&#x27;;
interface SSEConnection {
id: string;
res: Response;
lastEventId: number;
}
class SSEServer {
private connections: Map&lt;string, SSEConnection&gt; = new Map();
private eventCounter = 0;
setupRoutes(app: express.Application) {
app.get(&#x27;/api/events&#x27;, (req, res) =&gt; {
this.handleConnection(req, res);
});
}
private handleConnection(req: Request, res: Response) {
// Set SSE headers
res.setHeader(&#x27;Content-Type&#x27;, &#x27;text/event-stream&#x27;);
res.setHeader(&#x27;Cache-Control&#x27;, &#x27;no-cache&#x27;);
res.setHeader(&#x27;Connection&#x27;, &#x27;keep-alive&#x27;);
res.setHeader(&#x27;X-Accel-Buffering&#x27;, &#x27;no&#x27;); // Disable nginx buffering
// Handle CORS if needed
res.setHeader(&#x27;Access-Control-Allow-Origin&#x27;, &#x27;*&#x27;);
// Get last event ID for reconnection
const lastEventId = parseInt(req.headers[&#x27;last-event-id&#x27;] as string || &#x27;0&#x27;);
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: &#x27;connected&#x27;,
data: { connectionId, timestamp: Date.now() },
});
// Send missed events if reconnecting
if (lastEventId &gt; 0) {
this.sendMissedEvents(connection, lastEventId);
}
// Handle client disconnect
req.on(&#x27;close&#x27;, () =&gt; {
this.connections.delete(connectionId);
console.log(`Client ${connectionId} disconnected. Total: ${this.connections.size}`);
});
// Keep connection alive with comments
const keepAliveInterval = setInterval(() =&gt; {
res.write(&#x27;: keepalive\n\n&#x27;);
}, 30000);
req.on(&#x27;close&#x27;, () =&gt; {
clearInterval(keepAliveInterval);
});
}
private sendEvent(connection: SSEConnection, event: {
event?: string;
id?: number;
data: any;
retry?: number;
}) {
const { res } = connection;
const { event: eventType = &#x27;message&#x27;, 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 === &#x27;string&#x27; ? data : JSON.stringify(data);
const lines = jsonData.split(&#x27;\n&#x27;);
lines.forEach((line) =&gt; {
res.write(`data: ${line}\n`);
});
res.write(&#x27;\n&#x27;);
} catch (error) {
console.error(&#x27;Error sending event:&#x27;, error);
this.connections.delete(connection.id);
}
}
broadcast(event: { event?: string; data: any }) {
const eventId = ++this.eventCounter;
this.connections.forEach((connection) =&gt; {
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&#x27;ll send a synthetic event
this.sendEvent(connection, {
event: &#x27;catchup&#x27;,
data: { message: &#x27;Caught up from event &#x27; + 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(() =&gt; {
sseServer.broadcast({
event: &#x27;time&#x27;,
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(&#x27;/api/events&#x27;, this.authenticate, (req, res) =&gt; {
this.handleConnection(req, res);
});
}
private authenticate(req: Request, res: Response, next: express.NextFunction) {
const token = req.query.token as string || req.headers.authorization?.split(&#x27; &#x27;)[1];
if (!token) {
res.status(401).json({ error: &#x27;Missing token&#x27; });
return;
}
if (!verifyToken(token)) {
res.status(403).json({ error: &#x27;Invalid token&#x27; });
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&lt;string, (event: MessageEvent) =&gt; void&gt; = new Map();
private abortController: AbortController | null = null;
public readyState: number = 0;
public onopen: (() =&gt; void) | null = null;
public onerror: ((error: any) =&gt; void) | null = null;
public onmessage: ((event: MessageEvent) =&gt; 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 = &#x27;&#x27;;
while (true) {
const { done, value } = await reader.read();
if (done) break;
buffer += decoder.decode(value, { stream: true });
const events = buffer.split(&#x27;\n\n&#x27;);
buffer = events.pop() || &#x27;&#x27;;
events.forEach((eventStr) =&gt; {
this.parseAndDispatchEvent(eventStr);
});
}
} catch (error) {
this.readyState = 2; // CLOSED
this.onerror?.(error);
}
}
private parseAndDispatchEvent(eventStr: string) {
const lines = eventStr.split(&#x27;\n&#x27;);
let eventType = &#x27;message&#x27;;
let data = &#x27;&#x27;;
lines.forEach((line) =&gt; {
if (line.startsWith(&#x27;event:&#x27;)) {
eventType = line.substring(6).trim();
} else if (line.startsWith(&#x27;data:&#x27;)) {
data += line.substring(5).trim() + &#x27;\n&#x27;;
}
});
const event = new MessageEvent(eventType, { data: data.trim() });
if (eventType === &#x27;message&#x27; &amp;&amp; this.onmessage) {
this.onmessage(event);
}
const listener = this.listeners.get(eventType);
listener?.(event);
}
addEventListener(type: string, listener: (event: MessageEvent) =&gt; void) {
this.listeners.set(type, listener);
}
close() {
this.abortController?.abort();
this.readyState = 2; // CLOSED
}
}
// Use native or polyfill
const EventSourceImpl = typeof EventSource !== &#x27;undefined&#x27; ? EventSource : EventSourcePolyfill;
const eventSource = new EventSourceImpl(&#x27;/api/events&#x27;);</code></pre>
<h2>Quick Reference</h2>
<h3>Client API</h3>
<pre><code class="lang-typescript">// Create connection
const eventSource = new EventSource(&#x27;/api/events&#x27;);
// Listen to events
eventSource.onmessage = (event) =&gt; { /* Default message */ };
eventSource.addEventListener(&#x27;custom&#x27;, (event) =&gt; { /* Named event */ });
// Connection state
eventSource.onopen = () =&gt; { /* Connected */ };
eventSource.onerror = (error) =&gt; { /* 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: {&quot;text&quot;: &quot;Hello&quot;}
event: notification
id: 2
data: {&quot;title&quot;: &quot;New message&quot;}
</code></pre>
<h3>Event Fields</h3>
<pre><code>event: &lt;event-name&gt; // Optional, default: &quot;message&quot;
id: &lt;event-id&gt; // Optional, for reconnection
retry: &lt;milliseconds&gt; // Optional, reconnection delay
data: &lt;payload&gt; // 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(&#x27;/events&#x27;, (req, res) =&gt; {
res.setHeader(&#x27;Content-Type&#x27;, &#x27;text/event-stream&#x27;);
// Missing Cache-Control header
});</code></pre>
<p><strong>Why it&#x27;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(&#x27;Cache-Control&#x27;, &#x27;no-cache&#x27;);
res.setHeader(&#x27;X-Accel-Buffering&#x27;, &#x27;no&#x27;); // Nginx</code></pre>
<h3>❌ Not Handling Reconnection</h3>
<pre><code class="lang-typescript">// Wrong: No last-event-id handling
app.get(&#x27;/events&#x27;, (req, res) =&gt; {
// Start sending all events from beginning
});</code></pre>
<p><strong>Why it&#x27;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[&#x27;last-event-id&#x27;] as string || &#x27;0&#x27;);
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&#x27;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(&#x27;/events&#x27;, (req, res) =&gt; {
// Connection may timeout after idle period
});</code></pre>
<p><strong>Why it&#x27;s bad</strong>: Proxies may close idle connections</p>
<p><strong>Better approach</strong>:</p>
<pre><code class="lang-typescript">setInterval(() =&gt; {
res.write(&#x27;: keepalive\n\n&#x27;);
}, 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>