Home / Docs / Specification / 31. HTTP servers

31.7 The host-driven form: serve

Release v0.4.0

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:

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