Sse

---
name: sse
description: "Server-Sent Events covering the EventSource API, text/event-stream format, auto-reconnection, Last-Event-ID resumption, named events, server implementations across Node.js/Python/Go/.NET/Rust, LLM streaming patterns, and infrastructure configuration. Use for \"SSE\", \"Server-Sent Events\", \"EventSource\", \"text/event-stream\", \"Last-Event-ID\", \"event stream\", \"LLM streaming\", \"AI streaming\", \"token streaming\", \"server push\", \"live feed\", \"log streaming\", \"progress events\", \"retry field\", \"keepalive\", \"MCP transport\". Covers the HTTP-native client-push transport itself. Do NOT use for broker-backed pub/sub or message-queue fan-out (Kafka, RabbitMQ, SNS/SQS) — use the relevant broker skill in the `messaging` plugin for that."
license: MIT
---

# Server-Sent Events

This skill covers Server-Sent Events (SSE), the HTTP-based unidirectional server push technology standardized in the WHATWG HTML Living Standard. SSE has experienced a major resurgence due to LLM/AI token streaming. It has deep knowledge of:

- SSE wire format: `data`, `event`, `id`, `retry` fields
- EventSource browser API: auto-reconnection, `Last-Event-ID`, readyState
- Named events for logical multiplexing
- Server implementations: Node.js (Express, Fastify), Python (FastAPI, Django), Go, .NET 10, Rust (Axum)
- LLM streaming patterns (OpenAI, Anthropic, MCP protocol)
- Infrastructure: keepalive, proxy configuration, HTTP/2, CDN handling
- Authentication constraints and workarounds

## How to Approach Tasks

1. **Classify** the request:
   - **Protocol / architecture** -- Load `references/architecture.md` for wire format, EventSource API, reconnection, named events
   - **Best practices** -- Load `references/best-practices.md` for server implementations, LLM streaming, keepalive, authentication, infrastructure
   - **Troubleshooting** -- Load `references/diagnostics.md` for connection issues, buffering, proxy problems, reconnection failures
   - **Cross-technology comparison** -- Read the `overview` skill

2. **Gather context** -- Server language/framework, client type (browser EventSource vs fetch), proxy/CDN in use, use case (LLM streaming, notifications, dashboard)

3. **Analyze** -- Apply SSE-specific reasoning: HTTP-native behavior, auto-reconnect semantics, keepalive requirements, proxy buffering issues.

4. **Recommend** -- Provide server implementation code, client code, and infrastructure configuration.

## Core Protocol

### Wire Format

UTF-8 text stream. Events are blocks of field lines terminated by blank line (`\n\n`):
```
id: 1001
event: price-update
data: {"symbol":"AAPL","price":189.43}

```

Four field names: `data` (payload), `event` (type), `id` (for resumption), `retry` (reconnect interval ms). Comment lines start with `:` (used for keepalive).

### EventSource API

```javascript
const es = new EventSource('/events');
es.onmessage = (e) => console.log(e.data);
es.addEventListener('custom', (e) => JSON.parse(e.data));
es.onerror = () => { /* browser auto-reconnects */ };
es.close();
```

### Key Features

- **Auto-reconnection** with `Last-Event-ID` resumption
- **Named events** for logical channel multiplexing
- **HTTP-native**: works through all proxies, CDNs, firewalls
- **No sticky sessions** needed (stateless reconnection)
- **HTTP/2** eliminates 6-connection browser limit
- Server sends `204 No Content` to permanently close stream

## Anti-Patterns

1. **Using SSE for bidirectional communication** -- SSE is server-to-client only. Use WebSocket for bidirectional.
2. **No keepalive comments** -- Proxies kill idle connections after 60-120 seconds. Send `:keepalive\n\n` every 15-30 seconds.
3. **Missing `Cache-Control: no-cache`** -- Without it, intermediate caches may buffer the entire stream.
4. **No `X-Accel-Buffering: no` behind Nginx** -- Nginx buffers responses by default, preventing streaming.
5. **Large event payloads** -- SSE is text-only UTF-8. Large binary data should use a separate REST endpoint.
6. **Not using `id` field for resumption** -- Without event IDs, clients cannot resume after reconnection and miss events.
7. **Not flushing response buffers** -- Many frameworks buffer output. Explicit flush is required (Go's `Flusher`, Python's `StreamingResponse`).
8. **EventSource with custom headers** -- EventSource cannot set custom headers. Use cookies or query-string tokens for auth.

## Reference Files

- `references/architecture.md` -- Wire format, EventSource API, reconnection, named events, HTTP headers, connection lifecycle
- `references/best-practices.md` -- Server implementations (Node.js, Python, Go, .NET, Rust), LLM streaming, keepalive, authentication, proxy configuration, HTTP/2
- `references/diagnostics.md` -- Connection drops, proxy buffering, reconnection failures, memory issues, CDN configuration, performance

## Cross-References

- `overview` skill -- SSE vs WebSocket, SignalR, Socket.IO comparisons
- `signalr` skill -- SignalR uses SSE as fallback transport