Learn

Architecture & pattern guides

Read the idea, build it on a Grid, prove it in a challenge. Short, practical guides — illustrated with RodGrid's own nodes — on system design, design patterns, flow modeling, and how to get the most out of the app.

All articles

Realtime transport: long-polling vs SSE vs WebSocket

Three ways to push to a browser, chosen by which way the messages flow and how often: proxies that buffer, idle timeouts and heartbeats, how each transport resumes after a drop, and the fallback ladder that keeps one event stream behind all three.

Should the build page use a WebSocket?

That was the first question when a hosted CI service decided to make its build page live. The page shows the log of a running build, a few lines a second most of the time and hundreds a second during the test run. It has a Cancel button, pressed at most once per build. And the team wanted, later, a debug shell into the runner of a failed build. The reflex answer is one WebSocket for all of it, the most capable and the most demanding to operate of the three transports compared here. A better answer comes from looking at each feature on its own.

Long-polling is a plain HTTP request the server holds open until it has something, or about 30 seconds pass, after which the client immediately asks again. Server-Sent Events (SSE) is one HTTP response that never ends, streaming data: lines down to the browser, with built-in reconnection and a Last-Event-ID header. WebSocket upgrades the connection to a full-duplex stream of frames, both directions, with no HTTP framing after the handshake.

Draw the arrows first

The log flows one way, server to browser, and there is a lot of it. That is SSE's shape, shared by notifications, live scores and price tickers. It is ordinary HTTP, so it crosses proxies, load balancers and CDNs as long as they do not buffer the response (disable buffering for text/event-stream). Over HTTP/2, several streams share one connection, and the browser reconnects on its own and tells the server the last event it received. Putting this feed on a WebSocket would give up automatic reconnection and, on most paths, HTTP/2 multiplexing, to gain a direction it never uses. How HTTP/2 shares one connection among streams is in Network protocols: TCP, UDP, HTTP/2 & HTTP/3.

Cancel flows the other way, once. It is an ordinary POST /builds/812/cancel, with a status code and nothing to keep open. Next to an SSE stream, every message from the client is a separate request like this one: fine once per build, wasteful once per keystroke.

Keystrokes are the debug shell, and there both directions carry traffic at typing speed. A WebSocket pays its way: each keystroke goes up as a frame with a few bytes of header, and the output comes back on the same connection. Chat, collaborative editing and multiplayer games share that shape, a client that sends about as often as it receives. Live call audio and video are a different problem, usually carried by WebRTC rather than by any of these three; Realtime media: WebRTC, SFUs & NAT traversal covers it. And when the tab is closed, none of the three reaches the user at all; that is the job of mobile push and email, in Notifications & transactional messaging.

That leaves long-polling, the transport for when the others cannot get through: corporate proxies that buffer streaming responses, and ancient clients. The build page met the first kind within a week.

The log that arrived all at once

A customer at a bank reports that the live log is not live: nothing appears for eleven minutes, then the whole build's output at once, when the build ends. The bank's outbound proxy reads each response to its end before passing it on, to inspect it, and an SSE response does not end until the build does.

Your own infrastructure can do the same to every user: a reverse proxy that buffers responses holds the stream just as well. On the hops you control, the fix is configuration: turn off buffering for text/event-stream (nginx, for one, honours an X-Accel-Buffering: no response header), and send Cache-Control: no-store so nothing caches the stream by accident. A proxy you do not control needs a transport that survives buffering, one where every response is short and complete: long-polling.

The browser asks GET /builds/812/log?since=4812. The server answers at once if there are lines after 4812, or holds the request for up to about 30 seconds until one arrives, and the browser asks again from the new position. The cursor is the whole mechanism: without it, a server that returns only what is new at that moment loses the lines written between one response and the next request. The cost shows when the log is busy, since every batch of lines then pays a full request cycle, where a stream would have sent them on a connection already open.

Two quiet minutes

Then the stream starts dropping, but only in builds that compile a large project for two minutes without printing a line. Load balancers and proxies close connections that carry nothing for a while, often after about 60 seconds. The cure is never to stay silent that long: on SSE, a comment line (one that starts with :, which the browser ignores) every 20–30 seconds; on a WebSocket, a ping frame at the same interval. A heartbeat that must be answered also reveals a connection that died without closing. Browsers answer WebSocket pings themselves without telling the page, so a page that wants to notice a dead connection needs a heartbeat message of its own.

Picking up where the stream broke

Every transport drops: mobile radios change networks, proxies time out, deploys close connections. What matters is what the client misses meanwhile, and each transport answers that differently:

  • SSE resumes by design. The server tags each event with an id: line, here the log line number. When the stream breaks, the browser reconnects by itself and sends the last id it saw in a Last-Event-ID header, and the server sends the events after it. The browser also reconnects when the server ends the stream on purpose, so the build's last event should tell the page to call close(). That works only if the server still holds the lines after 4,812 when asked, so the log has to be stored, not just passed through, and a client whose missing lines were already discarded must be told to reload.
  • Long-polling reconnects on every cycle by nature, and resumes with its cursor.
  • WebSocket gives you neither. The client implements reconnection with backoff and jitter, the waiting rule Retry explains, and a resume token, such as the last sequence number it applied, which it sends after reconnecting so the server can replay the gap. The heartbeat is yours to write too.

So design as if every client reconnects every minute: history the server can replay, and sends that are safe to repeat. A cancel retried after its response was lost should cancel once, the property Idempotency & exactly-once illusions works through.

A WebSocket also needs upgrade support at every hop, and, like an SSE stream, a server that holds an open connection per user; what that costs a fleet, and what a deploy does to all those connections at once, is in WebSockets at scale: gateways, routing & draining.

One stream behind three doors

The service ends with one event stream per build and three ways out of it. A client library with a fallback ladder tries WebSocket, falls back to SSE, then to long-polling; the build log only listens, so its ladder starts at SSE, and steps down to long-polling when the first event, which the server sends at once, does not arrive within a few seconds. The server exposes the same log events on all three, so a downgrade changes the log's latency, not its features; the debug shell, which needs both directions, keeps its own WebSocket.

One event stream, three transports at the edge

The log's events are identical on all three; only the last hop differs. The debug shell is its own two-way session.

Bids up, prices down

The Online Auction Challenge is the classic mismatch: the server pushes the high bid to every watcher constantly, and a watcher bids once a minute at most. Write the transport on the client-facing edge and defend it by direction: bids up as POST, each with a real status code and room for an idempotency key, prices down as SSE, or a WebSocket only if both directions need it. The WebSocket Gateway node can stand for the SSE server, since the catalog describes it as a realtime server for WebSocket or SSE. Then label the resume mechanism on that edge. Chat System and Collaborative Whiteboard are the two-way cases where the WebSocket is the honest choice.

Practice this