Slow Clients and Backpressure

A server writing a 2 GB export to a client reading at 1 MB/s does not "send the file". It writes into a kernel socket buffer; the kernel sends as fast as the client acknowledges; TCP flow control stops the sender when the client's receive window fills (Flow Control: The Receive Window). Above the kernel, the application has its own buffers — the HTTP framework's write queue, the WebSocket library's outbound message queue, whatever the handler awaited on. If the application keeps producing while the socket is stalled, those buffers grow. Unbounded, they grow until the process is out of memory — and because one process serves many clients, one slow client's backlog takes every fast client with it (The Buffer Chain, What Happens When the Receiver Is Slow).

That is the whole problem: something must stop the producer when the consumer is behind, and the contract decides what. Three honest answers exist. *Backpressure*: the producer awaits the write; a stalled socket pauses the query, the file read, the event generation — bounded memory, unbounded time. *Drop*: the server keeps a bounded queue per client and discards (oldest or newest) when full, telling the client it did. *Disconnect*: the server closes when the client falls more than N behind or stays idle longer than T, and the contract says how to resume. Silence — an unbounded queue and hope — is the fourth, and it is the one most frameworks default to.

The choice depends on what the stream *is*. A download or export must not drop bytes: backpressure, with a resumable position for when the connection dies. A live feed of prices or presence updates may drop stale intermediate values as long as the client learns it missed some and can resync. A stream of ordered domain events (see Streaming APIs: Partial Data as a Contract) usually cannot drop, so it backpressures and eventually disconnects the client that cannot keep up — with a cursor so the client catches up later, not from scratch.

For downloads and exports the contract clauses are: Content-Length when known (so clients can show progress and detect truncation), Accept-Ranges: bytes with support for Range requests so an interrupted transfer resumes from an offset rather than restarting (HTTP: Requests, Responses, Headers and Status Codes), chunked transfer when the length is unknown, an idle timeout ("if no bytes are acknowledged for 60 s the server closes the connection") and a total ceiling if one exists. Large artifacts often should not stream through the API at all — hand back a signed object-storage URL and let a system built for byte-serving do it (File Upload APIs: Authorize, Upload Directly, Confirm in reverse).

For event streams (SSE, WebSocket) the clauses are about messages, not bytes: a per-connection outbound queue with a stated bound (in messages or bytes), the policy at the bound — pause the producer, coalesce (keep only the latest value per key), drop with a {"type":"gap","from":…,"to":…} marker, or close with a documented code — sequence numbers on every message so gaps are detectable, and a resume cursor (Last-Event-ID for SSE, an explicit resume_from on WebSocket subscribe) so a reconnecting client catches up from where it stopped rather than replaying everything or missing everything (Server-Sent Events, WebSocket Message Contracts). Heartbeats with a miss-count define "dead" so half-open connections do not hold buffers forever.

Disconnect is a legitimate contract outcome, not a failure, if it is *announced* and *resumable*: a WebSocket close code like 4008 SLOW_CONSUMER with the last delivered sequence, an SSE stream ending with a final event: overflow carrying the cursor. The client that is told why it was dropped and where to resume can decide to catch up or to switch to a coarser feed; the client that just sees EOF reconnects instantly and gets dropped again.

The server must not buffer without bound, and must not let one connection's backlog consume shared memory: per-connection limits plus a tier-wide budget, so the response to an overrun is closing *that* client, not OOM-killing the process that serves ten thousand others (Memory Pressure, Swap and the OOM Killer). It must not interpret a stalled socket as "the client went away" without a timeout — a mobile client behind a tunnel can legitimately stall for seconds. And it must not hide the policy: if messages can be coalesced or dropped, the docs and the message schema say so, or consumers will build exactly-once assumptions on a best-effort feed.

The client side of the contract is real too. Clients read as they parse — streaming JSON/NDJSON parsers, not await response.text() on a 2 GB body. They honor Range and Last-Event-ID on reconnect instead of restarting. They back off on 4008-style closes rather than reconnecting in a tight loop, which is the client-side version of the same overload. Publishing a reference client or SDK helper for the stream (SDK Design: The Contract's User Interface) is how most providers make those behaviors the default rather than a hope.

HTTP/2 adds a layer: many streams share one connection, with per-stream and per-connection flow-control windows (HTTP/2: Streams on One Connection). One slow stream can stall the connection's window for the others — which is why an API multiplexing a bulk download beside interactive requests on the same connection sees head-of-line effects it did not design for. The contract-level answer is usually to serve bulk bytes from a different host or a signed URL, keeping the interactive API's connections short and cheap.