Home / Docs / Guides

Serving HTTP

Release v0.4.0

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:

una
run
  grants
    serve "http://127.0.0.1:8080"
      at most 256 at once
      body at most 64 KiB
      answer within 10 seconds

On 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:

examples/health/ita.unauna
ita health
  version 0.1.0
  edition 0.4

run
  grants
    serve "http://127.0.0.1:8080"

serve
  module health

The module declares handle, and optionally on_stop, in exactly these shapes, with Request and Reply of std.host (spec/31 §7 rule 2):

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

The 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:

examples/health/src/health.unauna
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.unauna
ita server
  version 0.1.0
  edition 0.4

run
  entry main
  grants
    serve "http://127.0.0.1:8080"
src/main.unauna
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:

sh
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):

una run .Output
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):

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:

examples/health/src/health.unauna
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 == 404

The 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:

una test .Output
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 failed

A 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):

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

Residual limits