---
title: "31.7 The host-driven form: serve"
url: https://una-lang.org/en/docs/spec/31-http-servers/7-the-host-driven-form-serve/
release: v0.4.0
source: https://github.com/una-lang/una/blob/v0.4.0/docs/spec/31-http-servers.md
---

# 31.7 The host-driven form: serve

ADR 0123 rules 16 and 22, with decisions S6-D1 to S6-D6 of `docs/plan/0123-s6-design.md`. The section, its checks, its usage errors and the report's entries are in this section. The driver that runs the program of rule 4 runs in both engines, over the operations of `HttpServer` (§1 rule 10): `una run` runs it, and `una build` builds it into an executable that runs it (rule 5).

1. **The section.** In `ita.una` (`spec/30 §2`), the `serve` section names the module whose functions the host calls, and optionally a per-request deadline in milliseconds:

   ```text
   serve
     module shop.api
     within 10000
   ```

   - Its lines are `module`, a module of the package, and `within`, an integer from 1 to 86,400,000. A missing `module`, a `within` out of range, a line of another form, a line given twice, the section given twice, a module that is not a module of the package, and a `serve` section beside a `run entry` or a `drive` section (a package runs one program), are U7008 at the line, or at the value for one out of range. A section with any problem inside it, one the grammar finds included (a line given twice, an unknown line, a malformed literal), is not read: nothing else is reported of it, and a run never serves what it does not say.
   - `una.toml` has no `[serve]` table: edition `0.4` is written in `ita.una` only (ADR 0122), so `[serve]` in `una.toml` is U7002 as any unknown table. A dependency's `serve` section is not read, as its `run` and `drive` sections are not (ADR 0122 rule 12).
   - `run grants` keeps its meaning. A run of a package with a `serve` section and no `serve:` grant, in `run grants` or by `--grant`, is a usage error, exit code 2, before anything starts.
2. **The module.** It declares:

   ```una
   pub handle(request: internal Request) -> internal Reply
   pub on_stop() -> Unit                 -- optional
   ```

   with `Request` and `Reply` of `std.host` (§1 rule 2), and neither has a `requires` clause: the host calls `handle` for every request it reads and `on_stop` at every stop, and no call of the host establishes a precondition, so a `requires` would be a fact the verifier assumes and nothing proves. A `requires` on either is U7008 at the section's `module`, with the clause as the related span, in `una check`; so is a refined type of a parameter or of the result of either, written there or carried by a refined kind such as `kind Full = Request where it.body != ""`, with the type as the related span, since a refinement of the parameter is the same precondition and the shape is exact. A module without `handle` of exactly this shape (public, no type parameters, one parameter passed by value whose type is `internal Request`, the result `internal Reply`), or with an `on_stop` that is not `pub on_stop() -> Unit`, is a usage error, exit code 2, of `una run` and `una build`, as for `drive` (`spec/26 §2`); the message names the module, the section and the first difference found.
3. **Checks** (`una check`):
   1. `handle` and `on_stop` MAY declare `uses`, checked against the grants as `main`'s are (U3012, `spec/05 §7`): against `run grants` in `una check`, and against the final grants, `--grant` flags included, in `una run`.
   2. `handle` MAY declare `fails`. `on_stop` MUST NOT (U3029 at the clause): the host has no caller to give a failure to.
   3. Neither may say `diverges` (U3027 at the clause): every request, and the stop, ends after finitely many steps (ADR 0116 rule 9).
   4. Neither may name `HttpServer`, or a capability whose handlers can perform one of its operations (§1 rule 4), in its `uses` (U3033 at the binding; decision S6-D3). In this form the host owns every exchange and answers each request with the reply `handle` returns, so a `handle` that took, answered or closed exchanges would take work from the driver, or stop the server from a request. A public function's effect set is bounded by its declared `uses` (`spec/05 §3`), so this refuses every operation of `HttpServer` in their effect sets, through a callee, a function value or a handler included. A server that takes requests itself is written in the language form (§1 rule 6, ADR 0123 rule 15) without a `serve` section.
   5. A `Reply` built from `secret` data is U4001 at the field, as for every constructor of `Reply` (§1 rule 2).
   6. **The driver is a hand-off site** of `L_srv` (§1 rule 5 item 7, IF-S1): its `next` is inside the `tasks` statement whose started tasks run `handle`, so the preview's `τ_conc` at it is `⊤`, as for the language form's `next`, and `L_srv` of a package with a `serve` section is the top label. It raises every timing site of the package (a `within`, a `first of`, a limit), as it does in a language-form server.
   7. **`within`.** With `within w`, the driver's `start answer(exchange) within w` moves the exchange's reply right to its task, whose cut by the deadline the host answers with `503` (§1 rule 3). That answer accepts `internal`, so `τ(e)` of the started expression, the timing of `handle` joined with `L_res` (which holds `L_srv`) and `τ_conc`, MUST flow to `internal`: U4003 at the value of `within` otherwise (§1 rule 5 item 6, IF6). While `L_srv` of the preview is `⊤` (item 6), every `within` of a `serve` section is U4003, as the language form's `start ... within` is; the label MAY become less strict with a more precise `L_srv` (#1155), and MUST NOT become stricter. Without `within`, the grant's `answer` bounds what each peer waits (§2), and `handle` cannot diverge.
4. **Meaning.** `una run` and the executable that `una build` writes run this program, with `handle` and `on_stop` from the module (ADR 0123 rule 16):

   ```una
   main() -> Unit
     uses @server: HttpServer[next, reply]
     diverges
   =
     tasks at most B at once                   -- B: the sum of `/once` over the run's `serve:` grants, within the default bound
       for ever
         let next = attempt @server.next()
         when next
           is Ok(exchange) ->
             start answer(exchange) within w   -- `within w`, and the clause below, only with `within`
               if error use unit
           is Err(failure) -> unit
     on_stop()                                 -- only when declared, after every request has drained

   answer(exchange: internal Exchange) -> Unit
     uses @server: HttpServer[reply]           -- and the `uses` of handle
   =
     let reply = handle(exchange.request)
       if error use Reply(status: 500, headers: [], body: "")   -- only when handle declares fails
     @server.reply(to: exchange.right, reply: reply)
       if error use unit
   ```

   - A failure of `handle` becomes `500` with an empty body, never the failure's payload. A `reply` that fails with `BadReply` sends nothing, and the task's end then answers `500` (§1 rule 3).
   - The driver is engine code equivalent to this program, not Una source or Core IR that the package gains (decision S6-D4): `una core` of the package does not change, and `handle` stays an ordinary function for the checker, the verifier and tests, which call it directly with a `Request` they build.
   - At a host stop, `next` fails with `Interrupted`, the loop ends, the started tasks drain, `on_stop` runs on the main task with the run's grants, and the run ends with exit code 0; at the hard stop every task is canceled, the auto-answers of their reply rights are sent, `on_stop` does not run, and the run ends with U6007 (ADR 0123 rule 18).
   - The `tasks` statement is bounded by `B`, the sum of `/once` over the run's `serve:` grants, within the default bound of a `tasks` statement (`spec/27 §7`, `max(64, M)` within the cap on tasks), and at least 1 (#1724). A started task holds its place until its `handle` and its `reply` end, not only while its exchange is open: a peer that leaves, or an `answer` that passes, ends the exchange and gives back its `/once` place, but not the task's place. While `B` tasks run, the driver waits at `start` and takes no request, and the requests wait in the engine under its own limits, answered `503` at `answer` when no place frees in time. The bound is shared by the grants (decision S6-D6).
5. **Run and built.** `una run` of a package with a `serve` section reports, in this order, the usage error of rule 2 and the usage error of a missing `serve:` grant (rule 1), and then runs the driver in the interpreter, as it runs a program of the language form (§1 rule 10). `una build` reports the usage error of rule 2 and requires no `serve:` grant, since the executable's grants may come from its flags; the executable reports the usage error of rule 1 at its start. Each usage error has exit code 2, and each comes before any listener is bound or any program code runs. `una check`, `una test` and `una report` of such a package work: tests call `handle` directly. `una build` builds the driver into an executable, whose description carries the section as `"serve": {"module": ..., "within": ...}` and which runs it, as it builds a program of the language form (§1 rule 10); an executable whose description names a `within` refuses to start. In both engines the serve threads start before the driver, which is the run's main task and accepts from its first `next`; the requests' events are those of the program of rule 4, the root task's and those of its started tasks `s1.k`, byte for byte, in both engines (`tests/serve_runs/serve_section_*`). The driver of a `within` waits for the label of rule 3 item 7, which refuses every `within` today.
6. **The report** (`spec/13 §6`, ADR 0123 rule 22), additions within `una.report/2`, for a package with a `serve:` grant or a `serve` section, which **serves**:
   - `tcb.host_capabilities` lists `HttpServer` when the package serves, or when a function or handler of it uses `HttpServer`.
   - `tcb.serve_grants` lists each `serve:` grant of `run grants`, in order, as `{"address": "127.0.0.1:8080", "scheme": "http", "limits": {...}, "checks_host": true}`: `limits` holds every item of §2's table but the TLS files and `hosts`, with its default applied, sizes in bytes, times in seconds, a rate as `"N/second"`, and `null` for `none` or no rate; `checks_host` is `false` for `hosts=*`. A package that serves nothing has `[]`.
   - `tcb.server` is `"una-http/serve"`, the server code of the host, for a package that serves, and `null` otherwise; `tcb.tls` is `null` while no TLS server is built (§6 rule 10).
   - `out_of_model` gains, at its end: "what a server's peers send in reaction to its timing, and which requests its full queues refuse"; "what a peer receives when the host's deadlines cut an exchange"; and "which request a call of `next` receives when several serve threads hold requests, which the timing of every task of the run and of the serve threads decides" (ADR 0123 S4 amendment, section E).
   - `warnings`, a new key after `out_of_model`, a list of sentences, `[]` when none, in the order of the grants: a plain `http` grant on an address that is not loopback, a wildcard included; a grant with `hosts=*`; with `peer=none`; with `peer_buffers=none`; with `tls12`. Warnings appear in the report only.
   - The human form prints `server:` in the `tcb` lines, a `servers:` section with one line per grant, and each warning as a `warning:` line after `out of model`.
7. **Costs.** The section is read in O(lines); the checks of rule 3 are O(clauses + uses) of the two functions, with the timing label of item 7 the one rule of every timing label, O(functions + call edges + operations); the report's entries are O(grants).
