Home / Docs / Specification / 31. HTTP servers
31.8 Tests
The functions of std.testing for servers, ADR 0123 rule 21 (spec/14 §4). They exist only in edition 0.4 and later, and, as every function of std.testing, only tests and the handlers that only tests install call them (U3015).
-
test_request(method: Method, target: Text, body: Text) -> Request fails TestRequestErrorgives the request the host would read from a peer that sent the request line ofmethodandtargetwithHTTP/1.1, the one headerHost: test, andbodyframed by its length. The host's own reader reads it (§3, §4), with no limit but the request's own size, so only the target's form can refuse it:- the target is read by §4: origin-form, or the absolute-form on the authority
testwith the schemehttp, rewritten to origin-form;segmentsandparamsare decoded as the host decodes them; headersis[Header(name: "host", value: "test")], sinceContent-Lengthbelongs to the connection (§3);bodyisbody;peeris"192.0.2.1", an address of the block that RFC 5737 sets aside for documentation;listeneris"test";- where the host would answer
400, it fails withRefused: a target that is empty or holds a byte outside printable ASCII (which would end or split the request line, §3 rule 1), the asterisk-form, the authority-form, an absolute-form on another authority or scheme, a#, a bad percent-encoding, and a segment or a parameter that §4 refuses.
- the target is read by §4: origin-form, or the absolute-form on the authority
-
pub kind TestRequestError = | Refusedis declared bystd.testing, a sum of one variant, whichfailsrequires (spec/06). ADR 0123 rule 21 writes it= Refused, which the grammar reads as an alias of a typeRefused(spec/02 §2); ADR 0123's amendment of 2026-11-06 onTestRequestErrorcorrects it. -
test_exchange(request: Request) -> Exchangegives an exchange ofrequestwith a fresh reply right: distinct from every reply right the run gave before, fromnextor fromtest_exchange, and equal only to itself. A handler ofHttpServerthat a test installs receives it inreplyas any value; the host's table never holds it (§1 rule 3), so it names no exchange of a peer. -
What a package uses. An import of
test_request,test_exchangeorTestRequestErrormakes the package one that uses the server's kinds, as an import of a name of §1 does, so Core IR declares them, and only then does Core IR declareTestRequestError,test_requestandtest_exchange; an import oftest_exchangemakes it one whose values can hold a reply right (§1 rule 5 item 6). Core IR of a package that imports none of them does not change, a server's that imports only names of §1 included. -
Engines and costs. Tests run in the interpreter (spec/08 §2), and native code never reaches
std.testing(U3015).test_requestis O(t + b) for a target of t bytes and a body of b bytes, one pass of the host's reader;test_exchangeis O(1). -
Scripts of connections (ADR 0123 rule 21). A script stands for the peers of a run's
serve:grants under virtual time, one JSON object per line,atin virtual milliseconds, each line exactly one of these forms (una_http::serve::script_file):{"at": <ms>, "connection": <k>, "grant": "<address>", "peer": "<ip>", "reads": "eager" | "paced"}opens connectionkon the grant whose address, aslistenerwrites it (§1), is<address>, from the IP address<ip>;{"at": <ms>, "connection": <k>, "bytes": "<base64>"}sends bytes, in the padded standard base64 of RFC 4648 §4;{"at": <ms>, "connection": <k>, "read": <n>},nat least 1, lets apacedconnection receivenmore bytes;{"at": <ms>, "connection": <k>, "close": true}closes the peer's side, and no line follows it on that connection.
Lines end with LF, the last one optionally, and each is one JSON object with nothing before its
{or after its}: an empty line, a line of spaces or tabs, a CR anywhere (so a CRLF line end), a key that is not one of the forms', and a key given twice are refused. A script with no lines opens no connection.atnever decreases from a line to the next, and lines of equalattake effect in their order. A connection is opened once, before its other lines, and one peer address opens at most 64,512 connections: the engine gives the connections of a peer address the ports 1024 to 65535 in the order the script opens them, so the connection numbers, any whole numbers, never make a port. A script is read and checked in full before anything runs; the first line that is not one of the forms or breaks a rule above is refused, named by its number, counted from 1. Reading is O(n) in the bytes of the script.una runand executables take--serve-script <file>and--serve-out <file>. These are usage errors, exit code 2, with the same message in both engines, in this order: before the package is read and before the ranges of--workers,--task-depth, the thread counts and--max-depthare checked,--serve-scriptwithout--virtual-time, and--serve-outwithout--serve-script(a flag value that is not a number or is out of its own range, such as--deadline 0, is refused while the flags are read, before these); then, after the checks of the program, rule 10 of §1 among them, and after the key files, a run with noserve:grant, a script that is not a regular file (opened without blocking and checked on its descriptor, so a FIFO or a device is never read), one larger than 64 MiB, one that cannot be read or is not UTF-8, and a script refused above. A script read and checked is then, while the scripted engine does not run outside the toolchain's own tests, the usage error "the scripted connections of--serve-scriptdo not run in this release yet". A run that ends with any of these binds no listener and makes no file: the trace file of--traceis made only after them, in both engines, and--serve-outis not opened. Only the toolchain's own test builds ofunaand of the runtime, in a run whose environment setsUNA_TEST_RUN_SERVER=1, serve the script: the engine of §6 takes the script's connections in place of listeners, binds none, and advances the script while the program waits innext, one instant at a time, every line of that instant in order. The engine's clock moves only to the script's next line or the engine's next timer. The serve threads finish their work at each instant, so a pipelined request is read, and a refused one answered, at the instant the reply before it is written; a request they queue while the program waits is delivered to it at that instant, before the clock moves or the script ends (issue #1738). Both engines do the same. At the run's end, after the lines the program did not wait for and one more hour of the engine's clock,--serve-outgets what each connection received:- one compact JSON object per LF-ended line, its keys in lexicographic order:
{"at", "bytes", "connection"}with the bytes that left at that millisecond in padded base64,{"at", "connection", "shutdown": true}when the host shut its sending side,{"at", "closed": true, "connection"}when it closed the connection, and{"at", "connection", "refused": <reason>}for a connection refused at accept, which also has itsclosedline at the same time; - sorted by time, then connection, then kind in the order
bytes,shutdown,closed,refused; - a reason is one of
full(the grant'sconnections),peerlimit(the peer'speer),handshakes,peerhandshakes,nothread,faultandfailed.
What it holds. The file holds exactly the bytes the script's peers received: what the host wrote, statuses and its own headers, and what the program put in its replies, unredacted. Unlike the trace (§1 rule 7), it keeps
internaldata, a value a policy released into a reply, and credentials such asset-cookie, since those are what a peer of the server reads; it gives no reader more than the program's peers had, and only those who may read what the server sends should read it. It is written once, after the run: opened without following a symbolic link in its last component and without blocking, so a link or a FIFO with no reader is refused; a file that is not a regular file, or that has more than one name (a hard link), is refused; its mode is set to0600, an existing file's included, before it is truncated and written, so a reader that opened an existing file before the run keeps what its descriptor allows. After the run's own diagnostics, both engines then write, in this order, what the engine leaves not at rest (counters, peers, timers, connections accepted before any server operation) aswarning:lines on stderr, which do not change the exit code, and, for a file that cannot be written or is refused, the line "error: cannot write the connections to<path>:<reason>", a usage error: the exit code is then the higher of the run's own and 2. A--tracethat cannot be written is reported last, after the run's own diagnostics and these, as "error: cannot write the trace to<path>:<reason>" in both engines, also a usage error: the exit code is the higher of the run's and 2. Both engines write the same file, byte for byte. Without--serve-script,--virtual-timestill takes noserve:grant (§6 rule 14).The security hunt (ADR 0123 implementation plan, step 10, #1011). The hunt's family N (
docs/plan/security-hunt-generators.md,hunt serversinscripts/security-hunt) runs servers through scripts of connections with a test build ofuna, so it binds no listener. Its programs send the refusals of §3 and §4 and their well-formed twins, each followed by a request a smuggling peer would want read, whole and split at random byte boundaries; a peer must receive the host's own answer alone, with the status of the rule, and the request behind it must never be read. Its handlers also echo a request's decoded query value into a header of their reply, a CR, an LF or a NUL included, and write names the host refuses: such a reply must fail withBadReplyand send nothing (§5 rule 1), so nothing it carries reaches the peer. A run of the two-run oracle over handlers that readsecretdata compares what the peers receive, theinternalobserver of IF2, across values of the secret: it must not change, but for what a policy releases. This is a check of the rules above, not a rule of its own.