Server-Sent Events (SSE)

Сервер открывает один HTTP-ответ и пишет в него data: ...\n\n бесконечно. Браузер парсит, эмитит JS-события, сам реконнектится. Никаких новых протоколов поверх HTTP.

Зачем

Половина «real-time» в продукте — это односторонний push: сервер знает что-то новое и хочет сказать клиенту. Прилетел новый заказ, изменился статус деплоя, LLM выдала следующий токен, обновились unread-counters в шапке. Клиент при этом ничего не пушит обратно — он просто слушает.

Под такой профиль трафика есть три инструмента:

• Short-poll — GET каждые N секунд. Латентность = интервал опроса, нагрузка = O(clients × poll_rate). 1000 клиентов с опросом раз в секунду = 1000 RPS вхолостую, даже когда событий нет.
• Long-poll — GET, сервер держит ответ открытым до события или таймаута, клиент тут же делает следующий GET. Меньше холостого трафика, но каждое событие = полный HTTP request/response cycle (заголовки, TLS resumption, новая запись в access log).
• WebSocket — отдельный binary frame protocol после HTTP Upgrade. Full-duplex, бинарь, низкие frames. Но: ломается на «тупых» прокси, нет auto-reconnect из коробки, нужна отдельная инфраструктура (sticky sessions, отдельные правила LB, отдельный мониторинг).

SSE — четвёртый вариант, и для одностороннего push он почти всегда правильный. Это обычный HTTP/1.1 chunked-ответ (или HTTP/2 stream), который сервер не закрывает. Браузер парсит wire-format через нативный EventSource API. Auto-reconnect с Last-Event-ID — встроены. Работает через любой прокси, который не сломан в принципе.

Если в системе всё-таки появляется регулярный client → server трафик (чат с typing indicators, multiplayer, collaborative editing с позициями курсоров) — нужен WebSocket. Если нет — SSE короче, проще в эксплуатации и не плодит параллельный стек.

Mental model

Три вещи, которые надо удерживать в голове:

1. Это HTTP-ответ, который не закрывается. Не новый протокол, не апгрейд, не upgrade-handshake. GET /stream → 200 OK с заголовком Content-Type: text/event-stream → сервер пишет в body байты и не вызывает close(). Браузер читает по мере прихода.
2. Wire format — текст, разделённый \n\n. Каждое событие — набор полей data:, event:, id:, retry:, разделённых \n. Конец события — пустая строка. Любая строка с : в начале — комментарий (keep-alive).
3. Auto-reconnect — это спецификация. Браузер сам реконнектится при разрыве, сам присылает Last-Event-ID: <last> в заголовке следующего запроса, сам ждёт retry: N миллисекунд. Сервер должен уметь это пережить: иметь буфер последних событий и уметь начать стрим не с now, а с указанного id.

Кеш-мнемоника: «long-poll, у которого ответ длится вечно, плюс браузер сам знает, где остановился».

Что на диаграмме

Скрипт раскладывает один минимально-полный SSE-стек на четыре группы:

• Clients — браузерная вкладка с EventSource. На ноде закреплены три ADR (выбор транспорта, стратегия resume, гигиена прокси).
• Edge — NGINX как reverse proxy. Здесь сидят все «invisible killers»: buffering, gzip, idle timeouts. Если в стеке есть CDN (Cloudflare, Fastly) — он визуально на этом же месте.
• SSE server — собственно SSE handler (/stream) и Redis Stream как буфер событий. Redis Stream здесь не «потому что Redis», а потому что нужен durable bounded buffer с монотонными id для replay по Last-Event-ID.
• Producers — сервисы, которые публикуют события в Redis: API service (бизнес-события: orders, status changes) и LLM service (поток токенов из LLM-инференса). Они никак не связаны с клиентом напрямую — это критический развязывающий слой.

Edges на диаграмме — физические провода: browser → nginx → sse → redis, api → redis, llm → sse. Ответы (фреймы серверу → клиенту) идут по тем же проводам в обратную сторону (reverse animation на FlowBuilder), отдельные edges под «push» не нужны.

Сценарии (что показывают анимации)

1) basic-stream — стандартный happy path. Клиент делает new EventSource('/stream'). Браузер шлёт GET с Accept: text/event-stream. NGINX проксирует БЕЗ буферизации. Сервер отвечает 200 OK + Content-Type: text/event-stream + Cache-Control: no-cache, no-transform — ответ остаётся открыт. Параллельно API service делает XADD в Redis stream. SSE handler крутит XREAD BLOCK 30000 (long-blocking read) — как только прилетает новая запись, формирует SSE-фрейм (event: + id: + data: + \n\n) и пишет в открытый ответ. NGINX мгновенно форвардит — на клиенте срабатывает listener. Каждые 15-30 секунд сервер шлёт : keepalive\n\n (comment line) — EventSource его игнорирует, но TCP остаётся живым (не сработают idle timeouts). Инвариант: один TCP, бесконечно событий, ноль polling. Bandwidth = O(events), не O(time).

2) reconnect-resume — TCP drop в середине стрима. Прилетели события 42 и 43, клиент запомнил lastEventId = "43". Дальше — laptop sleep / Wi-Fi → LTE handoff / proxy reset → TCP RST. Сервер при следующей записи получает EPIPE и закрывает свой handler. Тем временем API публикует 44 и 45 в Redis (они никуда не пропали — буфер их держит). Браузер видит обрыв, ждёт retry миллисекунд (по умолчанию 3 секунды, сервер может переопределить полем retry: N) и сам делает GET со встроенным заголовком Last-Event-ID: 43. Никакого application кода — это поведение EventSource. Handler читает заголовок, делает XRANGE events.stream (43+1)-0 +, получает пропущенные 44 и 45, отправляет их фреймами с теми же id, потом возвращается к нормальному XREAD BLOCK. Клиент догнал стрим, в коде прикладного слоя ноль строк про reconnect. Гочa: если Last-Event-ID уехал за пределы буфера (был 30-минутный outage, а буфер хранит 15 минут) — отдать 410 Gone или фрейм event: snapshot со ссылкой на REST-эндпоинт полного состояния.

3) llm-streaming — OpenAI/Anthropic-стиль. Это де-факто стандарт для LLM API: POST с промптом, в ответ — SSE-стрим токенов, финальный фрейм data: [DONE]. Деталь, которая ломает EventSource: он умеет только GET и не умеет custom headers (включая Authorization). Поэтому везде, где есть POST + auth + streaming (то есть везде, где есть LLM API), используют fetch + ReadableStream или полифилл @microsoft/fetch-event-source — тот же wire format, та же логика, но через fetch. Сценарий демонстрирует: prompt летит на LLM service, токены приходят по одному, каждый — отдельный SSE-фрейм. UX-эффект: perceived latency падает с «жди 5 секунд» до «первый байт через 200мс», текст «печатается» на глазах. Этим же паттерном работают POST /v1/chat/completions?stream=true у OpenAI, Anthropic Messages API с stream: true, Mistral, Cohere.

Trade-offs (ADR-001, ADR-002, ADR-003)

Полные ADR закреплены на ноде browser (вкладка Decisions). TL;DR:

ADR-001 — SSE vs WebSocket vs long-poll. SSE когда трафик server → client only и payload текстовый. WebSocket когда client → server тоже real-time (chat, games, collab editor, WebRTC signaling). Long-poll только как fallback для очень старых корпоративных прокси. Если вы открываете параллельный POST-endpoint, чтобы слать каждое нажатие клавиши с клиента — вам нужен WebSocket, не SSE.

ADR-002 — Resume стратегия. Bounded server-side buffer (Redis Streams: XADD с auto-id + XTRIM MAXLEN ~ N), монотонные глобально упорядоченные id (stream id вида timestamp-seq или Snowflake — НЕ autoincrement- per-pod, оно сломается через два инстанса), окно 5-15 минут или 10K-100K событий. При reconnect за пределы окна — 410 Gone + snapshot. SLA задокументировать: «replayable up to N минут, older reconnects = full state refetch».

ADR-003 — Гигиена прокси. Это то, на чём ломаются 90% первых деплоев SSE. proxy_buffering off в NGINX location block. gzip off или Content-Encoding: identity (gzip буферизует до 16KB+, ломает streaming feel и его обычно списывают на «сеть»). Cache-Control: no-cache, no-transform — no-transform мешает mid-path прокси (корпораты, мобильные операторы) пере-сжимать ответ. ALB idle timeout ≥ keep-alive period + margin (стандартные 60 секунд ок, если пинговать каждые 30). Heartbeat :\n\n каждые 15-30 секунд — невидим для приложения, держит TCP. Проверять сразу curl --no-buffer -N <url> — байты должны капать, а не вывалиться пачкой.

Реальные системы

• OpenAI / Anthropic / Mistral / Cohere — все стримят токены в SSE wire format поверх POST (через fetch+ReadableStream, потому что EventSource не умеет POST).
• GitHub — live-events для нотификаций.
• Slack, Pinterest — unread counts, presence updates.
• Vercel, Netlify, Render — стрим build/deploy логов в UI.
• Mercure (Symfony + Caddy module) — open standard pub/sub поверх SSE.
• Next.js, Remix — server-side loading hints, streaming SSR частично используют тот же transport.

Anti-patterns

1. WebSocket для read-only push. Лишний протокол, отдельный стек инфры, sticky sessions — а можно было одной HTTP-роутой.
2. NGINX без proxy_buffering off. События накапливаются, латентность взлетает, клиент видит пачки вместо потока.
3. Gzip на SSE endpoint. Компрессор буферизует, streaming сломан. Это самая частая «магически медленная» SSE.
4. Нет heartbeat. Connection дропается каждую минуту по ALB/NGINX idle timeout, клиент бесконечно реконнектится.
5. Last-Event-ID игнорируется. Сервер стримит «с now», после reconnect клиент молча пропускает события навсегда.
6. Нет лимита на concurrent connections per user. Один зловредный клиент открывает 1000 SSE → file descriptor exhaustion → DoS на пустом месте.
7. Bearer token в EventSource. Не работает — EventSource не умеет custom headers. Либо cookie-based auth, либо fetch-EventSource полифилл.
8. HTTP/1.1 без HTTP/2. Браузер режет 6 соединений на origin. Шесть открытых вкладок с SSE = седьмой HTTP-запрос на тот же origin висит. HTTP/2 мультиплексирует — лимит снимается.
9. Autoincrement-per-pod ids в буфере. Через два пода ломается глобальный порядок и Last-Event-ID теряет смысл. Глобально монотонные id (Redis stream id, Snowflake) — обязательно.

Когда НЕ использовать

• Bi-directional трафик. Чат с typing indicators, multiplayer, collab editor — здесь нужен WebSocket. SSE + параллельный POST endpoint на каждое сообщение — антипаттерн, который сначала работает, потом превращается в WebSocket-самопал.
• Binary payload. SSE — только UTF-8 текст. Видео, аудио, protobuf, msgpack — мимо. Можно base64, но это +33% bandwidth и потеря того самого «дешёвый и простой» аргумента.
• Sub-100ms gaming latency. HTTP-overhead на каждое событие (даже chunked) — это десятки байт заголовков на каждый «кадр». Для realtime игры нужен WebSocket или WebTransport.
• Сотни тысяч одновременных подключений на одном процессе. Каждое SSE = open socket. Apache prefork сдохнет на нескольких тысячах, нужен Go/Rust/Node.js с epoll/kqueue и аккуратной работой с FD limits. Это решаемо, но архитектурно надо закладывать сразу.
• Через прокси, который вы не контролируете и который буферизует. Если deployment-target — корпоративная сеть с обязательным proxy, который буферизует ответы и не настраивается — SSE работать не будет, нужен long-poll fallback.

Дальше читать

• WebSocket (/concepts/websocket) — когда нужно полноценное bidirectional. Сравнение по latency, payload, операционке.
• HTTP/2 multiplexing — почему 6-connection limit перестаёт быть проблемой, как один TCP несёт десятки SSE-стримов.
• Redis Streams — XADD, XREAD BLOCK, XRANGE, XTRIM. Канонический backend для bounded event buffer.
• HTML Living Standard, server-sent events section — единственный нормативный источник по wire format и поведению EventSource.
• MDN, Using server-sent events — практический гайд с примерами EventSource и серверного кода.
• NGINX proxy_buffering docs — точная семантика и где её выключать.
• OpenAI streaming API reference — как выглядит SSE на POST и почему [DONE] стал индустриальным sentinel'ом.
• Mercure spec — open standard pub/sub поверх SSE; полезно посмотреть, как авторизация и discovery встраиваются в SSE-стек.