Home / Docs / Specification / 31. HTTP servers
31.6 Connections and serve threads
The host code in crates/una-http/src/serve is the same in both engines and runs on serve threads: threads that never run program code and whose work is bounded and linear in the bytes and events they handle (ADR 0123 rules 12 to 14 and 17 to 20; docs/plan/0123-s4-design.md). A run of a program that serves starts them before main (rule 14), under una run and in the executable of una build alike (§1 rule 10); any other run with a serve: grant holds its listeners and accepts nothing.
-
Serve threads.
una runand executables take--serve-threads <n>, from 1 to 256, by default the number of the machine's cores (spec/27 §3). A value that is not a number, or is out of range, is a usage error, exit code 2, beforemainstarts. A run that serves nothing accepts the flag and uses none. Each serve thread owns its connections, its timers and an inbox, and has a readiness queue of its own (kqueueorepoll) and a pair of sockets that wake it. Only plain owned data crosses between threads: a connection, the bytes of a request, a serialized reply. -
Accepting.
- Accepting begins at the run's first server operation. Before it, no listener is registered, and a peer's connection waits in the kernel's backlog.
- Each grant keeps the one listening socket that §2 rule 7 binds, without
SO_REUSEPORT. Every listener is registered, one-shot, in one accept poller, which is itself registered, one-shot, in the readiness queue of one serve thread at a time, the one that holds the turn (thread 0 first). That thread accepts at most 16 connections of each listener that fired, registers the listener again, and passes the turn to the next serve thread by a message. So exactly one thread accepts from a listener at a time, a listener event wakes one thread whatever their number, and a burst of connections is spread over the threads in turn. - A slot of
connectionsis taken beforeacceptis called, so every descriptor the host accepts, one closed at once included, holds one. Atconnectionsthe host does not register the listener again until a connection of the grant closes, and the kernel's backlog holds the rest.ECONNABORTEDandEINTRare skipped; any other error ofacceptstops accepting on that listener for 100 ms. - A connection is then checked in this order:
peer, and for anhttpsgrant the peer's and then the grant's handshake rates (rule 10). A connection over any of them is closed at once, before any byte is read. Else it is placed on the serve thread named by SipHash-2-4 of the listener, the peer's address and the peer's port, under a key of 128 bits drawn from the operating system's random source for the run and shown nowhere; the place does not depend on the order of accepts, on which thread accepted, or on how busy any thread is. - A peer is an IPv4 address, or the /64 prefix of an IPv6 address; an IPv4-mapped IPv6 address is its IPv4 address. The host keeps the peers with open connections, or with a handshake bucket that is not full, in a table of 64 shards: at most
connections + handshakesentries.
-
A connection is in one of four states, with at most one timer at a time (§2 rule 2:
idle,read,writeandanswer; every timer is a total and trickling bytes never extends it):- Reading. The first request of a connection is read within
readof the accept. A later request waitsidlefor its first byte, thenreadfor the rest. A request not read in full withinreadis answered408and the connection drains and closes (rule 8); a connection that sent no byte of it is closed without an answer. A connection idle pastidleis closed. - Waiting. From the end of the request until the reply is handed over, within
answer: afteransweran undelivered request, or a delivered exchange that was not answered, is answered503withRetry-After: 1, and a reply that comes later is discarded. The host reads no more than the head reserve while it waits, so a peer that leaves is seen at once, and its exchange ends with its reply discarded. - Writing. The reply is written within
write, and the host reads nothing more from the connection meanwhile. Then the connection reads its next request, or closes when the request saidConnection: close, when it wasHTTP/1.0, when the connection reachedrequests, or when a host stop is under way. - Draining after a refusal (rule 8).
- Reading. The first request of a connection is read within
-
Bytes of requests, in shares. The head of a request,
lineandheaderbytes, is counted inconnectionsat the accept and waits for no shared budget. A body is admitted before its first byte is read: a declaredContent-Lengthreserves its whole length, a chunked body reserves 64 KiB before each step, in the grant'sbuffersand the peer'speer_buffers; a reservation that fits neither is answered503withRetry-After: 1at once, and nothing else waits.100 Continueis sent only after the admission. The reservation is released when the request is delivered or refused. -
Delivery. A request read in full takes a place among the
waitingrequests (503withRetry-After: 1when none is free), and is delivered when the next exchange fits the grant'sdeliveredbytes, its/onceslots and its rate, in this order, each undone if a later one fails. Requests are delivered first come, first served among those one serve thread read for one grant; across threads the queues are visited from a rotating cursor, so no queue waits behind another indefinitely. The wait is bounded byanswer. A request whose bytes as read, its head, its body and their framing, exceed the grant's wholedeliveredcould never be delivered, and would hold its queue's front untilanswer: it is answered503withRetry-After: 1, the answer of ADR 0123 rule 14 for no room indelivered, at once and before it takes a place among thewaitingrequests; a declaredContent-Lengthis checked when the head is read, before any byte of the body, and a chunked body when the request is read in full (#1675). The rate is a token bucket kept as one timestamp per grant, updated by compare-and-swap, with the interval rounded up to a whole nanosecond and never to zero; it holdsNtokens. -
Replies, in shares. A reply is checked and serialized once (§5), reserved on the grant's
repliesand the peer's share, cut into segments of at most 16 KiB, and handed to the connection's owner; handing it over never waits on a peer and never fails for the reservation. Each segment is dropped, and its bytes given back, as soon as its last byte is written. When a reservation leaves the grant overreplies, the same call, before it allocates, closes connections until the grant is back under: the one with the most bytes left of the peer furthest over itspeer_repliesshare; when no peer is over its share, the one with the most bytes left of all; ties to the connection accepted first. A closed connection's reply is dropped at once and is never written, which the program never sees. A single reply larger thanrepliesis kept only while the grant has no other reply pending, else its connection is closed at once. The pending bytes of a grant are at mostrepliesplus the replies being reserved at that moment. -
The host's own answers. Each has an empty body and
Content-Length: 0;Retry-After: 1is written where shown;Connection: closealways.Status When Retry-After400,413,414,415,417,431,501,505a refusal of §3 and §4 no 421Hostis not allowed (§2 rule 5)no 408a request is not read in full within readno 503waitingis full; a body does not fit its shares; a request waits pastanswer, or can never fitdelivered(rule 5); an exchange is not answered withinanswer; a host stop finds a request undelivered or being read; the hard stop; the task holding the reply right is canceledyes 500the reply right is dropped without a reply no -
Closing after a refusal. After an answer that closes the connection, the host shuts down its sending side, reads and drops what the peer still sends, at most 64 KiB or for one second, and then closes, so that the peer reads the status instead of a reset. The connection keeps its slot and its place among the peers until it closes.
-
Stopping. At a host stop the host closes every listener at once and closes idle connections; requests undelivered or still being read are answered
503; delivered exchanges drain, each reply carryingConnection: close; a reply serialized just before the stop may lack the header, and its connection closes after it all the same. At the hard stop, each open exchange is answered503in one non-blocking write, and every connection closes, without waiting on a peer. A reply to an exchange that the hard stop,answeror a departed peer ended returns as if it had been sent. -
Handshakes. For an
httpsgrant,handshakesper second per grant andmax(4, handshakes / 16)per second per peer are token buckets, each full at the start and holding one second of tokens, charged at the accept; at most half of the serve threads, rounded up, are inside a handshake step at a time. Until the TLS server lands (§2 rule 8), a run with anhttpsgrant does not start serving: the host fails closed instead of serving plain bytes on anhttpsaddress. -
Descriptors. The run's limit of open descriptors is raised before
mainto the sum ofconnectionsover the grants, plus one listener per grant, one for the accept poller, three for each serve thread (its readiness queue and its pair of wake sockets), 256 sockets for the program's ownHttprequests, the helpers ofFiles, and 64 forConsole, the reactor and the runtime; a run that cannot is a usage error that names the sum. The cap on the sockets of the program'sHttprequests is then the soft limit less everything but those 256. -
Costs. Accepting, queueing and delivering a request, reserving and releasing a share, taking a token, arming and canceling a timer, and closing are O(1) expected; reading b bytes is O(b); a reply of r bytes costs O(r) to check and serialize and O(log c) per connection closed for pressure over c connections with a reply pending; a host stop is O(connections + queued requests).
-
Faults. A panic of the host is contained to the connection it happens on, and the run stops instead in three cases (ADR 0123, amendment of 2026-11-02, decision 10).
- Contained. A panic in a connection's step outside the serve thread's timers and readiness registrations, in the hand-off of an accepted connection (from the slot taken before
acceptto the connection's place in its owner's table), in a peer's expiry, in the closing of a connection, or inside a socket's write of a pending reply (which runs with the reply's lock held but changes nothing it protects, so the panic is carried out of the lock first), is caught where it happens and counted: it closes that connection at most, and no serve thread ends by it. What the connection holds is given back in every window: a fault in the peer's admission after its place was taken gives the place back, a fault in the hand-off before the connection reaches its owner's inbox, or before the owner put it in its table, gives back the slot and the place, and a fault inside the closing passes the step that faulted and still gives back everything after it, itsconnectionsslot and its peer's place included, each once: every step of the closing is marked done before it runs, so it runs at most once, and a closing resumes at most 8 times, more than its steps. A contained fault does not reach the process's panic hook, so faults cannot flood standard error. - Stopping the run. The run stops when a callback the program's side registered (
on_ready,on_slot_freed) panics; when a panic happens while a lock of a grant's shared state is held (a delivery queue, an exchange's request, a connection's pending reply, the pressure heaps, a registry shard, a shard of the peer table), after which that state may be inconsistent and is never served from again, even when the panic was contained where it happened (the socket's write of item 1 is not such a panic, since it changes nothing the lock protects); and when the run's contained faults pass 64, the same for every run and not a setting (the 65th stops it). A panic that began before the lock was taken, such as an exchange dropped while its task unwinds, does not count. These panics print through the panic hook. A callback that panicked is not called again once its panic is seen; calls already under way on other serve threads finish, so it runs at most once more per serve thread. - The stop. A stop is the hard stop (rule 9), made once, at the first point that holds no lock of a grant: each open exchange is answered
503in one non-blocking write, every connection closes, and every listener closes at the next pass of a serve thread's loop. A failure recorded on the program's side (in a delivery or a reply) wakes every serve thread as the program's side unwinds, so the stop does not wait for their next event. From the failure on, nothing is accepted, a reply that checks for it returns as if it had been sent and is never written, and the program's next request reports the failure instead of a request; a reply that passed the check just before the failure was recorded may still be queued, and the hard stop closes its connection. Its error names the cause:the serve engine stopped the run: a serve callback panicked,... a panic left the shared state of a grant inconsistent, or... more than 64 faults were contained. When the engines meet a program (step 5) the run aborts with that message as U8001, an internal error of the host, with exit code 3 (spec/11 §4), and the statusaborted. - A thread that ends. A panic inside the thread's timers or readiness registrations, which every connection of the thread shares, including one in the closing after a contained fault, or anywhere else in the thread's loop, ends the thread, and prints. A serve thread that ends closes every connection it owned and gives back what they held (rules 2, 4, 5 and 6; a panic inside the giving back of one connection is contained, and the others still close), hands on the turn to accept and the peers' expiries it was timing, and registers again every listener whose event its last wait for connections returned and whose burst did not end; a message for it is handled by its sender; a new connection whose keyed owner ended is placed on the next serve thread in the ring that has not ended. When the panic that ended it held a lock of a grant's shared state, the run stops as in item 2.
- What the program sees. Contained faults are counted per grant and for the run. ADR 0123's amendment of 2026-11-06 (slice S5), section I, declares what the program will see:
op faults() -> internal Int, a fourth operation ofHttpServerthat reads the run's count,accepts internal, with no failure, never parking, refused in a branch oftogetherby U3033 and allowed by aserve:grant with the others; and, for each contained fault, a host event with no task and no operation,{"seq": n, "outcome": {"kind": "fault", "site": "step" | "accept" | "peer-expiry" | "abandon", "listener": "<grant>"}}, written at the program's next server operation after it, before that operation's own event. Pending: both land with a later part of #1571, in both engines; until thenstd.hostdoes not declarefaults, and contained faults are counted and not shown to the program.
- Contained. A panic in a connection's step outside the serve thread's timers and readiness registrations, in the hand-off of an accepted connection (from the slot taken before
-
Starting and ending (S4 amendment B.2, ADR 0123 rule 18). A run whose program serves, one whose entry functions use
HttpServer(§1 rule 10) and that holds aserve:grant, starts every serve thread, its poller and its wake pair, and the accept poller, beforemain, over the listeners of §2 rule 7, and draws the key of its reduced trace form (§1 rule 7) from the host's random source; the panic hook of rule 13, chained over the runtime's own, is installed on the thread that starts the run before any of them. A run that serves nothing starts none of them. Once they have started, and before the run's first request, the run writes on stderr one line for eachserve:grant, in the order of its grants, the same in both engines:serving on <address>:<port> (granted by the package)for a grant ofrun grants, and(granted by a `--grant` flag)for one of a flag; an IPv6 address is written in brackets. A run that holds aserve:grant and serves nothing binds its listeners beforemain(§2 rule 7), accepts nothing on them and writes no such line. Nothing is accepted until the run's first server operation. Only a run that can take a host stop, one with aservesection, a driver, or amainthat saysdiverges(ADR 0116 rule 18), installs the handlers of SIGINT and SIGTERM; a server of the language form whosemaindoes not saydivergeskeeps their default actions, so SIGTERM ends its process at once, with no drain, and a shell reports exit code 143. The run's watcher of host stops (ADR 0116 rule 14) hands each request to the engine: the host stop of rule 9 when the first request reaches the run, and the hard stop when it comes. At the run's end the engine stops as at a host stop, and the run waits for the serve threads to write what it answered and close, for at most the grace period (--stop-grace, ADR 0116 rule 16); past it, and at once after the hard stop or an internal error, the engine makes the hard stop and the run waits for its threads at most one more second. Anextwaits for the engine on a condition that each queued request, each ended exchange, each closed connection and each delivery signals to one waitingnext, and each stop to all of them, and looks at its own cancellation, an abort of the run and a host stop at least every 10 ms. A signal wakes only anextwhose last attempt came before it, and anextthat a signal woke and that ends without a further attempt, at a cancellation, hands the signal on, so a request costs O(1) wakes whatever the number of waitingnexts. The signal of a delivery wakes one morenextbecause one ended exchange can let several queued requests through, when the bytes it gives back to thedeliveredbudget fit more than one of them. Every serve thread is in place, its wake pair in its readiness queue, before the run's first job; a run in which one cannot register it, or the accept poller, is a usage error beforemain. A run under--virtual-timethat holds aserve:grant is a usage error beforemain, in both engines (ADR 0123, S4 amendment C), since live peers send in real time; only the scripted engine of the toolchain's tests stands for the--serve-scriptof step 7 there.
Block for the capability. The serve threads decide observable timing: 408 against a silent close, idle against read, the order of delivery, and the placement of connections. The checker computes the L_srv labels of the S4 design (docs/plan/0123-s4-design.md §10) with the preview's terms (§1 rule 5 item 7); una run lets any program meet the engines (§1 rule 10), and the five timing oracles below MUST pass on the engines a release ships. The five oracles of the S4 design §11.5 exist (crates/una-cli/tests/timing_channels.rs): serve_prefix_secret and serve_prefix_early_peers, which time the reply to a probe instead of a deadline's outcome, since the preview's L_srv, ⊤ for a server of the language form, refuses a reply that carries one; and the positive controls serve_handoff_residue (SC2: reply bytes pending to a peer that does not read decide, through replies and connections, whether a later next under a deadline receives its request) and serve_delivery_history (SC3: the time between two deliveries under a rate decides the same), servers without tasks whose public twins MUST show the channel, and whose secret versions, the conformance cases serve_handoff_residue_secret and serve_delivery_history_secret, are refused with U4003; and serve_owner_spread (SC1, M1: the placement of connections), which observes the owner of each of 8 connections of one address over 8 serve threads directly: timing could not show the owner on the gate machine (one serve thread and 8 replied alike, ratios 0.4 to 1.17 over 9 workloads, in both engines), so the toolchain's test builds have a placement probe, under the test-hooks feature that no shipped una or libuna_rt.a has, which writes the serve thread that placement chose for each accepted connection, before the peer's admission, and can place by port mod M with no key. The harness picks connections whose source ports are all multiples of 8, the family that port mod 8 without a key puts on one serve thread. Under the keyed placement, for each of the program's two keys (which make public set-up code before the first server operation 0 or about 300 ms long), a run MUST NOT put all 8 on one owner, and over the 160 connections of 20 runs every serve thread MUST own between 3 and 44, bounds fixed in advance from Binomial(160, 1/8); the positive control, the same connections under the unkeyed port-mod-8 placement (port mod 8 with no key), MUST put all 8 on one owner in every run. This shows that the keyed placement spreads connections that the unkeyed port-mod-8 placement concentrates, and that the probe and the crafted ports do separate those two. Other placements without a fresh key spread multiples of 8 and pass it, such as (port >> 3) mod 8, an unkeyed SipHash, round-robin by accept order, the thread that accepted, or the keyed hash under a fixed key: the ports differ from run to run and cannot be replayed, so a fixed key is not covered (the oracle logs, as a diagnostic, how often a port that recurs across runs keeps its owner). It does not show that a peer cannot predict an owner, which rests on the key's secrecy and on SipHash-2-4 as a pseudorandom function (assumed); it observes the test build, whose placement calls the same function as a shipped build's; and it does not measure the time of a reply on its owner. Its timings, crafted ports against ports as they come and one serve thread against 8, are logged as diagnostics and not asserted. Its client uses the standard library only, which cannot bind a source port before it connects: the ports are found among the ephemeral ones and the others closed before the first server operation, so the property of the ports is fixed and the ports themselves are not. Each of the five runs in both engines, as <oracle>_native over the executable that una build makes (for serve_owner_spread, linked with the runtime built with its test-hooks) and <oracle>_interpreter under una run, since the waiting and waking of the serve engine is separate code in each: the same harness, assertions and sample sizes, with the iterations of public set-up and probe work scaled per engine so that their times are alike. All five passed in both engines on 2026-11-08, on the commit this lift of §1 rule 10 builds on, and a release runs them again on its candidate (docs/release-gates.md).