WebSockets vs Server-Sent Events (SSE)

Learning outcomes

• Distinguish duplex WebSockets from SSE unidirectional streaming
• Implement resilient reconnection and heartbeat loops

Mental model

WebSockets upgrade an HTTP socket into a full-duplex TCP connection. Server-Sent Events (SSE) maintain a standard persistent HTTP connection (text/event-stream) streaming text chunks from server to client.

Theory

• WebSockets (ws://, wss://): Bi-directional, full-duplex binary framing over custom TCP protocol. Ideal for chat apps and multi-player collaboration.
• Server-Sent Events (SSE): Unidirectional (server-to-client) UTF-8 text streaming over standard HTTP. Native browser auto-reconnect (EventSource). Ideal for AI LLM token streaming and dashboard metrics.

from fastapi import FastAPI, WebSocket
from fastapi.responses import StreamingResponse
import asyncio

app = FastAPI()

# Server-Sent Events (SSE) Route
async def event_generator():
    for i in range(10):
        await asyncio.sleep(1)
        yield f"data: Token chunk {i}\n\n"

@app.get("/stream")
async def stream_tokens():
    return StreamingResponse(event_generator(), media_type="text/event-stream")

# Bi-directional WebSocket Route
@app.websocket("/ws")
async def websocket_endpoint(websocket: WebSocket):
    await websocket.accept()
    while True:
        data = await websocket.receive_text()
        await websocket.send_text(f"Echo: {data}")

Alternatives and trade-offs

• WebSockets: Bi-directional low latency; bypasses HTTP caching, requires proxy WebSocket protocol support (Nginx Upgrade headers).
• SSE: Simple HTTP standard, works across existing HTTP load balancers and proxies, built-in browser retry; limited to text payloads and unidirectional push.

Failure modes and misconceptions

1. Proxy Connection Drops: Reverse proxies (Nginx/Cloudflare) terminate silent SSE/WebSocket streams after 60s idle timeout. Always implement ping/pong or periodic heartbeat comments (: heartbeat\n\n).
2. Browser Connection Limits: Browsers limit HTTP/1.1 SSE connections to 6 per domain. Use HTTP/2 multiplexing to bypass connection caps.

Decision scenario

Use Server-Sent Events (SSE) for AI token streaming endpoints because SSE operates over standard HTTP, simplifies CORS/auth proxying, and provides native browser auto-reconnection.

Learning outcomes

• Compare WebSockets full-duplex framing with SSE HTTP streaming.
• Build resilient heartbeats and reconnection loops for long-lived streams.
• Avoid proxy dropouts and HTTP connection limits in browser streaming applications.

Trade-offs

WebSockets enable low-latency bi-directional messaging, while SSE provides simpler HTTP-compliant server-to-client streaming.

Primary sources

• FastAPI Framework Architecture & Dependency Injection Specification — Tiangolo, verified 2026-07-22