Limits & timeouts
Every cap in this page is flag-overridable, but the defaults are chosen deliberately — each one guards against a specific failure mode, not a round number picked for its own sake.
HTTP server timeouts#
504. Guards against a hung local app. Post-header response duration is unlimited by design — streaming downloads and SSE need that, and a client disconnect cancels the request context anyway.502 if the session is wedged.408; one that stops reading its response is disconnected. Either way its request slots are freed. The deadline applies only while a read or write is blocked, so long uploads, SSE streams and WebSockets that keep moving are unaffected.ServerAliveInterval, for sessions that sit idle longer.Body limits#
Content-Length before the request is proxied at all — this is the real 413, and it covers every well-behaved client.MaxBytesReader for chunked or unknown-length bodies, surfaced as 413 from a custom ErrorHandler that type-checks *http.MaxBytesError.-max-body-bytes). Larger bodies get 413.503 with Retry-After and counts ngstoned_rejected_webhook_buffer_total. Must be at least -webhook-max-body-bytes.A chunked 413 may ship a partial body
MaxBytesReader alone — returns 502, not 413, because the trip surfaces as a request-body read error inside RoundTrip after headers and up to 256 MiB have already reached the agent. With both checks in place the chunked path still means the agent may have already forwarded a partial body to the local app before the edge cuts it off.Rate limiting#
429.:4443.Concurrency & the window budget#
429.429, or closes the TCP connection.AcceptBacklog is not the concurrency cap
AcceptBacklog is the depth of yamux's accept queue; when it's full, a new stream gets RST'd — a 502the client can't interpret, instead of the 429 the system intends. Concurrency is enforced by the per-session (48) and global (64) semaphores instead, with AcceptBacklog set comfortably above both (512) so it never becomes the binding constraint. The yamux receive window is itself a buffer — each open stream may hold up to its window of received-but-unread bytes on both machines, so concurrency × window is the number that matters, not either alone.The upgrade budget#
A WebSocket upgrade or an SSE stream would otherwise hold one of the semaphores above for its entire life, starving ordinary HTTP requests behind it. The edge detects a long-lived response — 101 Switching Protocols, or a 200 whose Content-Type is text/event-stream — and moves it onto this separate budget, releasing its global and per-session in-flight slot back to the pool. See WebSockets & SSE for the full picture.
A connection that can't be reclassified because either cap is exhausted is rejected outright with 503 Service Unavailable — it is not silently downgraded or left occupying a request slot — and ngstoned_rejected_upgrade_cap_total increments. ngstoned_active_upgrades is a live gauge of currently open upgraded connections.
Control-plane caps#
-unauth-per-addr; the default is a quarter of -handshake-concurrency, and never below 1. Counted per IPv4 address or per IPv6 /48 and shared by TCP, QUIC, WebSocket and forwarded control, where the address is the original client's. Stops one address from filling the handshake cap, though four addresses (or /48s) can still fill it. A refused client is turned away without any control reply: a TCP connection is closed, a QUIC connection is refused with CONNECTION_REFUSED, and a WebSocket upgrade gets 503 too many connections. Refusals are counted in ngstoned_rejected_unauth_per_addr_total. Many agents behind one NAT or one IPv6 /48 that start together can hit it.-quic. A QUIC handshake that stalls is dropped. The edge sends a QUIC Retry before it admits a connection, so the agent's first handshake reply arrives two round trips after it starts. The agent waits up to 10 s for it, and the whole handshake and authentication must fit in the 5 s pre-authentication budget after admission. A link with a round trip above about 4.5 s cannot connect over QUIC and should use TCP. Agents older than this release wait 5 s and are limited to about 2.5 s.-quic. The agent's whole QUIC dial budget. With UDP blocked, a literal address fails after 10 s. A name with both an IPv4 and an IPv6 address tries IPv4 first and then IPv6, so it fails after up to 20 s. With more than two records the 20 s may run out after the first two.-quic. A peer that vanishes without a clean close is noticed within about this long.-quic. Keeps an idle connection open and lets a vanished peer be detected.