Home / Docs / Specification / 31. HTTP servers
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).
-
The section. In
ita.una(spec/30 §2), theservesection names the module whose functions the host calls, and optionally a per-request deadline in milliseconds:unaserve module shop.api within 10000- Its lines are
module, a module of the package, andwithin, an integer from 1 to 86,400,000. A missingmodule, awithinout 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 aservesection beside arun entryor adrivesection (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.tomlhas no[serve]table: edition0.4is written inita.unaonly (ADR 0122), so[serve]inuna.tomlis U7002 as any unknown table. A dependency'sservesection is not read, as itsrunanddrivesections are not (ADR 0122 rule 12).run grantskeeps its meaning. A run of a package with aservesection and noserve:grant, inrun grantsor by--grant, is a usage error, exit code 2, before anything starts.
- Its lines are
-
The module. It declares:
unapub handle(request: internal Request) -> internal Reply pub on_stop() -> Unit -- optionalwith
RequestandReplyofstd.host(§1 rule 2), and neither has arequiresclause: the host callshandlefor every request it reads andon_stopat every stop, and no call of the host establishes a precondition, so arequireswould be a fact the verifier assumes and nothing proves. Arequireson either is U7008 at the section'smodule, with the clause as the related span, inuna check; so is a refined type of a parameter or of the result of either, written there or carried by a refined kind such askind 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 withouthandleof exactly this shape (public, no type parameters, one parameter passed by value whose type isinternal Request, the resultinternal Reply), or with anon_stopthat is notpub on_stop() -> Unit, is a usage error, exit code 2, ofuna runanduna build, as fordrive(spec/26 §2); the message names the module, the section and the first difference found. -
Checks (
una check):handleandon_stopMAY declareuses, checked against the grants asmain's are (U3012, spec/05 §7): againstrun grantsinuna check, and against the final grants,--grantflags included, inuna run.handleMAY declarefails.on_stopMUST NOT (U3029 at the clause): the host has no caller to give a failure to.- Neither may say
diverges(U3027 at the clause): every request, and the stop, ends after finitely many steps (ADR 0116 rule 9). - Neither may name
HttpServer, or a capability whose handlers can perform one of its operations (§1 rule 4), in itsuses(U3033 at the binding; decision S6-D3). In this form the host owns every exchange and answers each request with the replyhandlereturns, so ahandlethat 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 declareduses(spec/05 §3), so this refuses every operation ofHttpServerin 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 aservesection. - A
Replybuilt fromsecretdata is U4001 at the field, as for every constructor ofReply(§1 rule 2). - The driver is a hand-off site of
L_srv(§1 rule 5 item 7, IF-S1): itsnextis inside thetasksstatement whose started tasks runhandle, so the preview'sτ_concat it is⊤, as for the language form'snext, andL_srvof a package with aservesection is the top label. It raises every timing site of the package (awithin, afirst of, a limit), as it does in a language-form server. within. Withwithin w, the driver'sstart answer(exchange) within wmoves the exchange's reply right to its task, whose cut by the deadline the host answers with503(§1 rule 3). That answer acceptsinternal, soτ(e)of the started expression, the timing ofhandlejoined withL_res(which holdsL_srv) andτ_conc, MUST flow tointernal: U4003 at the value ofwithinotherwise (§1 rule 5 item 6, IF6). WhileL_srvof the preview is⊤(item 6), everywithinof aservesection is U4003, as the language form'sstart ... withinis; the label MAY become less strict with a more preciseL_srv(#1155), and MUST NOT become stricter. Withoutwithin, the grant'sanswerbounds what each peer waits (§2), andhandlecannot diverge.
-
Meaning.
una runand the executable thatuna buildwrites run this program, withhandleandon_stopfrom the module (ADR 0123 rule 16):unamain() -> 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
handlebecomes500with an empty body, never the failure's payload. Areplythat fails withBadReplysends nothing, and the task's end then answers500(§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 coreof the package does not change, andhandlestays an ordinary function for the checker, the verifier and tests, which call it directly with aRequestthey build. - At a host stop,
nextfails withInterrupted, the loop ends, the started tasks drain,on_stopruns 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_stopdoes not run, and the run ends with U6007 (ADR 0123 rule 18). - The
tasksstatement is bounded byB, the sum of/onceover the run'sserve:grants, within the default bound of atasksstatement (spec/27 §7,max(64, M)within the cap on tasks), and at least 1 (#1724). A started task holds its place until itshandleand itsreplyend, not only while its exchange is open: a peer that leaves, or ananswerthat passes, ends the exchange and gives back its/onceplace, but not the task's place. WhileBtasks run, the driver waits atstartand takes no request, and the requests wait in the engine under its own limits, answered503atanswerwhen no place frees in time. The bound is shared by the grants (decision S6-D6).
- A failure of
-
Run and built.
una runof a package with aservesection reports, in this order, the usage error of rule 2 and the usage error of a missingserve:grant (rule 1), and then runs the driver in the interpreter, as it runs a program of the language form (§1 rule 10).una buildreports the usage error of rule 2 and requires noserve: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 testanduna reportof such a package work: tests callhandledirectly.una buildbuilds 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 awithinrefuses to start. In both engines the serve threads start before the driver, which is the run's main task and accepts from its firstnext; the requests' events are those of the program of rule 4, the root task's and those of its started taskss1.k, byte for byte, in both engines (tests/serve_runs/serve_section_*). The driver of awithinwaits for the label of rule 3 item 7, which refuses everywithintoday. -
The report (spec/13 §6, ADR 0123 rule 22), additions within
una.report/2, for a package with aserve:grant or aservesection, which serves:tcb.host_capabilitieslistsHttpServerwhen the package serves, or when a function or handler of it usesHttpServer.tcb.serve_grantslists eachserve:grant ofrun grants, in order, as{"address": "127.0.0.1:8080", "scheme": "http", "limits": {...}, "checks_host": true}:limitsholds every item of §2's table but the TLS files andhosts, with its default applied, sizes in bytes, times in seconds, a rate as"N/second", andnullfornoneor no rate;checks_hostisfalseforhosts=*. A package that serves nothing has[].tcb.serveris"una-http/serve", the server code of the host, for a package that serves, andnullotherwise;tcb.tlsisnullwhile no TLS server is built (§6 rule 10).out_of_modelgains, 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 ofnextreceives 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 afterout_of_model, a list of sentences,[]when none, in the order of the grants: a plainhttpgrant on an address that is not loopback, a wildcard included; a grant withhosts=*; withpeer=none; withpeer_buffers=none; withtls12. Warnings appear in the report only.- The human form prints
server:in thetcblines, aservers:section with one line per grant, and each warning as awarning:line afterout of model.
-
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).