Serving HTTP
This page shows how a package of edition 0.4 answers HTTP/1.1 requests: how a run is granted an address to listen on, the two ways to write a server, what happens when the server is stopped, how its tests reach the request handling, and what the report says about it. The specification, spec/31, is normative, and this page only points to it. Edition 0.4 is a preview, and the limits of servers in this release are listed in Known limits.
The worked example is examples/health: a server that answers GET /health with 200 ok, and every other request with 404.
Grants: an address and its limits
A run listens only on an address that a serve: grant names; there is no other way for a program to accept connections. In ita.una the grant is a serve line under run grants, with one item per line below it (spec/31 §2 rule 3). This run section, in place of the one of examples/health, grants its address with four limits:
run
grants
serve "http://127.0.0.1:8080"
at most 256 at once
body at most 64 KiB
answer within 10 secondsOn the command line the same grant is --grant 'serve:http://127.0.0.1:8080;256/once;body=64;answer=10', its items written as ; suffixes and the whole value quoted, since a shell ends a command at an unquoted ; (spec/31 §2 rule 1). The address is an IPv4 address, or an IPv6 address in brackets, and always a port; a host name is refused, since nothing resolves a grant. 0.0.0.0 and [::] mean every interface (spec/31 §2 rule 1).
Every grant has limits, whether it writes them or not. The defaults include 256 exchanges delivered and not yet answered (/once), 1024 requests read and waiting to be delivered (waiting), 1024 open connections, 64 of them from one peer at that default (peer), a body of at most 1024 KiB, and 30 seconds from the end of a request to the start of its reply (answer); the table of spec/31 §2 rule 2 lists every item, its default and its range. When a limit is reached, the host answers for the program, with an empty body, as spec/31 §6 rule 7 lists: 503 with Retry-After: 1 when waiting is full or a request waits past answer, 408 for a request not read in time, 421 for a Host the grant does not allow.
Host is checked too: without a hosts item, a request's Host must be localhost or an IP literal, else the host answers 421; with hosts, it must match a listed name (spec/31 §2 rule 5).
The serve section
In the host-driven form, the package declares no main. A serve section in ita.una names the module whose handle the host calls once for each request it reads (spec/31 §7 rule 1). This is the manifest of examples/health:
ita health
version 0.1.0
edition 0.4
run
grants
serve "http://127.0.0.1:8080"
serve
module healthThe module declares handle, and optionally on_stop, in exactly these shapes, with Request and Reply of std.host (spec/31 §7 rule 2):
pub handle(request: internal Request) -> internal Reply
pub on_stop() -> UnitThe host owns every connection and answers each request with the reply handle returns, so handle is an ordinary function, which the checker, the verifier and the tests see as any other. This is handle of examples/health:
pub handle(request: internal Request) -> internal Reply
=
if request.method is Get and request.segments == ["health"]
Reply(status: 200, headers: [], body: "ok")
else
Reply(status: 404, headers: [], body: "")The request and the reply are internal: a reply carries what the server's peers may read, and a Reply built from secret data is U4001 (spec/31 §7 rule 3 item 5). handle may declare uses and fails; a failure of handle becomes 500 with an empty body, never the failure's payload (spec/31 §7 rules 3 and 4). Neither function may say diverges, or name HttpServer in its uses (U3027, U3033; spec/31 §7 rule 3).
The language form
A program can also take requests itself, through the operations next, reply and close of the capability HttpServer. Its main is a diverges function with a for ever loop that calls next and starts a task per request (spec/31 §1 rule 6). This server answers every request with 200 ok; its ita.una names run entry main and a serve: grant, and no serve section:
ita server
version 0.1.0
edition 0.4
run
entry main
grants
serve "http://127.0.0.1:8080"module main
import std.host (Exchange, HttpServer, Reply)
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
pub main() -> 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()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 (spec/31 §1 rule 6). A package has one program: a serve section beside a run entry is U7008 (spec/31 §7 rule 1).
Running a server
una run serves a package with a serve section, and a program of the language form, in the interpreter over live listeners, and so does the executable that una build makes of it (below), after every check of the program and of its grants (spec/31 §1 rule 10, §7 rule 5). From examples/health:
una run .Once the serve threads have started, and before the first request, the run writes one line on stderr for each serve: grant, in the order of the grants (spec/31 §6 rule 14):
serving on 127.0.0.1:8080 (granted by the package)A grant given with --grant is written serving on 127.0.0.1:8080 (granted by a `--grant` flag) instead, so a run never serves an address unseen.
Stopping. SIGINT (Ctrl-C) or SIGTERM is a host stop (spec/26 §6 rule 1). The host closes every listener at once and closes idle connections; requests not yet delivered, or still being read, are answered 503; delivered exchanges drain, each reply carrying Connection: close (spec/31 §6 rule 9). In the host-driven form, next fails with Interrupted, the loop ends, the started tasks drain, on_stop runs, and the run ends with exit code 0 (spec/31 §7 rule 4). The hard stop comes at the end of the grace period, --stop-grace seconds after the first request (10 by default), or at a second request: each open exchange is answered 503, and the run ends with U6007, exit code 1 (spec/26 §6 rule 6, spec/31 §6 rule 9).
Only a run that can take a host stop, one with a serve section, a driver, or a main that says diverges, installs the handlers of SIGINT and SIGTERM. A server of the language form whose main does not say diverges keeps their default actions: SIGTERM ends its process at once, with no drain, and a shell reports exit code 143 (spec/31 §6 rule 14).
Building. una build builds a program that serves, a package with a serve section or a program of the language form, into a native executable, with no test flag (spec/31 §1 rule 10, §7 rule 5). The executable checks its grants, those of run grants and of its own --grant flags, before main, writes the same serving on ... line for each address, serves as una run does, and drains at SIGINT or SIGTERM as above. una build of a package with a serve section needs no serve: grant, since the executable's may come from its flags; an executable started without one is a usage error, exit code 2 (spec/31 §7 rule 1).
Testing a server
Tests run in the interpreter (spec/31 §8 rule 5). std.testing gives two functions for servers, which only tests and the handlers that only tests install may call (U3015; spec/31 §8):
test_request(method: Method, target: Text, body: Text) -> Request fails TestRequestErrorgives the request the host would read from a peer that sent that method and target withHTTP/1.1, the one headerHost: test, andbody. The host's own reader reads it, so itssegmentsandparamsare decoded as the host decodes them, and it fails withRefusedwhere the host would answer400, as for a..segment or a#(spec/31 §8 rule 1).test_exchange(request: Request) -> Exchangegives an exchange of that request with a fresh reply right, for a test of the language form: a handler ofHttpServerthat the test installs withgivenreceives it inreply(spec/31 §8 rule 3).
A test of the host-driven form calls handle directly. These are the three tests of examples/health, each with a request that test_request builds:
test "the health endpoint answers ok"
do handle(test_request(method: Get, target: "/health", body: ""))
expect result.status == 200
test "every other path is not found"
do handle(test_request(method: Get, target: "/other", body: ""))
expect result.status == 404
test "a request of another method is not found"
do handle(test_request(method: Post, target: "/health", body: ""))
expect result.status == 404The first sends GET /health, whose segments are ["health"], and reads 200. The second keeps the method and changes the path, and the third keeps the path and changes the method, so each branch of the condition in handle is taken by one test. una test . runs them:
test health "the health endpoint answers ok" ... ok
test health "every other path is not found" ... ok
test health "a request of another method is not found" ... ok
3 tests: 3 passed, 0 failedA test of the language form calls the function that answers an exchange with a handler installed, as given @server = accepting() with a handler accepting of HttpServer, and checks expect performed @server.reply (spec/31 §8 rule 3).
What the report says
una report of a package with a serve: grant or a serve section adds what it serves (spec/31 §7 rule 6, spec/13 §6):
HttpServeramong the host capabilities, andserver: una-http/serve, the server code of the host, in thetcblines;- a
servers:section with one line per grant ofrun grantsand its limits, the defaults applied, such ashttp://127.0.0.1:8080: 256/once, rate none, waiting 1024, connections 1024, peer 64, ...; - three entries at the end of
out of model: 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; - a
warning:line for each grant that is plainhttpon an address that is not loopback, a wildcard included, and forhosts=*,peer=none,peer_buffers=noneandtls12.
With --json, these are the keys tcb.host_capabilities, tcb.serve_grants, tcb.server, tcb.tls, out_of_model and warnings of una.report/2.
Refusals
withinin a server. Under the preview, the labelL_srvof a server of the language form, and of a package with aservesection, is the top label, and so is every timing site of the package (spec/31 §1 rule 5 item 7). So everywithinof aservesection is U4003 (spec/31 §7 rule 3 item 7), and astart ... withinin the block of atasksstatement whose expression performs an operation that acceptsinternalis refused: a server starts its request tasks withoutwithin, and the grant'sanswerbounds what each peer waits (spec/31 §1 rule 5 item 8).httpsgrants fail closed. Anhttpsgrant needscertificateandkeyfiles, which the run loads and checks beforemain(spec/31 §2 rules 7 and 8). The TLS server waits for the decision on the project's TLS provider (#1059), so a run with anhttpsgrant does not serve: it fails closed instead of serving plain bytes on anhttpsaddress (spec/31 §6 rule 10).- No
serve:grant. A run of a package with aservesection and noserve:grant, inrun grantsor by--grant, is a usage error, exit code 2, before anything starts (spec/31 §7 rule 1). - A wrong
handle. A module withouthandleof exactly the shape above, or with anon_stopof another shape, is a usage error, exit code 2, ofuna runanduna build, that names the first difference found (spec/31 §7 rule 2).
Residual limits
- No share per peer for three limits. A grant's
waiting,/onceanddeliveredhave no share per peer, so one peer, or a few, can take the whole of each budget. At the defaults,waitingholds 1024 requests and one peer may hold 64 connections, so about 16 well-behaved addresses can fillwaitingand hold back every other peer's requests until those are delivered or time out (spec/31 §2 rule 2,§6rule 5). An operator facing it raises the grant's limits or puts a filter in front (ADR 0123 rule 7). - A grant that serves nothing. A run that holds a
serve:grant but does not serve, whose program never usesHttpServerand that has noservesection, still binds its listeners beforemain, accepts nothing on them and writes noserving online (spec/31 §6 rule 14). Read a package'srun grants, or its report, before running it. --serve-script. The scripted connections of--serve-scriptrun only in the toolchain's own test builds (spec/31 §8 rule 6).