Home / Docs / Specification / 31. HTTP servers

31.1 The capability

Release v0.4.0

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).

  1. Edition and names. Every name of this section exists only in packages of edition 0.4 and later. std.host declares them, and the prelude does not put them in scope: a module imports them, as import std.host (HttpServer, Request, Reply) (spec/10 §11 rule 10). An import of one is never redundant, an import of Method or ServeError brings its variants, and a kind of the package named Request or Reply stays legal. In earlier editions an import of these names is U1001, as an unknown name is. This section adds no keyword.

  2. Declarations. std.host declares, in edition 0.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 public
    • params. ADR 0123 rule 1 names the field of the decoded query query, a word that spec/01 reserves in every edition, so a field of that name could never be read. The field is params, as ADR 0123's amendment of 2026-11-06 (slice S5), section A, states.
    • Header is the kind of spec/24 §1, whose value is internal Text.
    • Labeled fields. The fields are internal, so a program can build a Reply from request data, and a test or a handler can build a Request from internal data. A constructor field is a flow site (spec/07 §7 rule 2), so a secret value in a field of a Reply is U4001 where the reply is made.
    • Status is a refinement of Int: every Reply(status: s, ...) carries the obligation 200 <= s and s <= 599 (spec/12 §3), refuted U5001 and unknown U5002.
    • ReplyRight is an opaque built-in type of std.host: it has no constructor, no literal, no fields and no order. Its values come only from next and, in tests, from std.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. next fails with Interrupted at a host stop (spec/26), TimedOut when a deadline of the program cuts its wait (spec/27 §5), and Closed after close. reply fails with NotHeld and BadReply (rules 4 and 13 of ADR 0123, §5 rule 1). close cannot fail, so a handling clause on it is U3025.
    • What each accepts. reply accepts internal (IF2). close accepts public only, so a server cannot close itself on the strength of a request's content: under a raised program counter it is U4003 (IF1). next accepts internal: ADR 0123 writes no accepts on it, and whether a task takes a request off the queue, and with it a /once slot that other tasks' deliveries wait for, could otherwise depend on secret data; under a secret program counter it is U4003.
    • What parks. next parks its task while no request is ready, and is an interruptible operation (spec/26, spec/27). reply and close never wait.
    • One instance. A run has one host instance of HttpServer, host:HttpServer, which serves every serve grant (§2).
    • Grants and examples. A uses of an HttpServer operation that no serve grant 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 whose do line needs HttpServer without a given handler is U3014 (spec/05 §9 rule 5). A test MAY install a handler of HttpServer with given, as for every capability; its operations are ordinary handler code.
  3. Reply rights (ADR 0123 rule 4). Every exchange comes with a reply right, held by exactly one task at a time:

    1. next gives the reply right of its exchange to the task that called it.
    2. start e moves to the started task every reply right that the calling task holds and that is reachable from the values e captures, closures included.
    3. No other construct moves a reply right: a branch of together, the body of a together for and a branch of first of act for the task that runs the construct (rule 4).
    4. reply succeeds only for a reply right that the calling task holds and has not answered; otherwise it fails with NotHeld, and nothing is sent. A successful reply releases it.
    5. When a task ends holding reply rights, the host answers each one, in the order the task received them: 500 when the task returned, failed or ended alone, 503 with Retry-After: 1 when it was canceled, cut by within or stopped; each appends the event {"seq": n, "task": "<path>", "outcome": {"kind": "unanswered", "status": s}}.
    6. Which task holds a reply right depends only on the order of next, start and reply in each task, never on timing.
    7. Each exchange ends by one atomic transition, the first of the program's reply, the host's answer deadline, an auto-answer, its peer leaving or a stop; a reply after another transition returns unit and 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-time they 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): a ReplyRight, a value that can hold one, and, in a package that imports HttpServer, Exchange or ReplyRight, or test_exchange of std.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 a reply through that handler in the started task fails with NotHeld, and the task that holds the right answers it at its end. Native code moves the rights that the values of the closure start copies 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, answers 503 and appends no event. Quiet code appends no unanswered event, as it appends no event of an operation (spec/26 §6 rule 4). The unanswered events of a task come before the event that ends it, cancelled or aborted. 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 its tasks statements, which cancel their tasks, each with its cancelled event; 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 open 503 with Retry-After: 1 in 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 the 503 reaches the peer. The host then answers every right still held, which sends nothing, and appends no unanswered event 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 no unanswered event. The interpreter's tasks end as at an abort of the run: each answers the rights it holds 503 with Retry-After: 1 itself, appending their unanswered events, 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.
    • next after a host stop fails with Interrupted wherever 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 next with no request to deliver lets another ready task run first, but not one that waits in next itself 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 call next waits 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 in next. A task canceled while it waits in next ends the operation with the outcome interrupted, takes no request, and the request stays queued for a later next. An abort of the run by a started task ends a next in progress with the outcome aborted, 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's next at once: the root unwinds through its tasks statements, which cancel their tasks, so a task waiting in next ends the operation interrupted, as a canceled one does, with its cancelled event, and the root then ends the run with the abort (item 5). next checks an abort of the run first, then Closed, then the host stop: a close or 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 answered 503 (item 5).
  4. 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 a together for and of a branch of first of MUST NOT contain an operation of HttpServer. U3033 is reported at each of these, written in the branch, inside a lambda written there too:

    • an operation of HttpServer, "@server.reply cannot run in a branch of together; 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 hold HttpServer;
    • an operation of a capability that has a handler in the package whose uses hold HttpServer, 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 of parameter (spec/05 §9 rule 9), or its passing on, since the code its callers pass is not known in the branch and may reply: "f runs the code its callers pass, which in a program that serves can perform an operation of HttpServer, and that cannot run in a branch of together; 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.

  5. Information flow (ADR 0123 IF1 to IF7).

    1. Requests are input (IF1). next returns an internal Exchange. Whether next succeeds is public: no argument decides it, and its failures come from host stops, from close, which accepts public only, and from deadlines, which spec/27 §5 labels. So an accept loop stays at a public program counter, and it can print.
    2. Replies accept internal (IF2). Every argument of reply is a sink with accepts internal: a secret value reaches a reply only through a policy (spec/07 §5).
    3. Failures of reply (IF3) are labeled internal at least: NotHeld and BadReply are decided by the reply right, the reply and the task's own reply rights, which the program's order decides. attempt gives an internal Result, and if error pass and if error fail are U4002.
    4. 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).
    5. 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 next receives when several serve threads hold requests.
    6. Auto-answers (IF6). A start e whose captures can hold a ReplyRight, by their types, or, in a package that imports HttpServer, Exchange or ReplyRight, or test_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 a reply at the start. 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 imports HttpServer, Exchange or ReplyRight, since the checker sees every module of the program, its dependencies included. The program counter of the start, joined with the effect floor and the timing floor around it, and with τ(e) when it has within, MUST flow to internal, else U4003 at the word start. The capture test is one look at the type of each local e reads, 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-depth ends alone, and the host answers its rights 500 where the program would have replied, so the status a peer reads can tell how deep the task went. Such a start is also U4003 when both hold:

        1. 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 via function, reaches a cycle (a function, a handler, a via or a lambda that can call itself again), a call of a function value or of a uses of parameter (the lambda node Λ, which a prelude function that applies a function argument, such as map, 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;
        2. 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, accepts and failure), binds, receives or, in a lambda, captures. A symbolic label ℓ_T counts as above internal in what the start itself reads, binds or receives, since a start in 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 internal data 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-depth is set below that chain; which chain runs is then decided at a branch, and in a program that starts tasks a branch that data above internal decide is refused (spec/27 §8 rule 5), so a lowered --task-depth makes such a task end alone, or not, by internal data 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). At internal, 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-depth needs 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 the start, holds a check point that data above internal decide, 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 above internal decides. 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, a via function, 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, as std.collections's from edition 0.5, security/server_start_depth_unseen_secret; in edition 0.4 those are std.testing's, for tests and handlers' operations only; or a module that failed to parse; path dependencies are checked with the package), or when the start lies in a handler's operation body, whose holder no function names, or when the start's own data carry a type parameter's label; a predicate and a body that evaluates a checked predicate count so too, conservatively, though a reflect predicate's body records its check points and checked on data above public is refused (spec/07 §3). So a task that recurses on the request's length and also holds a secret key that decides none of its calls is accepted (security/server_start_depth_holds_secret, live in both engines: its 200 or 500 follows 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, through srv.deep, and data above internal decide some of its calls, which may decide how deep it goes; a started task that runs past --task-depth ends alone and its rights are answered 500". One that calls a policy whose via recurses 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 read secret data, 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 on internal data, and hold secret data that decides none of its calls. The default of if error use runs under the label that decides the failure, as every branch does (spec/07 §3).

      • 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 start that moves reply rights; then O(size of the seed of e) lookups per start. Recording what a node holds costs O(open sites + log n) per binding and per operation. tests/start_reach_scaling.rs of una-check keeps 2000 starts linear.

    7. The label L_srv (ADR 0123, S4 amendment IF-S1). In a package whose code performs an operation of HttpServer, the serve threads' work after each hand-off site, an operation of HttpServer or a start of item 6, can shift every timing site of the program, so L_srv = internal ⊔ ⨆ over hand-off sites s of (sfx(s) ⊔ Suf*(node(s)) ⊔ τ_conc(s)) ⊔ L_res joins τ of every timing site, as L_res does (spec/26 §7 rule 5): every within, first of and for ever within, every tick, L_lim and the statement a limiter scopes over. It is public in a package without an operation of HttpServer. A message whose label it raises names "the requests that the serve threads handle after the server operations in m.f".
      • Preview over-approximation. sfx(s) ⊔ Suf*(node(s)), the code that can run after s, is taken as τ⁰ of the bodies of every ancestor of the function that holds s, that function included, in the call graph of ADR 0116 P1, the rule of L_lim (spec/27 §9 rule 5); and τ_conc is the preview's, ⊤ for a site in a task, a tasks block, 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, whose next stands in the block of a tasks statement, L_srv is ⊤ 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.
    8. In practice (IF7). A request task branches on internal data, so its program counter is internal: it can call Http, Files.write, limiter and reply, and cannot print. Under the preview's τ_conc, a start ... within in the block of a tasks statement whose expression performs an operation that accepts internal is refused already (spec/27 §5), so the language form below starts its tasks without within, and the host's answer deadline bounds what each peer waits.
  6. The language form (ADR 0123 rule 15). A server is a diverges function with a for ever loop that calls next and starts a task per request:

    una
    answer(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()

    next waits, parked, and fails with Interrupted at a host stop, which ends the loop at its next iteration start. tasks at most N at once bounds the program's tasks, and the grant's /once the exchanges open. A server that answers in its loop, with no tasks, is legal too.

  7. Trace events. next, reply and close are events of spec/11 §5, with instance host: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 headers authorization, proxy-authorization, cookie, set-cookie, x-api-key and x-auth-token as <credential>, in requests and in replies; the values of query parameters, in params and in target, 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, Header and Param of std.host in the arguments and the outcome of these events, where the event is built, before any output: the human and --json traces, 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-Cookie is 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. A target stays a quoted text, its path as it is and, in its query after the first ?, each value of a part name=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. In params the 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 Request and Reply is internal, so a run's trace shows each as <redacted:internal>, a reply whose Reply is built from public data included (Reply(status: <redacted:internal>, headers: <redacted:internal>, body: <redacted:internal>)), and the outcome of next as {"kind": "redacted", "level": "internal"}; the reduced form lies beneath that redaction. The runs of tests/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.
  8. Diagnostics. U3033 is new (spec/13 §4). U1001, U3012, U3014, U3025, U4001, U4002, U4003, U5001 and U5002 cover the rest.

  9. Costs. Holding, moving and releasing a reply right are O(1) each. The move at start moves 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 a start whose 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.

  10. una run runs; una build builds. The operations of HttpServer, 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 before main (§6 rule 14). una run of a program whose entry function, main or a driven module's init, step or on_stop, uses HttpServer runs 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 build of 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 of run grants and of its own --grant flags, before main, starts the serve threads before main (§6 rule 14) and takes host stops as una run does. The scripted engine of --serve-script runs only in the toolchain's own test builds, in both engines: in native code only in an executable linked with the runtime built with its test-hooks, which no shipped una has (§8 rule 6). In a run without the engine, which no program reaches, the trace writes every argument of an operation of HttpServer as an internal value is, redacted, whatever its label. una check checks such a program fully, and una test runs tests that install a handler of HttpServer with given.