Server-Sent Events

API Design

Meaning

Server-Sent Events (SSE) is a web standard that lets a server push real-time updates to a client over a single long-lived HTTP connection using the text/event-stream MIME type. It addresses the pain point of unidirectional server-to-client streaming without the overhead of WebSockets or the latency of repeated polling. The trigger is needing lightweight, one-way push delivery from server to browser through standard HTTP infrastructure.

Primary Function

Real-time server push streaming

Communicative Purpose

Enables unidirectional real-time data streaming from server to client over plain HTTP without polling overhead or a separate protocol.

Pattern

client opens EventSource(url) → server sends text/event-stream chunks → client receives MessageEvent objects with auto-reconnect

Função primária

Real-time server push streaming

Propósito comunicativo

Enables unidirectional real-time data streaming from server to client over plain HTTP without polling overhead or a separate protocol.

Situações de gatilho

Web apps: pushing live notifications, alerts, or feed updates to browser clients in real time Real-time dashboards: streaming stock prices, monitoring metrics, or log tails to a UI Chat or broadcast: one-way fan-out of messages from server to many subscribed clients

Contextos

Browser-based web applications, Node.js and Python HTTP servers, EventSource client API, HTTP/1.1 streaming, real-time UI frameworks

Padrão

client opens EventSource(url) → server sends text/event-stream chunks → client receives MessageEvent objects with auto-reconnect

Colocados típicos

EventSource API
text/event-stream MIME type
MessageEvent
Last-Event-ID header
keep-alive connection
retry interval
named events

Substituições comuns

WebSockets: bidirectional full-duplex but heavier handshake and proxy issues Long polling: simpler but wastes requests and adds latency Webhooks: server-to-server callbacks
not server-to-browser Server push via HTTP/2: similar idea but requires HTTP/2 transport

Erros comuns

Forgetting Content-Type: text/event-stream header → browser treats response as plain text and never fires MessageEvent Not flushing the response buffer → events sit in the OS buffer and arrive in bursts instead of real time Assuming SSE is bidirectional → server cannot read client messages on the same stream Ignoring Last-Event-ID on reconnect → client permanently loses events sent during the disconnect window Using SSE through a buffering reverse proxy without disabling buffering → events are delayed until the buffer fills

Similar / contraste

WebSockets: bidirectional, binary-capable, separate upgrade handshake Long polling: client-driven repeated requests, no persistent stream WebHooks: server-to-server, not browser-facing HTTP/2 server push: transport-level, deprecated in browsers, not the same API

Interferências

Coming from WebSockets: may expect bidirectional frames on one connection — SSE is strictly server-to-client text streaming Coming from REST: may expect request-response semantics — SSE is a long-lived unidirectional stream with no client-to-server payload Coming from server-side languages: may buffer the response by default — must explicitly flush after each event chunk

Família do chunk

EventSource API
WebSockets
long polling
HTTP chunked transfer encoding
server push

Nuance

When NOT to use: bidirectional communication, binary payloads, IE/legacy browser support, or environments where proxies aggressively buffer chunked responses Performance: one TCP connection per origin (HTTP/1.1 limit of ~6), automatic browser reconnection with exponential backoff, no per-message framing overhead beyond the data: prefix Boundary conditions: text-only UTF-8 payloads, no binary frames, connection silently dropped by idle proxies after ~30–60 s without a heartbeat comment

Efeito pragmático

Delivers real-time UI updates without polling overhead, traverses corporate proxies and firewalls that block WebSocket upgrades, and gives production-grade auto-reconnection for free in every modern browser.

Dica de memória

Server-Sent Events: like a one-way radio broadcast from server to browser — the server talks, the browser listens, and if the signal drops, the radio automatically retunes to the last station it heard.

Upgrade path

WebSockets for bidirectional or binary needs; SSE with Last-Event-ID replay buffers for production resilience

Frequência: MediumFormulaicidade: Semi-fixedPrioridade de aquisição: Active recallPrioridade de output: BothTag de espaçamento: Medium-term

Examples

const eventSource = new EventSource('/api/notifications'); eventSource.addEventListener('alert', (event) => { const payload = JSON.parse(event.data); showToast(payload.message); }); eventSource.onerror = () => { console.warn('SSE connection lost, browser will auto-reconnect'); };

from flask import Flask, Response import time app = Flask(__name__) @app.route('/api/feed') def stream(): def generate(): while True: yield f"data: {time.strftime('%H:%M:%S')}\n\n" time.sleep(1) return Response(generate(), mimetype='text/event-stream') if __name__ == '__main__': app.run(threaded=True)