Home / Docs / Specification / 31. HTTP servers
31.1 The capability
The declarations of ADR 0123 rules 0 to 5 and the static rules of its Information flow, with the label L_srv of its S4 amendment (IF-S1), are in this section. The operations of HttpServer run in both engines: una run reaches them, and so does the executable of una build (rule 10).
-
Edition and names. Every name of this section exists only in packages of edition
0.4and later.std.hostdeclares them, and the prelude does not put them in scope: a module imports them, asimport std.host (HttpServer, Request, Reply)(spec/10 §11 rule 10). An import of one is never redundant, an import ofMethodorServeErrorbrings its variants, and a kind of the package namedRequestorReplystays legal. In earlier editions an import of these names is U1001, as an unknown name is. This section adds no keyword. -
Declarations.
std.hostdeclares, in edition0.4:una--- The methods a request may have. The host answers any other with 501. pub kind Method = Get | Head | Post | Put | Patch | Delete | Options --- One decoded query parameter, as `name=value`. pub kind Param name: internal Text value: internal Text --- A request, as the host read it (§3 and §4). pub kind Request method: internal Method target: internal Text -- the request target as received, in origin-form segments: internal List[Text] -- the path, split on "/" and percent-decoded segment by segment params: internal List[Param] -- the query, decoded, in order headers: internal List[Header] -- names in ASCII lower case, in the order received body: internal Text peer: internal Text -- the peer's IP address, without its port listener: internal Text -- the grant's address, as the grant writes it --- A request and the reply right to answer it. pub kind Exchange request: internal Request right: internal ReplyRight pub kind Status = Int where 200 <= it and it <= 599 pub kind Reply status: internal Status headers: internal List[Header] body: internal Text pub kind ServeError = Interrupted | TimedOut | Closed | NotHeld | BadReply pub capability HttpServer op next() -> internal Exchange fails ServeError accepts internal op reply(to: ReplyRight, reply: Reply) -> Unit fails ServeError accepts internal op close() -> Unit accepts publicparams. ADR 0123 rule 1 names the field of the decoded queryquery, a word that spec/01 reserves in every edition, so a field of that name could never be read. The field isparams, as ADR 0123's amendment of 2026-11-06 (slice S5), section A, states.Headeris the kind of spec/24 §1, whosevalueisinternal Text.- Labeled fields. The fields are
internal, so a program can build aReplyfrom request data, and a test or a handler can build aRequestfrominternaldata. A constructor field is a flow site (spec/07 §7 rule 2), so asecretvalue in a field of aReplyis U4001 where the reply is made. Statusis a refinement ofInt: everyReply(status: s, ...)carries the obligation200 <= s and s <= 599(spec/12 §3), refuted U5001 and unknown U5002.ReplyRightis an opaque built-in type ofstd.host: it has no constructor, no literal, no fields and no order. Its values come only fromnextand, in tests, fromstd.testing.test_exchange(§8). Two reply rights are equal when they name the same exchange, so==and!=apply to it. Interpolation writes<reply-right>.- Failures.
nextfails withInterruptedat a host stop (spec/26),TimedOutwhen a deadline of the program cuts its wait (spec/27 §5), andClosedafterclose.replyfails withNotHeldandBadReply(rules 4 and 13 of ADR 0123, §5 rule 1).closecannot fail, so a handling clause on it is U3025. - What each accepts.
replyacceptsinternal(IF2).closeacceptspubliconly, so a server cannot close itself on the strength of a request's content: under a raised program counter it is U4003 (IF1).nextacceptsinternal: ADR 0123 writes noacceptson it, and whether a task takes a request off the queue, and with it a/onceslot that other tasks' deliveries wait for, could otherwise depend onsecretdata; under asecretprogram counter it is U4003. - What parks.
nextparks its task while no request is ready, and is an interruptible operation (spec/26, spec/27).replyandclosenever wait. - One instance. A run has one host instance of
HttpServer,host:HttpServer, which serves everyservegrant (§2). - Grants and examples. A
usesof anHttpServeroperation that noservegrant allows is U3012 (spec/05 §7 rule 2); a grant allows all three operations, and the repair is a description only, since no address can be chosen for the programmer. A test whosedoline needsHttpServerwithout agivenhandler is U3014 (spec/05 §9 rule 5). A test MAY install a handler ofHttpServerwithgiven, as for every capability; its operations are ordinary handler code.
-
Reply rights (ADR 0123 rule 4). Every exchange comes with a reply right, held by exactly one task at a time:
nextgives the reply right of its exchange to the task that called it.start emoves to the started task every reply right that the calling task holds and that is reachable from the valuesecaptures, closures included.- No other construct moves a reply right: a branch of
together, the body of atogether forand a branch offirst ofact for the task that runs the construct (rule 4). replysucceeds only for a reply right that the calling task holds and has not answered; otherwise it fails withNotHeld, and nothing is sent. A successfulreplyreleases it.- When a task ends holding reply rights, the host answers each one, in the order the task received them:
500when the task returned, failed or ended alone,503withRetry-After: 1when it was canceled, cut bywithinor stopped; each appends the event{"seq": n, "task": "<path>", "outcome": {"kind": "unanswered", "status": s}}. - Which task holds a reply right depends only on the order of
next,startandreplyin each task, never on timing. - Each exchange ends by one atomic transition, the first of the program's
reply, the host'sanswerdeadline, an auto-answer, its peer leaving or a stop; areplyafter another transition returnsunitand sends nothing.
Items 1, 2 and 4 to 7 are the runtime's (rule 10). What the checker can see of them is checked now: item 3 through rule 4, and the auto-answers of item 5 through IF6 (rule 5 item 6). Both engines implement them over the engine of §6 (rule 10), with one table of reply rights (
una_http::serve::rights), and under--virtual-timethey give a run the same bytes, output and trace (ADR 0117 rule 12):- A reply right is one word that names an entry of the run's table,
(slot << 32) | generation; a slot's generation grows at each reuse and a slot whose generations are spent is retired, so no word names two exchanges of a run. Holding, moving and releasing one is O(1) amortized. - The walk of item 2 reads only the captures whose types can hold a reply right, which the checker marks for IF6 and Core IR names on the
start(rights): aReplyRight, a value that can hold one, and, in a package that importsHttpServer,ExchangeorReplyRight, ortest_exchangeofstd.testing(§8), a function value or a value of a type parameter. They are walked in the order of their names, each value depth first, left to right, the values a closure holds included, an allocation that several values share once, at its first meeting; so a right that a task holds and that a capture reaches moves, in that order, and one it does not hold stays where it is. The capabilities a started task inherits are not values it captures: a right held in the state of a handler that the task inherits, and that no captured closure holds, does not move, so areplythrough that handler in the started task fails withNotHeld, and the task that holds the right answers it at its end. Native code moves the rights that the values of the closurestartcopies reach, before the instances of its capabilities, in the order of their names and in the same order inside each; a capture that the checker does not mark holds no reply right, so both engines move the same rights in the same order. A handler instance's own instances are capabilities too, and neither engine walks them. - Item 5. A task that the run's end stops, by a host stop's hard stop or by an abort of the run, is stopped:
503. A task whose body never ran, or that ended by a fault of the interpreter, the root task included, answers503and appends no event. Quiet code appends nounansweredevent, as it appends no event of an operation (spec/26 §6 rule 4). Theunansweredevents of a task come before the event that ends it,cancelledoraborted. In native code, an abort of a run that serves does not end the process at once, as in the interpreter: an abort by a started task stops every task at its next check point, and an abort of the root unwinds the root through itstasksstatements, which cancel their tasks, each with itscancelledevent; the host answers the rights each task holds, its events are written, and the root then ends the run with the first abort. At the hard stop (U6007), in both engines, the run's watcher makes the engine's hard stop before any check point sees the hard stop: from then on the engine discards every answer and reply of the program that has not yet taken its exchange, and its serve threads answer each exchange still open503withRetry-After: 1in one non-blocking write and close every connection (§6 rule 9). A reply already in progress when the hard stop comes, one that checked the stop before it and takes its exchange after it, may be lost: neither it nor the503reaches the peer. The host then answers every right still held, which sends nothing, and appends nounansweredevent for any of them. Native code ends the process there, after waiting at most one second for the serve threads, without waiting for its tasks; the interpreter ends each task at its next check point. At an internal error (U8001) the engines differ. Native code makes the engine's hard stop first, as above, then ends the process, with nounansweredevent. The interpreter's tasks end as at an abort of the run: each answers the rights it holds503withRetry-After: 1itself, appending theirunansweredevents, and the engine's hard stop comes at the run's end; an internal error of the engine itself (§6 rule 13) refuses those answers and makes the hard stop at once. nextafter a host stop fails withInterruptedwherever it is called, before it takes any request, so a stopped run never delivers one (rule 2,Failures), unless the run has aborted (Waiting).- Waiting. A
nextwith no request to deliver lets another ready task run first, but not one that waits innextitself and can only wait on: when every ready task waits there, the task that runs waits for the engine, so a pool of tasks that callnextwaits instead of passing the turn among themselves. A waiting task that its cancellation or its deadline ended counts as one that can run, so it runs at once, and the wait for the engine lasts no longer than the earliest deadline of the tasks waiting innext. A task canceled while it waits innextends the operation with the outcomeinterrupted, takes no request, and the request stays queued for a laternext. An abort of the run by a started task ends anextin progress with the outcomeaborted, before it takes any request, and the task ends as the aborted run's tasks do. An abort of the root task ends no other task'snextat once: the root unwinds through itstasksstatements, which cancel their tasks, so a task waiting innextends the operationinterrupted, as a canceled one does, with itscancelledevent, and the root then ends the run with the abort (item 5).nextchecks an abort of the run first, thenClosed, then the host stop: acloseor a host stop that comes with the abort does not turn the run's end into a failure the task can handle, and the rights it holds are answered503(item 5).
-
No server operations in branches (U3033, ADR 0123 rule 5). The effect set (spec/05 §3 rule 3) of a branch of
together, of the body of atogether forand of a branch offirst ofMUST NOT contain an operation ofHttpServer. U3033 is reported at each of these, written in the branch, inside a lambda written there too:- an operation of
HttpServer, "@server.replycannot run in a branch oftogether; answer after the block"; - a call of a function, a call of a function value, a function named or passed as a value, and a handler installed with
with, whose requirements holdHttpServer; - an operation of a capability that has a handler in the package whose
usesholdHttpServer, or another such capability, whatever handler serves it, since a handler's parameters may hold a reply right; - in a program that imports a name of the server, a call of a
uses ofparameter (spec/05 §9 rule 9), or its passing on, since the code its callers pass is not known in the branch and may reply: "fruns the code its callers pass, which in a program that serves can perform an operation ofHttpServer, and that cannot run in a branch oftogether; call it after the block".
The repair, a description only, moves the operation after the construct. Each check is O(1) per site, beside a search over the package's handlers computed once.
- an operation of
-
Information flow (ADR 0123 IF1 to IF7).
- Requests are input (IF1).
nextreturns aninternal Exchange. Whethernextsucceeds ispublic: no argument decides it, and its failures come from host stops, fromclose, which acceptspubliconly, and from deadlines, which spec/27 §5 labels. So an accept loop stays at apublicprogram counter, and it can print. - Replies accept
internal(IF2). Every argument ofreplyis a sink withaccepts internal: asecretvalue reaches a reply only through a policy (spec/07 §5). - Failures of
reply(IF3) are labeledinternalat least:NotHeldandBadReplyare decided by the reply right, the reply and the task's own reply rights, which the program's order decides.attemptgives aninternalResult, andif error passandif error failare U4002. - No host deadline becomes a value (IF4): the host's deadlines, a peer that leaves and full queues change only what the network carries (rule 3 item 7).
- The request stream is input from outside, and its dependence on the server's timing is out of model (IF5, spec/07 §1), as is which request a call of
nextreceives when several serve threads hold requests. - Auto-answers (IF6). A
start ewhose captures can hold aReplyRight, by their types, or, in a package that importsHttpServer,ExchangeorReplyRight, ortest_exchange(§8), include a function value, which may have captured one, moves reply rights, whose auto-answers depend on how its task ends. It is checked as areplyat thestart. A capture of a type parameter's type, or of a type not yet solved, counts as one that can hold a reply right only in a package that importsHttpServer,ExchangeorReplyRight, since the checker sees every module of the program, its dependencies included. The program counter of thestart, joined with the effect floor and the timing floor around it, and withτ(e)when it haswithin, MUST flow tointernal, else U4003 at the wordstart. The capture test is one look at the type of each localereads, O(1) per read with a table of the kinds that can hold a reply right, computed once.-
The depth of its task (#1674, ADR 0123, amendment of 2026-11-06 on the depth of a request task). A started task that runs past
--task-depthends alone, and the host answers its rights500where the program would have replied, so the status a peer reads can tell how deep the task went. Such astartis also U4003 when both hold:- its task can push frames without a bound its code shows: what it runs, along the call graph of ADR 0116 P1 with an edge from each policy to its
viafunction, reaches a cycle (a function, a handler, aviaor a lambda that can call itself again), a call of a function value or of auses ofparameter (the lambda nodeΛ, which a prelude function that applies a function argument, such asmap, reaches too), or code whose calls the checker does not hold: a function or handler of a standard module other than the prelude, or of a dependency not checked with the package; - it can hold data above
internal: its program counter, what it reads from outside, binds or receives from an operation, or what any node it reaches declares in its signature (parameters, result, a handler's parameters, an operation's result,acceptsand failure), binds, receives or, in a lambda, captures. A symbolic labelℓ_Tcounts as aboveinternalin what thestartitself reads, binds or receives, since astartin a generic body takes the values of its type parameters from callers outside the task; and in what the lambdas of the package hold, when the task can be handed a function value made outside it (a capture, or a handler parameter or operation answer that may hold one). It does not count in the signature and body of a generic function the task reaches, whose type parameters take what the task passes, counted where the task holds it.
Without item 2, the task's depth depends on
internaldata at most, which the answer accepts. Without item 1, its depth is bounded by the longest chain of calls its code shows, so it ends alone only when--task-depthis set below that chain; which chain runs is then decided at a branch, and in a program that starts tasks a branch that data aboveinternaldecide is refused (spec/27 §8 rule 5), so a lowered--task-depthmakes such a task end alone, or not, byinternaldata at most, which the answer accepts (#1681,security/server_start_static_depth_secret). This holds while spec/27 §8 rule 5 stands: an amendment of ADR 0117 that withdraws it MUST keep a rule for the depth of started tasks, or #1681 reopens (DECISIONS-OPEN item 18). Atinternal, whether such a task's later effects run, besides its answer, is the residual of #1677 (spec/27 §8 rule 5), which with a lowered--task-depthneeds no recursion, only a branch. A more precise rule is #1682. The prelude's functions are host code in both engines and push no frame of Una code but through a function argument. Precise form of item 2 (#1682, which ADR 0123's amendment of 2026-11-06 allows as a refinement that only accepts more). A frame is pushed only by a call, so the task's depth follows only what decides its calls. When every call the task can make lies in code whose decisions the checker records with their labels, item 2 is replaced by: a function it reaches, or the body that holds thestart, holds a check point that data aboveinternaldecide, with a concrete label (a call, an operation or a loop under such a program counter, spec/27 §8 rule 5, recorded whether or not that rule reports it), or a call of a generic function whose check points a type argument aboveinternaldecides. The coarse item 2 stays when the task reachesΛ(a call of a function value, or a prelude function that applies one), a handler's operation, aviafunction, whose body is checked without labels (spec/07 §5 rule 3), or code the checker does not see (a function of a standard module other than the prelude, asstd.collections's from edition 0.5,security/server_start_depth_unseen_secret; in edition 0.4 those arestd.testing's, for tests and handlers' operations only; or a module that failed to parse; path dependencies are checked with the package), or when thestartlies in a handler's operation body, whose holder no function names, or when thestart's own data carry a type parameter's label; a predicate and a body that evaluates acheckedpredicate count so too, conservatively, though areflectpredicate's body records its check points andcheckedon data abovepublicis refused (spec/07 §3). So a task that recurses on the request's length and also holds asecretkey that decides none of its calls is accepted (security/server_start_depth_holds_secret, live in both engines: its200or500follows the body's length, whatever the key), and one whose recursion the key decides is refused (security/server_start_depth_secret): "its task can recurse, throughsrv.deep, and data aboveinternaldecide some of its calls, which may decide how deep it goes; a started task that runs past--task-depthends alone and its rights are answered500". One that calls a policy whoseviarecurses keeps the coarse test (security/server_start_depth_via_recursion). The cost is two more closures over the strongly connected components, O(V + E), and one pass over the recorded check points, O((sites + calls) log n). A request task can readsecretdata, call prelude functions and reply with what a policy releases, when it neither recurses nor calls a function value; one that recurses can do so oninternaldata, and holdsecretdata that decides none of its calls. The default ofif error useruns under the label that decides the failure, as every branch does (spec/07 §3). - its task can push frames without a bound its code shows: what it runs, along the call graph of ADR 0116 P1 with an edge from each policy to its
-
Cost. One graph of the package, one search for its cycles and two closures over its strongly connected components, O(V + E), built at the first
startthat moves reply rights; then O(size of the seed ofe) lookups perstart. Recording what a node holds costs O(open sites + log n) per binding and per operation.tests/start_reach_scaling.rsofuna-checkkeeps 2000starts linear.
-
- The label
L_srv(ADR 0123, S4 amendment IF-S1). In a package whose code performs an operation ofHttpServer, the serve threads' work after each hand-off site, an operation ofHttpServeror astartof item 6, can shift every timing site of the program, soL_srv = internal ⊔ ⨆ over hand-off sites s of (sfx(s) ⊔ Suf*(node(s)) ⊔ τ_conc(s)) ⊔ L_resjoinsτof every timing site, asL_resdoes (spec/26 §7 rule 5): everywithin,first ofandfor ever within, every tick,L_limand the statement alimiterscopes over. It ispublicin a package without an operation ofHttpServer. A message whose label it raises names "the requests that the serve threads handle after the server operations inm.f".- Preview over-approximation.
sfx(s) ⊔ Suf*(node(s)), the code that can run afters, is taken asτ⁰of the bodies of every ancestor of the function that holdss, that function included, in the call graph of ADR 0116 P1, the rule ofL_lim(spec/27 §9 rule 5); andτ_concis the preview's,⊤for a site in a task, atasksblock, a lambda or a handler's operation (spec/27 §11, which names the sites that keep it). Both are sound and coarser than the amendment's, so code that runs only before the first server operation still raises the label here; they MAY become more precise, and MUST NOT become stricter. In a server of the language form, whosenextstands in the block of atasksstatement,L_srvis⊤under the preview, and so is every timing site of the package. - Cost. One pass over the call graph, linear in its nodes and edges, and linear in the hand-off sites.
- Preview over-approximation.
- In practice (IF7). A request task branches on
internaldata, so its program counter isinternal: it can callHttp,Files.write,limiterandreply, and cannot print. Under the preview'sτ_conc, astart ... withinin the block of atasksstatement whose expression performs an operation that acceptsinternalis refused already (spec/27 §5), so the language form below starts its tasks withoutwithin, and the host'sanswerdeadline bounds what each peer waits.
- Requests are input (IF1).
-
The language form (ADR 0123 rule 15). A server is a
divergesfunction with afor everloop that callsnextand starts a task per request:unaanswer(exchange: internal Exchange) -> Unit uses @server: HttpServer[reply] = @server.reply(to: exchange.right, reply: Reply(status: 200, headers: [], body: "ok")) if error use unit serve_all() -> Unit uses @server: HttpServer[next, reply, close] diverges = tasks at most 1000 at once for ever let next = attempt @server.next() when next is Ok(exchange) -> start answer(exchange) is Err(failure) -> unit on stop @server.close()nextwaits, parked, and fails withInterruptedat a host stop, which ends the loop at its next iteration start.tasks at most N at oncebounds the program's tasks, and the grant's/oncethe exchanges open. A server that answers in its loop, with notasks, is legal too. -
Trace events.
next,replyandcloseare events of spec/11 §5, withinstancehost:HttpServer. Their values are redacted by their labels, as every event's are, and, whatever their labels, they are written in the reduced form of ADR 0123 rule 1, in a recording kept for replay too: the values of the headersauthorization,proxy-authorization,cookie,set-cookie,x-api-keyandx-auth-tokenas<credential>, in requests and in replies; the values of query parameters, inparamsand intarget, written as bodies are; a body as{"length": n, "hmac": "<hex>"}, its length in bytes and an HMAC-SHA-256 of it under a key of the run; a reply right as<reply-right>. Path segments, header names, other header values, the method, the peer, the listener and statuses stay as they are. Both engines build these events with one implementation (una_interp::serve_trace), so they write the same text:- Where. The reduction applies to every value of the kinds
Request,Reply,HeaderandParamofstd.hostin the arguments and the outcome of these events, where the event is built, before any output: the human and--jsontraces, and the trace file of an executable, all read the same events, so no path writes the clear form. A run keeps no other recording of host results. - Form. A header is a credential by its name in any letter case, so a reply's
Set-Cookieis one, and so is every header whose name is not a token (RFC 9110 §5.6.2), such as"set-cookie "or a name with a tab or a control byte, which the host refuses to send (BadReply) and whose value is still never written.<credential>and the body form are written bare in the value's Una form, as<reply-right>is. Atargetstays a quoted text, its path as it is and, in its query after the first?, each value of a partname=value, split at its first=, replaced by the body form of the value as received, before its percent-decoding; a part without=is a name and stays, so the target keeps its shape. Inparamsthe body form is of the decoded value. - The key. 32 bytes drawn from the host's random source when the run starts, all zeros under a script of connections (ADR 0123 rule 21), so that two runs of one script, in either engine, give the same trace. The engine of the run holds it, and it is never written.
- Under the labels of this section every field of
RequestandReplyisinternal, so a run's trace shows each as<redacted:internal>, areplywhoseReplyis built frompublicdata included (Reply(status: <redacted:internal>, headers: <redacted:internal>, body: <redacted:internal>)), and the outcome ofnextas{"kind": "redacted", "level": "internal"}; the reduced form lies beneath that redaction. The runs oftests/serve_runs/also compare it in both engines with the redaction of labels lifted, which only the scripted engine of the toolchain's own tests can ask for. - Cost. O(b) for b bytes of a body or a target, one HMAC over them; O(1) for every other field.
- Where. The reduction applies to every value of the kinds
-
Diagnostics. U3033 is new (spec/13 §4). U1001, U3012, U3014, U3025, U4001, U4002, U4003, U5001 and U5002 cover the rest.
-
Costs. Holding, moving and releasing a reply right are O(1) each. The move at
startmoves the rights in the order of rule 3 item 2, with the same result in both engines, in O(objects that the marked captures reach) in the interpreter and O(objects that the task's captured values reach) in native code, which walks all captures after the copy succeeds and before the task is queued (the same order as the copy itself in cost), and costs nothing at astartwhose captures cannot hold a reply right; ADR 0123 Costs states what native code adds to the copy of the captures. The checks of this section are linear in the sites they look at. -
una runruns;una buildbuilds. The operations ofHttpServer, the holding and moving of reply rights at run time, the state machine of rule 3 item 7, the auto-answers and their events, and the reduced trace form, are in place in both engines over the engine of §6, which a run that serves starts beforemain(§6 rule 14).una runof a program whose entry function,mainor a driven module'sinit,steporon_stop, usesHttpServerruns it in the interpreter over live listeners, after every check of the program and of its grants, with the plain toolchain and no test flag.una buildof such a program, after the same checks of the program, with the plain toolchain and no test flag, makes an executable that runs it in native code over live listeners: it checks its grants, those ofrun grantsand of its own--grantflags, beforemain, starts the serve threads beforemain(§6 rule 14) and takes host stops asuna rundoes. The scripted engine of--serve-scriptruns only in the toolchain's own test builds, in both engines: in native code only in an executable linked with the runtime built with itstest-hooks, which no shippedunahas (§8 rule 6). In a run without the engine, which no program reaches, the trace writes every argument of an operation ofHttpServeras aninternalvalue is, redacted, whatever its label.una checkchecks such a program fully, anduna testruns tests that install a handler ofHttpServerwithgiven.