How do Server-Sent Events and WebSockets work on the wire?
An SSE stream is an ordinary HTTP response that never finishes. The client sends a GET (the browser's EventSource adds Accept: text/event-stream). The server answers 200 OK with Content-Type: text/event-stream and Cache-Control: no-cache, then keeps writing UTF-8 text. Each event is a group of field: value lines, and a blank line ends the event. A raw stream looks like this: retry: 5000, then id: 42, event: order.updated, data: {"id":42,"status":"shipped"}, a blank line, then : keepalive (a comment, because it starts with a colon) and another blank line. Multiple data: lines in one event are joined with newlines. id: sets the value the browser sends back as Last-Event-ID when it reconnects. retry: sets the reconnect delay in milliseconds.
Every proxy, load balancer and logging tool on the path sees a normal, slow HTTP response, so SSE inherits HTTP's authentication, compression and HTTP/2 multiplexing. The same property is the weakness: any intermediary that buffers responses will hold events back.
A WebSocket also begins as an HTTP GET, carrying Upgrade: websocket, Connection: Upgrade, Sec-WebSocket-Version: 13 and a random Sec-WebSocket-Key. The server replies 101 Switching Protocols with a Sec-WebSocket-Accept derived from that key. After that response the connection is no longer HTTP. Both sides exchange binary frames with opcodes for text, binary, ping, pong and close, and client-to-server payloads are masked. Each proxy must either understand the upgrade or pass raw bytes through, and that requirement drives most WebSocket proxy configuration.
GET /events HTTP/1.1
Host: api.example.com
Accept: text/event-stream
Last-Event-ID: 41
HTTP/1.1 200 OK
Content-Type: text/event-stream
Cache-Control: no-cache
retry: 5000
id: 42
event: order.updated
data: {"id":42,"status":"shipped"}
: keepalive
GET /ws HTTP/1.1
Host: api.example.com
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Version: 13
Sec-WebSocket-Key: dGhlIHNhbXBsZSBub25jZQ==
HTTP/1.1 101 Switching Protocols
Upgrade: websocket
Connection: Upgrade
Sec-WebSocket-Accept: s3pPLMBiTxaQ9kYGzzhZRbK+xOo=
A raw SSE exchange that remains an ordinary, never-ending HTTP response, next to a WebSocket upgrade handshake (using the RFC 6455 sample key and its derived accept value) after which the connection stops being HTTP.
Server-sent events vs WebSockets: when should you use each?
Start from traffic direction. If the server talks and the client mostly listens, SSE is the better default for notifications, activity feeds, job progress and dashboards. It is plain HTTP, so existing auth, logging, compression and load balancers work unchanged, and EventSource handles reconnection for you. Occasional client-to-server actions such as marking a notification read or cancelling a job fit naturally as ordinary POSTs.
Choose WebSockets when both sides send frequently and latency matters in both directions. Collaborative editing, multiplayer games and trading UIs fit this case. Sending each keystroke or input as a separate POST adds per-request overhead and gives you no ordering with the push stream. WebSockets also carry binary frames natively, which matters for compact encodings or media.
| Criterion | SSE | WebSockets |
|---|---|---|
| Direction | Server to client | Bidirectional |
| Payload | UTF-8 text only | Text or binary frames |
| Client-to-server | Separate HTTP requests | Same connection |
| Browser API | EventSource, no custom headers |
WebSocket |
| Network friction | Buffering proxies | Middleboxes that mishandle Upgrade |
Avoid SSE for binary data. Base64 inflates payloads by about a third and adds encode and decode work on both ends. Avoid WebSockets when clients sit behind corporate proxies or older middleboxes that strip or reject Upgrade. There you need a fallback path either way.
Other options exist. Long polling works almost everywhere but pays a request per message. Fetch-based streaming reads a chunked response body and, unlike EventSource, lets you set headers. WebTransport runs over HTTP/3 and offers multiplexed streams and unreliable datagrams.
Who should use SSE, and who should use WebSockets?
SSE fits teams that:
- Build features where the server pushes and the client mostly reads: notifications, feeds, build or job progress, monitoring dashboards, and streamed text output such as incremental generation results.
- Already run a mature HTTP stack (auth middleware, rate limiting, access control, tracing) and want real-time updates to reuse it rather than bypass it.
- Are small or lack dedicated real-time infrastructure experience. The protocol is text over HTTP, the browser handles reconnection, and debugging needs only
curl -N. - Can use cookie-based auth, or accept the cost of a fetch-based client if they need
Authorizationheaders.
WebSockets fit teams that:
- Build products where clients send frequent, latency-sensitive messages: collaborative editors, multiplayer games, trading or bidding UIs, chat with typing indicators and presence.
- Need binary payloads or compact binary encodings.
- Are prepared to own client-side reconnection, backoff, heartbeats and a resume protocol, or to adopt a library that provides them.
- Control enough of the network path, or serve over TLS, to avoid middleboxes that break
Upgrade.
Neither may be needed if updates arrive every few minutes and a delay of tens of seconds is acceptable. Periodic polling against a cacheable endpoint holds no long-lived connections, needs no proxy changes and scales on the infrastructure you already have. Teams whose users sit behind restrictive corporate networks should plan for a fallback such as long polling regardless of which primary protocol they pick.
How much reconnection and resume logic do you have to build yourself?
With SSE, the protocol does much of the resilience work for you. When the connection drops, EventSource reconnects on its own. The server can control the delay by sending a retry: field, in milliseconds. If events carried an id: field, the browser sends the last one it saw in a Last-Event-ID request header on reconnect. The client needs no extra code for this.
That header only tells the server where the client stopped. The server still has to do the following for resume to work:
- Assign monotonic event IDs per stream, so "everything after N" has a clear meaning. A sequence number or log offset works. Random UUIDs do not.
- Keep a replay buffer or durable log, such as an in-memory ring buffer, Redis stream or Kafka topic, that covers the longest gap you plan to tolerate. If the requested ID has already been evicted, send a signal that tells the client to do a full resync.
- Make clients idempotent, because a reconnect can deliver an event the client has already processed.
With WebSockets, all of this is application code. You write the close detection, the exponential backoff with jitter and the resume handshake. You also design a message format that carries sequence numbers. The server-side buffering is the same work for both protocols. The client-side difference is where SSE saves the most engineering time.
Authentication reduces that advantage. EventSource cannot set custom headers, so you cannot send Authorization: Bearer. Teams usually choose one of three workarounds:
- Cookies, which require CSRF and CORS credential handling.
- Query-string tokens, which end up in access logs and proxy logs.
- A fetch-based client, which supports headers but drops built-in reconnection and
Last-Event-ID, so you have to rebuild them.
// Minimal SSE server (Node.js, no dependencies) showing the server-side work resume needs.
const http = require('node:http');
const BUFFER_SIZE = 1000; // must cover the longest disconnect you plan to tolerate
const buffer = []; // in-memory replay buffer; lost on restart (use a durable log in production)
const clients = new Set();
let nextId = 1; // monotonic per stream, so "everything after N" is well defined
function send(res, evt) {
res.write(`id: ${evt.id}\ndata: ${evt.data}\n\n`);
}
function publish(payload) {
const evt = { id: nextId++, data: JSON.stringify(payload) };
buffer.push(evt);
if (buffer.length > BUFFER_SIZE) buffer.shift(); // evict oldest
for (const res of clients) send(res, evt);
}
http.createServer((req, res) => {
if (req.url !== '/events') { res.writeHead(404).end(); return; }
res.writeHead(200, { 'Content-Type': 'text/event-stream', 'Cache-Control': 'no-cache' });
res.write('retry: 5000\n\n'); // tell EventSource to wait 5s before reconnecting
// EventSource sends this header automatically on reconnect if events had ids.
const lastId = Number(req.headers['last-event-id']);
if (Number.isInteger(lastId) && lastId > 0) {
const oldest = buffer.length ? buffer[0].id : nextId;
if (lastId < oldest - 1) {
// Gap already evicted: tell the client to refetch full state instead of replaying.
res.write('event: resync\ndata: {}\n\n');
} else {
// Replay only what was missed; clients must still dedupe by id (idempotency).
for (const evt of buffer) if (evt.id > lastId) send(res, evt);
}
}
clients.add(res);
req.on('close', () => clients.delete(res));
}).listen(8080);
setInterval(() => publish({ ts: Date.now() }), 1000); // demo event source
A dependency-free Node.js SSE endpoint that sets the retry interval, assigns monotonic event IDs, replays missed events from a bounded buffer based on Last-Event-ID, and sends a resync event when the requested ID has already been evicted.
How do you fix nginx buffering for SSE and proxy WebSockets correctly?
Nginx buffers upstream responses by default. It reads from your backend into memory or temp files and sends data to the client in chunks, which suits page responses but breaks streams. An SSE event of a few hundred bytes can wait in the buffer until more data arrives, so clients see nothing and then a burst of events at once.
For the SSE location, set proxy_buffering off. If you want to control this per response instead, have the backend send X-Accel-Buffering: no, which nginx honors. Also set proxy_http_version 1.1 and clear the hop-by-hop header with proxy_set_header Connection "" so upstream keepalive works. Raise proxy_read_timeout above your heartbeat interval. The 60-second default closes quiet streams.
For WebSockets, the Upgrade and Connection headers are hop-by-hop, so nginx does not forward them unless told to. Use proxy_set_header Upgrade $http_upgrade and proxy_set_header Connection "upgrade", or derive the value with a map so one location can serve both upgrade and plain requests.
Nginx is not the only layer that can buffer:
- Compression: gzip in nginx or in app middleware waits to fill compression blocks. Disable it for
text/event-stream. - Framework middleware: some layers collect the whole body before sending it. The handler must flush after every event.
- Corporate proxies and antivirus: these may hold streams until they close, or strip
Upgrade. Serving over TLS usually avoids this.
To check the stream end to end, run curl -N against the public URL. The -N flag turns off curl's own output buffering. Each event should print as soon as the server emits it.
map $http_upgrade $connection_upgrade {
default upgrade;
'' close;
}
upstream app {
server 127.0.0.1:8080;
keepalive 16; # reuse upstream connections
}
server {
listen 443 ssl;
server_name example.com;
ssl_certificate /etc/nginx/tls/example.com.crt;
ssl_certificate_key /etc/nginx/tls/example.com.key;
# SSE: pass each event through as soon as the backend writes it
location /events/ {
proxy_pass
proxy_http_version 1.1; # needed for upstream keepalive
proxy_set_header Connection ""; # clear hop-by-hop header
proxy_buffering off; # or have the backend send X-Accel-Buffering: no
proxy_cache off;
gzip off; # compression would batch small events
proxy_read_timeout 1h; # must exceed the heartbeat interval
}
# WebSocket: forward the upgrade handshake explicitly
location /ws/ {
proxy_pass
proxy_http_version 1.1;
proxy_set_header Upgrade $http_upgrade;
proxy_set_header Connection $connection_upgrade;
proxy_read_timeout 1h; # idle sockets close at the 60s default
}
}
An nginx config that turns off buffering and gzip for an SSE location, forwards the Upgrade and Connection headers for a WebSocket location, and includes a curl -N command to confirm events arrive unbuffered.
Why do long-lived connections drop, and how should heartbeats be tuned?
Every hop between the client and your process keeps its own idle timer. That includes the cloud load balancer, the reverse proxy, any CDN, and the corporate proxy on the user's network, which you neither control nor see. Each hop closes a connection that carries no bytes for longer than its timeout. A stream that waits minutes between real events will be cut by whichever hop has the shortest timer. The client sees a dropped connection with no error from your server. In nginx, for example, proxy_read_timeout defaults to 60 seconds.
The fix is to send traffic before any timer expires:
- SSE: write a comment line, which is a line starting with
:, followed by a blank line.EventSourceignores comments, so they never fire handlers. They still count as bytes on the wire. - WebSockets: servers can send protocol-level ping frames, and compliant clients reply with pong automatically. Browser JavaScript cannot send pings or see them arrive, so a client that needs to detect a dead server needs an application-level heartbeat message with its own timeout.
Pick an interval comfortably below the shortest idle timeout in the path, such as 15–30 seconds against a 60-second limit. That margin absorbs scheduling delays and a single lost write. Because you rarely know the corporate proxy's timeout, err shorter.
Observability is the other gap. Most proxies write access log lines when a response ends, so a healthy SSE stream produces no log entry for hours. Track connection-level metrics instead: open connections, connection duration, disconnect reasons, and time since the last write per connection.
// Minimal Node.js SSE server: heartbeats under the shortest idle timeout,
// plus per-connection metrics, because access logs only appear when a stream ends.
const http = require('node:http');
const HEARTBEAT_MS = 20_000; // well below a 60 s proxy idle timeout
const conns = new Map(); // res -> { openedAt, lastWriteAt }
function send(res, chunk) {
res.write(chunk);
conns.get(res).lastWriteAt = Date.now(); // track time since last byte on the wire
}
http.createServer((req, res) => {
if (req.url !== '/events') { res.writeHead(404).end(); return; }
res.writeHead(200, {
'Content-Type': 'text/event-stream',
'Cache-Control': 'no-cache',
'X-Accel-Buffering': 'no', // ask nginx not to buffer this response
});
conns.set(res, { openedAt: Date.now(), lastWriteAt: Date.now() });
// A line starting with ':' is a comment: EventSource ignores it, but every hop sees bytes.
const hb = setInterval(() => send(res, ': heartbeat\n\n'), HEARTBEAT_MS);
req.on('close', () => {
clearInterval(hb);
const { openedAt } = conns.get(res);
conns.delete(res);
// Emit duration at disconnect so long streams are visible in metrics/logs.
console.log(JSON.stringify({ event: 'sse_disconnect', durationMs: Date.now() - openedAt }));
});
}).listen(8080);
// Periodic connection-level gauges instead of waiting for access log lines.
setInterval(() => {
const now = Date.now();
let maxIdleMs = 0;
for (const c of conns.values()) maxIdleMs = Math.max(maxIdleMs, now - c.lastWriteAt);
console.log(JSON.stringify({ metric: 'sse_open_connections', value: conns.size, maxIdleMs }));
}, 10_000);
A Node.js SSE endpoint that sends comment-line heartbeats every 20 seconds to stay under a 60-second idle timeout, and reports open connections, connection duration and time since last write instead of relying on access logs.
What limits SSE scaling: browsers, HTTP/2 and server resources?
Those connection metrics also show where SSE stops scaling, and the first limit is in the browser. Over HTTP/1.1, browsers cap concurrent connections per origin, commonly cited as six. Each EventSource holds one of those slots for as long as it stays open. If a user has five tabs open, only one slot is left for API calls, so fetches queue behind the streams and the app appears to hang.
HTTP/2 removes that cap by multiplexing many streams over one connection, up to a stream limit the server advertises. The browser only benefits if the hop it connects to speaks HTTP/2. That hop might be TLS termination, a CDN, or a proxy. Your origin may support HTTP/2 while a load balancer in front of it serves HTTP/1.1. Check the protocol in browser devtools for each deployment and don't assume it.
| Limit | Symptom | Mitigation |
|---|---|---|
| File descriptors | Accept errors when the limit is reached | Raise ulimits on app and proxy hosts |
| Memory per connection | Memory grows with idle clients | Keep per-stream buffers and state small |
| Thread-per-request runtime | Thread pool exhausted by idle streams | Use an event loop or lightweight threads |
| Proxy connection limits | Refused or reset connections | Size the proxy for two sockets per stream (client and upstream) |
Slow consumers are the remaining risk. A client on a poor network can accumulate an unbounded queue in server memory. Cap each connection's queue. When it fills, drop low-value events or disconnect the client and let it resume.
Plan capacity around peak concurrent connections, not requests per second. A server can handle a low request rate and still fail at a high connection count.
How do you handle fan-out, deploys and reconnect storms with either protocol?
Shared architecture: stateless nodes plus a pub/sub backbone
Once you run more than one node, SSE and WebSockets use the same design. App nodes hold sockets but no authoritative state. Producers publish to a backbone such as Redis pub/sub or a message broker, and each node forwards messages for the topics its local clients subscribe to. Redis pub/sub is best-effort: a node that is briefly disconnected loses whatever was published during the gap. If clients need guaranteed delivery, write events to a durable log with ordered IDs and replay from the client's last ID on reconnect. The broker is also a new failure domain. When it stalls, every node goes quiet at once, so alert on subscriber lag and not only on node health.
Deploys and reconnect storms
During a rolling deploy, stop accepting new connections on the old instance and close existing ones gradually over a drain window. Clients should reconnect with randomized backoff. Expect connection counts to drift after a deploy. Old connections stay on the instances that survived, and new instances start nearly empty. Capping connection age forces gradual rebalancing. Autoscaling on CPU or request rate misses this kind of saturation, so scale on concurrent connections per node.
Illustrative estimate, not a measured result: assume 200,000 clients drop when a broker fails over. If they all reconnect within 2 seconds, auth receives about 100,000 token validations per second, and the replay store receives the same number of reads. If clients spread reconnects over a jittered 60-second window, both loads fall to about 3,300 per second.
How does the choice affect development cost?
Most of the cost of real-time features comes from the work around the protocol, not the protocol itself. The main cost drivers are:
- Client resilience code. SSE gets reconnection and
Last-Event-IDfrom the browser. With WebSockets you write and test close detection, backoff with jitter, application-level heartbeats and a resume handshake, or you take on a client library and its maintenance. - Server-side resume. Monotonic IDs, a replay buffer or durable log, resync signalling and idempotent clients cost the same for both protocols. Budget for them whenever clients must not miss events.
- Auth. SSE's lack of custom headers can add CSRF and CORS work for cookies, or force a fetch-based client that gives up the built-in reconnection. WebSockets have their own handshake-auth decisions. Either way, decide early, because changing the auth model later touches every client.
- Infrastructure configuration. Each proxy, load balancer and CDN in the path needs buffering, upgrade handling and idle timeouts set correctly, and those settings differ per environment.
- Operations. Long-lived connections need connection-level metrics, connection-based autoscaling, drain logic for deploys and capacity planning around concurrency. Request-oriented dashboards and alerts do not cover them.
- Fallbacks. Supporting users behind restrictive networks may mean building and maintaining a second transport such as long polling.
Running cost scales with concurrent connections rather than request volume. Illustrative estimate, not a measured result: assume 100,000 concurrent clients and an assumed 50 KB of memory per connection across app process, socket buffers and per-stream queue. That is roughly 5 GB of memory held just for idle connections, before any message processing. The proxy holds its own client and upstream sockets on top of that. Measure per-connection memory on your own runtime before sizing anything, because the real figure varies widely with language, framework and queue limits.
Choosing the protocol that matches the traffic pattern is the largest cost lever. Using WebSockets for a one-way feed means paying for bidirectional client machinery you never use. Using SSE for a highly interactive feature means paying for many extra POSTs and for ordering logic between two channels.
How can SSE or WebSockets save engineering time?
Time savings come from reusing what already exists and from doing the hard parts once:
- Reuse the HTTP stack with SSE. Auth middleware, rate limiting, tracing and request validation apply to the stream without new code. Client actions go through existing POST endpoints with their existing tests.
- Let the browser handle reconnection. With
EventSource, the client-side reconnect, delay andLast-Event-IDhandling are already done. That is the code most often written incorrectly in WebSocket clients. - Debug with standard tools. An SSE stream is readable text, so
curl -Nagainst the public URL shows whether events arrive, arrive late or arrive in bursts. That quickly isolates buffering in a proxy, compression layer or framework. - Build the backbone once. The stateless-node plus pub/sub design, durable event log, monotonic IDs and replay logic serve both protocols. A team that later adds a WebSocket feature reuses all of it.
- Standardise the edge configuration. Keep a reviewed proxy config for streaming locations (buffering off, compression off, timeouts above the heartbeat interval, upgrade headers forwarded) and reuse it across services instead of rediscovering each setting during an incident.
- Instrument connections from the start. Open connections, duration, disconnect reasons and time since last write turn "users say updates are delayed" from a long investigation into a dashboard check.
- Default to the simplest option that fits. Use polling when latency tolerance allows it, SSE for one-way push and WebSockets only where both directions need low latency. Each step up adds code and operational surface that someone has to maintain.
Illustrative estimate, not a measured result: assume a team ships three one-way push features and that each WebSocket implementation would need an assumed three engineer-days for client reconnection, heartbeats and resume handling that EventSource already provides. Choosing SSE for those features avoids roughly nine engineer-days of client work, minus any time spent on the cookie or fetch-based auth workaround. Substitute your own assumed effort figures; the point is that the saving repeats per feature, while the shared server-side work is paid once.
How OneEnv can help
Disclosure: OneEnv is the product behind this blog.
OneEnv (oneenv.io) is a workspace-based governance platform for the things services share — environment variables, database structure, API routes and validation rules. A change to a shared value is staged on a branch, reviewed once, and then every affected service explicitly approves or rejects it before it goes live, so you can see who a change touches before it ships instead of finding out in production.
Applied to server-sent events vs websockets, this is where it helps:
Saves time
- Every service that inherits a shared value is listed in one place, so nobody searches repos and chats to find out who is affected.
- One review per branch replaces coordinating each team separately; each service still keeps its own approve/reject.
- Changing a shared variable is one edit and one review instead of editing every service's
.envby hand.
Saves cost
- Fewer production incidents and rollbacks caused by a shared value, route or column changing under a consumer unannounced.
- Less duplicated configuration to maintain: one shared definition inherited by many services.
- A wrong or stale value is caught at review time by the services it affects, not by a failed deploy.
- OneEnv has a free plan (1 workspace, unlimited services and members, full governance), so trying it costs nothing.
These are qualitative benefits, not measured results — how much you save depends on how many services share the value.
Want to try it? Start at oneenv.io.