Skip to content

Limits and deadlines

What bounds an HTTP request and its connection — the body cap, the request budget, the connection cap, each phase's deadline and the shutdown window.

Every wait the HTTP transport owns is bounded: what a request may send, how long it may run, how many connections it serves at once, how long each phase of a connection may stall, and how long the way down waits. Each bound is a field of HttpConfig, set through <PREFIX>_HTTP__* or pinned in code, and a value outside its range fails the boot naming the variable.

Whatever reads a request body — an extractor such as Json<T> or RawBody, a guard, a global pipe — reads at most max_body_bytes: 2 MiB by default, so a runaway upload can’t exhaust memory. The transport itself reads no body. It is read by whoever needs it, after routing and the guards, so a refused request is answered before a byte of its body is taken, and a refused client that sent Expect: 100-continue is never told to go ahead. Only a declared Content-Length past the cap is refused up front, unread. Past the cap a read fails and the request is answered 413, whatever the reader made of the failure. Raise or lower it globally, from one byte to a tebibyte; a value outside that fails the boot naming the variable:

.env.production
NESTRS_HTTP__MAX_BODY_BYTES=4194304 # 4 MiB

A single route that needs a tighter cap reads its body under its own (see RawBody); the config value is the default for everything else.

request_timeout bounds how long one request may run, so a slow or stuck request can’t tie up a connection indefinitely. It counts from the request’s arrival, so a body that trickles in a byte at a time counts against it; one that stops arriving altogether is answered sooner, 408, by the body-read deadline. A body that stops within the budget’s last BODY_READ_TIMEOUT_SECS is answered the budget’s 503 with Retry-After, not 408: the budget fires first. With that deadline at or past the budget every stalled body is, which one warn says at boot. Default 20 seconds — the shutdown window’s own, so a request admitted just before a stop is answered inside the window rather than cut; <PREFIX>_HTTP__REQUEST_TIMEOUT_SECS=0 turns it off — the framework-wide spelling every duration ceiling uses, so 0 never means “zero seconds”. The OpenAPI document follows: every route lists the 503 while the budget is on, and a route taking a body the 408 while the gap sits under it:

.env.production
NESTRS_HTTP__REQUEST_TIMEOUT_SECS=15
NESTRS_HTTP__REQUEST_TIMEOUT_SECS=0 # no timeout at all

A handler that exceeds it is aborted and the client gets 503 Service Unavailable with a Retry-After naming the budget — not 504. RFC 9110 §15.6.5 scopes 504 Gateway Timeout to a server “acting as a gateway or proxy” whose upstream was slow; this transport is the origin, and the handler that overran is its own work. The distinction is not cosmetic: a client SDK or a load balancer that retries a 504 on another node is acting on “that node’s upstream is flaky”, and re-runs a handler that will overrun again. §15.6.4 is the origin’s own sentence — explicitly temporary, and paired with Retry-After.

Under a unit of work (SeaOrmDatabaseModule) the timeout cuts the handler alone: its writes roll back, so the 503 is honest. A handler that answered in time answers its own status however long its commit takes, and 500 without Retry-After when the commit never answered, since its writes may have landed (Transactions).

A budget longer than the window, or none at all, files one warn on nest_rs::http at boot — the request timeout outlasts the shutdown window, with request_timeout_ms (0 when off) and shutdown_timeout_ms — and the app still boots: a deployment may accept it knowingly. One with handlers longer than the default raises the timeout, the window and the pod’s grace period together. The framework’s own nets under a request — the authentication guard’s, the throttler’s, the queue port’s — wait 18 seconds, so a backend that hangs is named by what waited on it rather than by this 503.

The timeout bounds a request until its response head leaves, so the units an upgraded socket or an event stream carries past that point take timeouts of their own, at the same 20-second default and with the same boot warn: a WebSocket message and its socket’s connection hooks, <PREFIX>_WS__MESSAGE_TIMEOUT_SECS, <PREFIX>_WS__CONNECT_TIMEOUT_SECS and <PREFIX>_WS__DISCONNECT_TIMEOUT_SECS, and an MCP operation, <PREFIX>_MCP__OPERATION_TIMEOUT_SECS.

The transport accepts its connections itself, on hyper, and serves at most max_concurrent_connections at once — 10 000 by default. Past it, a new connection waits until one closes — the next one accepted and held unserved, the rest in the kernel’s listen backlog: its client sees latency, then the kernel’s own refusal once the backlog is full, never a reset of a connection it already holds. A socket upgraded to a WebSocket counts until it closes. When a connection waits on the cap, one warn on nest_rs::http names the variable, and one info follows once none waits any more — a pair for a busy spell, not one per connection, and none for connections that never wait:

.env.production
NESTRS_HTTP__MAX_CONCURRENT_CONNECTIONS=50000

Whole numbers from 1 to 1048576, Linux’s default ceiling on the files one process opens; anything outside fails the boot naming the variable, set in the environment or pinned. A cap above the process’s own file limit (ulimit -n) is met by the kernel first, so raise the two together.

Behind a proxy that caps its connections to each upstream — nginx’s max_conns, Envoy’s circuit breakers — keep this cap at or above the proxy’s, or the replica holds back connections the proxy believes it may open.

What one connection may do is fixed:

  • an HTTP/2 connection runs at most 200 streams at once, the limit it advertises in SETTINGS_MAX_CONCURRENT_STREAMS (RFC 9113 §5.1.2), and a client resetting streams faster than they are answered is sent GOAWAY (CVE-2023-44487);
  • an HTTP/1 request head larger than 64 KiB is answered 431 Request Header Fields Too Large (RFC 6585 §5) rather than buffered, and an HTTP/2 header list larger than 16 KiB, the limit the connection advertises in SETTINGS_MAX_HEADER_LIST_SIZE (RFC 9113 §6.5.2), is answered 431 on its stream alone, the connection serving on. A request target counts in both — the head’s first line, or :path in the list — so one past them is answered 431 too, where RFC 9112 §3 names 414 URI Too Long for a request line: hyper, which reads the head, cannot tell the two apart (hyperium/hyper#3874). Short of those bounds, a long target reaches the router like any other;
  • a client speaking HTTP/2 from its first byte is served in plaintext too, and every socket is written without Nagle’s delay (TCP_NODELAY).

Each phase of a connection has a deadline, so a client holding one without using it gives its place under the cap back. Each is a <PREFIX>_HTTP__ key:

PhaseDeadline, fromAt the deadline
The first request headHEADER_READ_TIMEOUT_SECS, 30 s from accept — a TLS handshake and HTTP/2’s preface inside itclosed
Idle, nothing in flightIDLE_TIMEOUT_SECS, 75 s from the last answer’s endHTTP/1 closed, HTTP/2 sent GOAWAY
A later HTTP/1 headHEADER_READ_TIMEOUT_SECS from its first byte, or the idle deadline if soonerclosed
A request body that stops arrivingBODY_READ_TIMEOUT_SECS, 10 s from its last frame, once something reads itanswered 408 Request Timeout (RFC 9110 §15.5.9) — HTTP/1 with Connection: close, HTTP/2 that stream alone; within the budget’s last gap, the budget’s 503 first
A write the peer takes nothing ofSEND_TIMEOUT_SECS, 60 s from the write that started waitingdropped — on HTTP/2, a stream the peer grants no window is reset and its connection serves on

A request in flight has no other connection deadline: its own budget bounds the handler and the reading of its body, the body-read deadline a body that stops arriving — the one bound on it when the budget is off, as for a long upload — and the send deadline bounds a response — an event stream or a WebSocket included — whose peer stops reading. That one runs only while a write waits, from the moment it starts waiting, so a slow reader that keeps taking bytes is never cut. Each cut files one warn, the peer took nothing within the send deadline; it is cut off, on its edge’s target: nest_rs::http, nest_rs::ws or nest_rs::graphql. On HTTP/2 it holds a response to its last byte: a stream whose window stays shut is reset whatever is left to send.

Each key takes whole seconds; 0 turns none of them off, and a value outside its range fails the boot naming the variable, set in the environment or pinned:

.env.production
NESTRS_HTTP__HEADER_READ_TIMEOUT_SECS=10
NESTRS_HTTP__BODY_READ_TIMEOUT_SECS=15
NESTRS_HTTP__IDLE_TIMEOUT_SECS=620
NESTRS_HTTP__SEND_TIMEOUT_SECS=120

Behind a load balancer, keep IDLE_TIMEOUT_SECS above the balancer’s own idle timeout for its connections to this server. A balancer that keeps one open longer reuses it as the server closes it, and answers that request 502. The default clears the 60 seconds of AWS’s Application Load Balancer and of nginx’s upstream keep-alive; Google Cloud’s load balancer keeps 600, so set 620 behind it. The debug boot line transport listening carries idle_timeout_ms beside the address the transport bound, for the day intermittent 502s send you looking.

On SIGTERM or SIGINT the transport stops accepting, ends what has no end of its own — a stream, a socket — the way its protocol ends one, and gives what is still answering shutdown_timeout to finish — 20 seconds by default. It is the first of the bounded steps on the way down: the window, then half a second for what the transport stopped to unwind, then five seconds for the shutdown hooks, then three for the telemetry flush, then one for the console — 29.5 seconds, under the 30 a Kubernetes pod gets between SIGTERM and SIGKILL. Raise the window together with the pod’s grace period, keeping the nine and a half seconds after it and any preStop delay before it, the sleep that takes the replica out of the load balancer before the signal:

.env.production
NESTRS_HTTP__SHUTDOWN_TIMEOUT_SECS=55 # beside a 5 s preStop sleep and terminationGracePeriodSeconds: 70

Whole seconds from 1 to 3600; anything outside fails the boot naming the variable, and so does a pinned value outside the range. 0 is refused rather than read as “off” — the spelling REQUEST_TIMEOUT_SECS uses — because a shutdown that waits without a bound is what the window exists to prevent.

What the window does depends on what the connection is doing:

  • Idle — a kept-alive connection with nothing in flight is closed at the signal; the window is not spent on it.
  • A request still running — is answered, and its connection closed after the answer. With the defaults its budget ends inside the window, so it is answered at the latest with its 503. If the window closes first — a budget past the window, or none — the connection is dropped, the client gets no answer and the handler is cancelled where it waits — over HTTP/1.1 and over HTTP/2 alike: closing an HTTP/2 connection resets every stream on it, and hyper drops a reset stream’s handler. Its http.request line is still filed, with outcome="cancelled" and the time it ran in place of a status and bytes, since nothing was answered. Its span exports like an answered one’s — named GET /reports/{id} for the route the router matched, with http.route — and failed: error.type is cancelled, the status Error.
  • A stream with no end of its own — an #[sse] stream, an MCP session’s standalone GET stream — is ended at the signal, cleanly: its last chunk is written, so the client’s EventSource reads an end and reconnects, to a replica still in the load balancer. Waiting would only have spent the whole window on an end that is not coming. Its http.request line carries the head’s status, the bytes written, and outcome="cancelled", since the transport ended it rather than the stream.
  • A body with an end of its own — a download — is a response still being answered: it gets the window, and is cut at its close, its line carrying the head’s status, the bytes written before the cut and outcome="cancelled".
  • A WebSocket — a gateway’s socket is closed at the signal with RFC 6455’s 1001 Going Away, after the message it is answering; a graphql-ws socket first completes each subscription still running and answers what is still answering, then closes the same way. A message or a subscription still running when the window closes is dropped with its socket, and files its line cancelled. A socket a hand-built self-mount upgraded is the developer’s own: the transport cannot see inside it, so it neither waits for nor closes one — it ends when its handler ends it, or with the process.
  • An MCP operation still running — runs on a task of rmcp’s rather than on the connection that asked for it, so it gets the window like a request, and the transport stops it itself once the window has closed: it is dropped where it waits, files its mcp.operation line with outcome="cancelled", and one warn names how many were stopped. A subscriptions/listen is answered its final result at the signal instead, since a subscription has no end of its own.

What the transport stopped at the close gets half a second to unwind, once for all of it — the connections it cut, the HTTP/2 streams they ran and every mount’s work together — so none of it is still running when the shutdown hooks start, and the transport is back within its stop bound, the window and that half second. What still runs then — a handler or a unit blocking its thread — is left to end on its own and named: a connection or a stream at warn, a mount’s work at error. When the window closes on open connections, one warn on nest_rs::http counts them: cut, the connections it closed, and upgraded_open, the sockets a hand-built self-mount left open. The shutdown hooks run once every transport has stopped, five seconds between all of them — see Lifecycle — so keep the grace period above this window plus the half second, theirs, the flushes’ and any preStop delay.

A client that goes away mid-request is seen only if it resets. The line of a request whose client stopped waiting depends on how the client left:

  • An abortive close — a reset: an HTTP/2 stream cancelled, a socket closed with SO_LINGER of zero, a process that crashed — drops the request where its handler waits, exactly as the window does, and it files outcome="cancelled" with no status.
  • An ordinary close — close() after a timeout, a browser navigating away, curl giving up — is a half-close over HTTP/1.1, which is legal: a client may send its request, shut its writing side and still read the answer. So hyper does not take it for an abandonment while the handler runs; the handler runs to its end, the answer is written to a socket nobody reads, and the line is filed with that status and bytes.

hyper’s reading is the specification’s, so outcome="cancelled" counts the requests the server could see were abandoned — never every client that stopped waiting.

  • HTTP configuration — every HttpConfig field, its variable and its pinned form.
  • Shutdown — every bounded step from the signal to the exit.
  • Transactions — what a request’s deadline does to its unit of work.