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.
Request-body size limit
Section titled “Request-body size limit”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:
NESTRS_HTTP__MAX_BODY_BYTES=4194304 # 4 MiBA 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
Section titled “Request timeout”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:
NESTRS_HTTP__REQUEST_TIMEOUT_SECS=15NESTRS_HTTP__REQUEST_TIMEOUT_SECS=0 # no timeout at allA 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.
Connections
Section titled “Connections”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:
NESTRS_HTTP__MAX_CONCURRENT_CONNECTIONS=50000Whole 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
200streams at once, the limit it advertises inSETTINGS_MAX_CONCURRENT_STREAMS(RFC 9113 §5.1.2), and a client resetting streams faster than they are answered is sentGOAWAY(CVE-2023-44487); - an HTTP/1 request head larger than
64 KiBis answered431 Request Header Fields Too Large(RFC 6585 §5) rather than buffered, and an HTTP/2 header list larger than16 KiB, the limit the connection advertises inSETTINGS_MAX_HEADER_LIST_SIZE(RFC 9113 §6.5.2), is answered431on its stream alone, the connection serving on. A request target counts in both — the head’s first line, or:pathin the list — so one past them is answered431too, where RFC 9112 §3 names414 URI Too Longfor 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).
Connection deadlines
Section titled “Connection deadlines”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:
| Phase | Deadline, from | At the deadline |
|---|---|---|
| The first request head | HEADER_READ_TIMEOUT_SECS, 30 s from accept — a TLS handshake and HTTP/2’s preface inside it | closed |
| Idle, nothing in flight | IDLE_TIMEOUT_SECS, 75 s from the last answer’s end | HTTP/1 closed, HTTP/2 sent GOAWAY |
| A later HTTP/1 head | HEADER_READ_TIMEOUT_SECS from its first byte, or the idle deadline if sooner | closed |
| A request body that stops arriving | BODY_READ_TIMEOUT_SECS, 10 s from its last frame, once something reads it | answered 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 of | SEND_TIMEOUT_SECS, 60 s from the write that started waiting | dropped — 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:
NESTRS_HTTP__HEADER_READ_TIMEOUT_SECS=10NESTRS_HTTP__BODY_READ_TIMEOUT_SECS=15NESTRS_HTTP__IDLE_TIMEOUT_SECS=620NESTRS_HTTP__SEND_TIMEOUT_SECS=120Behind 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.
Shutdown
Section titled “Shutdown”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:
NESTRS_HTTP__SHUTDOWN_TIMEOUT_SECS=55 # beside a 5 s preStop sleep and terminationGracePeriodSeconds: 70Whole 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. Itshttp.requestline is still filed, withoutcome="cancelled"and the time it ran in place of astatusandbytes, since nothing was answered. Its span exports like an answered one’s — namedGET /reports/{id}for the route the router matched, withhttp.route— and failed:error.typeiscancelled, the statusError. - A stream with no end of its own — an
#[sse]stream, an MCP session’s standaloneGETstream — is ended at the signal, cleanly: its last chunk is written, so the client’sEventSourcereads 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. Itshttp.requestline carries the head’sstatus, thebyteswritten, andoutcome="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, thebyteswritten before the cut andoutcome="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 linecancelled. 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.operationline withoutcome="cancelled", and onewarnnames how many were stopped. Asubscriptions/listenis 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_LINGERof zero, a process that crashed — drops the request where its handler waits, exactly as the window does, and it filesoutcome="cancelled"with nostatus. - An ordinary close —
close()after a timeout, a browser navigating away,curlgiving 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 thatstatusandbytes.
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.
Going further
Section titled “Going further”- HTTP configuration — every
HttpConfigfield, 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.