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.
Client HTTP Connection
WebSocket Handshake (101 Upgrade) vs SSE (text/event-stream)
WS: Full Duplex Frame Exchange
SSE: Server Push Stream
Connection Reconnect Loop
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.
python(24 lines)
1from fastapi import FastAPI, WebSocket
2from fastapi.responses import StreamingResponse
3import asyncio
4
5app = FastAPI()
6
7# Server-Sent Events (SSE) Route
8async def event_generator():
9 for i in range(10):
10 await asyncio.sleep(1)
11 yield f"data: Token chunk {i}\n\n"
12
13@app.get("/stream")
14async def stream_tokens():
15 return StreamingResponse(event_generator(), media_type="text/event-stream")
16
17# Bi-directional WebSocket Route
18@app.websocket("/ws")
19async def websocket_endpoint(websocket: WebSocket):
20 await websocket.accept()
21 while True:
22 data = await websocket.receive_text()
23 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
Upgradeheaders). - 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
- Proxy Connection Drops: Reverse proxies (Nginx/Cloudflare) terminate silent SSE/WebSocket streams after
60sidle timeout. Always implement ping/pong or periodic heartbeat comments (: heartbeat\n\n). - Browser Connection Limits: Browsers limit HTTP/1.1 SSE connections to 6 per domain. Use HTTP/2 multiplexing to bypass connection caps.
Reflect before revealing the guide
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.