Tern

http

The http module is Tern's HTTP: two servers, a client, and the request and response types they share. http.serve is the one-line server: an HTTP/1.1 event loop on every core that calls one handler function for each request. The engine (http.new_server) is the server web frameworks are built on: routes, WebSockets, server-sent events, streamed bodies, static files and HTTPS, on the task runtime. roost, the router and middleware framework, is written on top of it, and its roost.Request and roost.Response are this module's types under another name. This page covers the types, serve, every request and response function, the engine, the client, and the helpers middleware uses.

Compiles (not run here)
import http

fn handle(req: http.Request) http.Response:
    if req.path == "/":
        return http.text("hello " + req.query("name"))
    return http.not_found()

fn main():
    http.serve(8080, handle)

Build and run it, then visit http://localhost:8080/?name=ada:

tern build hello.tn -o hello && ./hello
# tern: serving http://localhost:8080 on 14 threads

The whole app compiles to one small binary with no dependencies beyond the C library (and SQLite, if you import sqlite). A program pays only for what it calls: an http.serve app doesn't carry the engine, and neither links TLS unless it imports tls.

Request

struct Request:
    method: str                 # "GET", "POST", ...
    path: str                   # "/users/42" (without the query string)
    raw_query: str              # "page=2&sort=name" (see query)
    head: str                   # header lines as received, "Name: value\r\n" each (see header)
    body: str
    params: str                 # path parameters of an engine route, packed (see param)
    ctx: {str: str}             # values middleware passes to inner handlers (see set_ctx)
    conn: int                   # the connection's socket (see peer and client_ip)
  • path is the part of the URL before ?, exactly as the client sent it: it is not URL-decoded (/a%20b stays /a%20b). http.match and route parameters decode what they capture.
  • raw_query is the part after ?, also raw, or "" if there is none. Read values with req.query(name).
  • head holds the header lines as the client sent them. Read them with req.header(name), which ignores case.
  • body is the request body (for example, a JSON document or a form), as bytes.

Reading requests

fn query(req: Request, name: str) str           a query parameter, decoded ("" if absent)
fn queries(req: Request) {str: str}             every query parameter
fn header(req: Request, name: str) str          a header, ignoring case ("" if absent)
fn headers(req: Request) {str: str}             every header (lowercase names)
fn cookie(req: Request, name: str) str          a cookie from the Cookie header
fn form(req: Request, name: str) str            a field of an x-www-form-urlencoded body
fn forms(req: Request) {str: str}               every field of one
fn parts(req: Request) [Part]                   a multipart/form-data body (file uploads)
fn part(req: Request, name: str) Part           the part for one field (name "" if none)
fn param(req: Request, name: str) str           a path parameter of an engine route
fn param_int(req: Request, name: str, default: int) int
fn params(req: Request) {str: str}
req.json(&value) bool                           decode the JSON body into value (needs import json)
fn add_header(req: mut Request, name: str, value: str)
fn set_ctx(req: mut Request, key: str, value: str)    fn ctx_value(req: Request, key: str) str
fn new_request(method: str, target: str, body: str) Request

Call them as methods: req.query("page"). query and form decode + and %XX; a name that appears more than once gives its first value, and a name with no = (as in ?debug) is "". to_int reads a number: req.query("page").to_int(1). Part has name (the form field), filename ("" for a plain field), content_type and data.

http.new_request(method, target, body) builds a request the way the servers do, for calling a handler in a test: target is the path with its query string, and add_header adds headers.

import http

fn main():
    req = http.new_request("GET", "/search?q=tern+lang&page=2&tag=a%26b&debug", "")
    req.add_header("User-Agent", "curl/8.0")
    req.add_header("Cookie", "theme=dark; sid=abc")
    print(req.path, "|", req.query("q"), req.query("page").to_int(1), req.query("tag"), "[" + req.query("debug") + "]")
    print(req.header("user-agent"), req.header("X-API-KEY") == "", req.cookie("sid"))
    print(req.headers())
    print(req.queries())
Output
/search | tern lang 2 a&b []
curl/8.0 true abc
{"user-agent": "curl/8.0", "cookie": "theme=dark; sid=abc"}
{"q": "tern lang", "page": "2", "tag": "a&b", "debug": ""}

Response

struct Response:
    status: int
    content_type: str
    body: str
    headers: str                # extra header lines, "Name: value\r\n" each (see set_header)
    upgrade: int                # 1: WebSocket, 2: event stream (set by ws_upgrade / sse_open)

The server writes the status line, a Content-Type header from content_type (left out if it is ""), the lines in headers as they are, a Content-Length, and the body.

fn text(body: str) Response                 200, text/plain; charset=utf-8
fn html(body: str) Response                 200, text/html; charset=utf-8
fn json(body: str) Response                 200, application/json
fn status(code: int, body: str) Response    any status, plain text
fn not_found() Response                     404 "not found"
fn no_content() Response                    204
fn redirect(to: str) Response               302 with Location
fn redirect_permanent(to: str) Response     308 with Location
fn with_status(res: Response, code: int) Response
fn set_header(res: mut Response, name: str, value: str)
fn set_cookie(res: mut Response, name: str, value: str)     Path=/; HttpOnly; SameSite=Lax
fn set_cookie_with(res: mut Response, name: str, value: str, attrs: str)
fn get_header(res: Response, name: str) str
fn header_line(name: str, value: str) str   "Name: value\r\n"

html sends the body as it is: escape user input yourself (see html). json's body must already be JSON text, usually from json.encode: http.json(json.encode(users)). set_header("Content-Type", ...) sets content_type; other names add a line to headers.

import http

fn main():
    print(http.text("hi"))
    print(http.json("[1,2]").content_type, "|", http.html("<p>").content_type)
    r = http.redirect("/login")
    print(r.status, r.get_header("location"), r.body == "")
    csv = http.Response(200, "text/csv", "id,name\n1,ada\n", "", 0)
    csv.set_header("Cache-Control", "no-store")
    csv.set_cookie("sid", "abc")
    print(csv.get_header("cache-control"), "|", csv.get_header("set-cookie"))
    print(http.with_status(http.json(`{"error":"taken"}`), 409).status)
Output
http.Response{status: 200, content_type: "text/plain; charset=utf-8", body: "hi", headers: "", upgrade: 0}
application/json | text/html; charset=utf-8
302 /login true
no-store | sid=abc; Path=/; HttpOnly; SameSite=Lax
409

match

fn match(path: str, pattern: str, params: mut {str: str}) bool

Routing for serve's handlers (the engine and roost route by themselves). It matches a path against a pattern such as "/users/{id}/posts/{post}", where each {name} matches one whole path segment. On a match, it returns true and replaces params with the captured values (URL-decoded), keyed by name. If it doesn't match, it returns false and leaves params unchanged.

The path and the pattern must have the same number of /-separated segments, so /users/42/ (with a trailing slash) doesn't match /users/{id}. A segment can be empty: /users/ matches /users/{id} with id equal to "", so check captured values before using them. Captured values are always strings; convert them with to_int.

import http

fn main():
    p: {str: str} = {}
    print(http.match("/users/42/posts/7", "/users/{id}/posts/{post}", &p), p)
    print(http.match("/files/my%20notes.txt", "/files/{name}", &p), p)
    print(http.match("/users/42/", "/users/{id}", &p), p)
    print(http.match("/users/", "/users/{id}", &p), p)
    print(http.match("/about", "/about", &p), p)
    id = 0
    if http.match("/orders/1001", "/orders/{id}", &p):
        id = p["id"].to_int(-1)
    print(id)
Output
true {"id": "42", "post": "7"}
true {"name": "my notes.txt"}
false {"name": "my notes.txt"}
true {"id": ""}
true {}
1001

match is a soft keyword in Tern, which is why a function can be called match.

serve

fn serve(port: int, handler)                 # handler: fn(req: http.Request) http.Response
fn serve(port: int, handler, app)            # handler: fn(req: http.Request, app: App) http.Response
fn serve(port: int, handler, &app)           # handler: fn(req: http.Request, app: mut App) http.Response

Listens on port on every network interface (IPv4) and answers requests forever; serve never returns. The handler must be a top-level function (not a lambda) of the shape shown. The compiler generates the glue between the server and your handler, which is why serve has three forms instead of a single signature.

It prints tern: serving http://localhost:PORT on N threads to standard error. If the port can't be used (for example, another program has it), it prints tern: bind: Address already in use and the program exits with status 1.

Sharing state with handlers

The third argument chooses how handlers see your app's data:

FormThe handler getsRequests run
serve(port, handle)nothing but the requestfully in parallel
serve(port, handle, app)app: App, read-only, shared by all threadsfully in parallel
serve(port, handle, &app)app: mut App, which it may changeone at a time

The read-only form is for data loaded once at start-up (configuration, lookup tables, a sqlite.Db). The mut form lets handlers change shared state safely: the server runs such requests one at a time, so two requests can never race on app. Keep those handlers short; for heavy traffic, keep changing data in the database instead.

The compiler checks that the form matches the handler:

Does not compile
import http

struct Counter:
    hits: int

fn handle(req: http.Request, c: mut Counter) http.Response:
    c.hits += 1
    return http.text(f"visit number {c.hits}")

fn main():
    c = Counter(0)
    http.serve(8080, handle, c)
Compiler output
12: error: `handle` changes the app state, so pass it with `&`; requests then run one at a time

With http.serve(8080, handle, &c) it compiles, and every visitor gets a unique number.

Threads

The server runs an event loop (kqueue on macOS, epoll on Linux and Android) on one thread per core, with keep-alive connections and pipelining. Set TERN_HTTP_THREADS to choose the number of threads. A handler may itself use parallel blocks. A handler runs on the event loop's thread, so it shouldn't wait on tasks or channels; use the engine for that.

Limits and timeouts

LimitDefaultWhat happensChange with
Request body size16 MB413 Payload Too Large, connection closedTERN_HTTP_MAX_BODY_MB
Request line and headers64 KB400 Bad Request, connection closed
Idle keep-alive connection60 sconnection closedTERN_HTTP_IDLE_SEC
Slow client (a request started but not finished)10 sconnection closedTERN_HTTP_HEADER_SEC

Malformed requests get 400 Bad Request. The environment variables are read when serve starts, e.g. TERN_HTTP_MAX_BODY_MB=64 ./app.

Not supported by serve: TLS (put a proxy such as Caddy or nginx in front, or use the engine's listen_tls), HTTP/2, request bodies sent with chunked transfer encoding (the body must have a Content-Length), and streaming responses (the whole body is built, then sent). The engine has all of these but HTTP/2.

Errors in handlers

A runtime error inside a handler (an index out of range, a missing map key, a division by zero, a failed SQL statement) doesn't stop the server. That request is answered with 500 internal server error, a line is logged to standard error, and the server carries on:

tern: GET /crash failed: runtime error in handle (hello.tn:6): index 5 out of bounds (length 1)

With serve(port, handle, &app), changes a failing handler made to app before the error are kept, so update app at the end of the handler, after the checks that can fail.

The servers and the client are not available on WebAssembly (a compile error). The request and response functions work everywhere, so request-handling code can be tested anywhere.

A complete example

A guestbook: an HTML form, a form-encoded POST, a JSON API, and state shared between requests with mut:

Compiles (not run here)
import http
import json

struct Entry:
    name: str
    message: str

struct Book:
    entries: [Entry]

fn escape(s: str) str:
    return s.replace("&", "&amp;").replace("<", "&lt;").replace(">", "&gt;").replace(`"`, "&quot;")

fn page(b: Book) http.Response:
    out = `<h1>Guestbook</h1><form method="post" action="/sign">`
    out += `<input name="name"> <input name="message"> <button>Sign</button></form><ul>`
    for e in b.entries:
        out += "<li><b>" + escape(e.name) + "</b>: " + escape(e.message) + "</li>"
    return http.html(out + "</ul>")

fn sign(req: http.Request, b: mut Book) http.Response:
    name = req.form("name").trim()
    message = req.form("message").trim()
    if name == "" or message == "" or len(message) > 500:
        return http.status(400, "name and message (up to 500 bytes) are required")
    b.entries.push(Entry(name, message))
    return http.redirect("/")

fn handle(req: http.Request, b: mut Book) http.Response:
    params: {str: str} = {}
    if req.method == "GET" and req.path == "/":
        return page(b)
    if req.method == "POST" and req.path == "/sign":
        return sign(req, &b)
    if req.method == "GET" and req.path == "/api/entries":
        return http.json(json.encode(b.entries))
    if req.method == "GET" and http.match(req.path, "/api/entries/{n}", &params):
        n = params["n"].to_int(-1)
        if n < 0 or n >= len(b.entries):
            return http.status(404, f"no entry {params["n"]}")
        return http.json(json.encode(b.entries[n]))
    return http.not_found()

fn main():
    book = Book([Entry("tern", "first!")])
    http.serve(8080, handle, &book)
curl -d 'name=Ada&message=Hello+there' localhost:8080/sign     # 302 back to /
curl localhost:8080/api/entries          # [{"name":"tern","message":"first!"},{"name":"Ada","message":"Hello there"}]
curl localhost:8080/api/entries/5        # 404: no entry 5

For a database-backed server, see the example at the end of sqlite.

The engine

fn new_server() Server
fn add_route(s: Server, method: str, pattern: str, h: fn(Request) Response,
             ws: fn(Request, Socket), sse: fn(Request, Stream), stream: bool)
fn no_ws(req: Request, ws: Socket)          the ws argument of a route without one
fn no_sse(req: Request, out: Stream)        the sse argument of a route without one
fn limit_connections(s: Server, n: int)
fn listen(s: mut Server, host: str, port: int, fallback: fn(Request) Response)
fn listen_tls(s: mut Server, host: str, port: int, fallback: fn(Request) Response, cert: str, key: str)
fn wait(s: Server)
fn stop(s: Server)

The engine runs each connection as a task on the task runtime (every core), so a handler may wait (sleep, channels, the client below, a database) without holding up other requests. Handlers are closures fn(http.Request) http.Response, so they can capture the state they need (a task.shared value for state that changes). A runtime error in a handler answers 500 and the server keeps running.

s.add_route(method, pattern, h, ws, sse, stream) registers a route; method "*" matches every method. Patterns: "/users/{id}" (one segment, read with req.param("id")), "/files/{*rest}" (the rest of the path); static segments win over {params}, which win over {*wildcards}. s.listen(host, port, fallback) starts serving in the background: host "" is every interface, port 0 picks a free one (then s.port says which), and fallback answers requests no route matches. s.wait() blocks until SIGINT or SIGTERM, then stops accepting and lets requests in progress finish (up to TERN_WEB_DRAIN_SEC, 10 s); s.stop() closes the server and waits for its handlers. s.limit_connections(n) (or TERN_WEB_MAX_CONNS) caps the connections open at once; past it, new clients wait in the kernel's queue. listen_tls serves HTTPS with a PEM certificate chain and key; it needs import tls.

import http

fn hello(req: http.Request) http.Response:
    return http.text("hello " + req.param("name"))

fn missing(req: http.Request) http.Response:
    return http.status(404, "no route for " + req.path)

fn main():
    s = http.new_server()
    s.add_route("GET", "/hello/{name}", hello, http.no_ws, http.no_sse, false)
    s.add_route("POST", "/echo", fn(req) http.text(req.body), http.no_ws, http.no_sse, false)
    s.listen("127.0.0.1", 0, missing)
    base = f"http://127.0.0.1:{s.port}"
    print(http.get(base + "/hello/ada").body)
    print(http.post(base + "/echo", "ping", "text/plain").body)
    res = http.get(base + "/nope")
    print(res.status, res.body)
    s.stop()
Output
hello ada
ping
404 no route for /nope

A framework adds the rest: roost has a router with r.get(path, h), nested routers, middleware layers, 405 answers with Allow, validation and metrics pages, all in Tern on these functions. Environment: TERN_ASYNC_THREADS (worker threads), TERN_WEB_IDLE_SEC (60), TERN_WEB_HEADER_SEC (10), TERN_WEB_MAX_BODY_MB (16), TERN_WEB_WS_MAX_MB (16).

WebSockets and server-sent events

fn ws_upgrade(req: Request) Response        accept a WebSocket (the route's ws handler runs next)
fn sse_open(req: Request) Response          open an event stream (the route's sse handler runs next)
ws.next(&msg) bool   ws.recv() str   ws.is_binary() bool   ws.is_open() bool   ws.close()
ws.send(text) bool   ws.send_binary(data) bool   ws.ping(data) bool     (false: the client is gone)
out.send(data) bool   out.event(name, data) bool   out.comment(text) bool
out.forward(ch) bool                        every message of a chan[str] as an event, until it closes
fn ws_connect(url: str) Socket              a client ("ws://host:port/path", "wss://" over TLS): ws.ok(), http.error()
fn ws_connect_with(url: str, headers: str) Socket

A WebSocket route answers the handshake with http.ws_upgrade and names its socket handler, which then has the connection to itself; an event-stream route does the same with http.sse_open. Pings are answered and fragmented messages put together for you. wss:// URLs connect over TLS (default port 443) with SNI and certificate verification, like https://, and need import tls in the program; without it ws_connect fails with "wss:// needs import tls". The Host header carries the URL's host and port, and the handshake accepts what CDNs add (extra headers, Connection: upgrade in any case). out.forward(ch) notices a client that went away within a second, even when ch is quiet, and sends messages that are already waiting in one write.

Compiles (not run here)
import http
import task

fn echo(req: http.Request, ws: http.Socket):
    msg = ""
    while ws.next(&msg):
        ws.send("echo: " + msg)

fn ticks(req: http.Request, out: http.Stream):
    for i in 0..3:
        if not out.event("tick", str(i)):
            return
        task.sleep(1000)

fn main():
    s = http.new_server()
    s.add_route("GET", "/ws", http.ws_upgrade, echo, http.no_sse, false)
    s.add_route("GET", "/ticks", http.sse_open, http.no_ws, ticks, false)
    s.add_route("GET", "/assets/{*path}", fn(req) http.static_file("./public", req.param("path"), req), http.no_ws, http.no_sse, false)
    s.listen("", 8080, fn(req) http.not_found())
    s.wait()

Streamed bodies and files

fn read_body(req: Request, max: int) str            the next piece ("" at the end)
fn save_body(req: Request, path: str) int           the rest into a file: bytes, or -1 (http.error())
fn next_part(req: Request, p: mut Part) bool        multipart: the next part (its data is "")
fn read_part(req: Request, max: int) str
fn save_part(req: Request, path: str) int
fn static_file(dir: str, rel: str, req: Request) Response
fn file_response(path: str, req: Request) Response

A route added with stream set to true runs its handler as soon as the headers arrive, with req.body empty; the handler reads the body itself, a piece at a time, in constant memory and without the body size limit (Content-Length and chunked bodies both work).

http.static_file(dir, rel, req) answers with the file rel under dir: the content type from the extension, ETag and Last-Modified with 304 answers, single byte ranges (206), and big files streamed from disk. Paths with .., and dot files other than .well-known, are 404; a directory serves its index.html. http.file_response(path, req) sends one file (relative to the working directory) with the same headers.

The client

fn get(url: str) Response
fn post(url: str, body: str, content_type: str) Response
fn fetch(cr: ClientRequest) Response
fn request(method: str, url: str) ClientRequest     a 30 s timeout, follows 5 redirects
fn try_get(url: str) Result[Response, str]
fn try_fetch(cr: ClientRequest) Result[Response, str]
fn failed(res: Response) bool                       no response at all (status 0; body says why)
fn url_encode(s: str) str

struct ClientRequest:
    method: str
    url: str
    headers: str                # "Name: value\r\n" lines (see header_line)
    body: str
    timeout_ms: int
    redirects: int              # how many redirects to follow

An HTTP/1.1 client for tasks: a request waits without blocking its thread, and keep-alive connections are pooled per host and shared by all tasks. https:// URLs need import tls (certificates are verified; see tls). A request that gets no response at all returns status 0 with the reason in body; try_get and try_fetch make that an Err, while 4xx and 5xx responses are Ok.

import http

fn main():
    cr = http.request("POST", "http://127.0.0.1:1/api/items")
    cr.headers = http.header_line("Content-Type", "application/json") + http.header_line("Authorization", "Bearer t0k3n")
    cr.body = `{"name": "tea"}`
    cr.timeout_ms = 2000
    res = http.fetch(cr)
    if http.failed(res):
        print("no response:", res.body)
    match http.try_get("http://127.0.0.1:1/"):
        Ok(r):
            print(r.status)
        Err(e):
            print(e)
    print(http.url_encode("a b&c"))
Output
no response: connect: Connection refused
http: request failed: connect: Connection refused
a%20b%26c

For middleware

fn peer(req: Request) str               "1.2.3.4:5678", the connection's address
fn client_ip(req: Request) str          the client's IP (see trust_proxies)
fn trust_proxies(n: int)                behind n proxies: client_ip reads X-Forwarded-For
fn matched_route(req: Request) str      the route's pattern, once track_routes() was called
fn track_routes()
fn now_us() int                         a monotonic clock, microseconds
fn log(line: str)                       one line to stderr, buffered (an access log's writer)
fn limiter(per_second: float, burst: int) Limiter
fn consume(l: Limiter, key: str) float  0.0, or (no tokens left) the seconds to wait
fn request_id() str                     a random (version 4) UUID
fn secure_equal(a: str, b: str) bool    a == b in constant time (for secrets)
fn gzip(data: str) str                  gzip-compressed ("" if it can't)
fn enable_metrics()                     count requests from now on (every engine server)
fn metrics_text() str                   Prometheus text format
fn metric_add(name: str, labels: str, v: float)      a counter of your own
fn metric_set(name: str, labels: str, v: float)      a gauge of your own

These are what roost's middleware (logging, rate limits, request ids, bearer tokens, gzip, metrics) is made of. A limiter holds a token bucket per key (a client IP, an API key), refilled at per_second up to burst, shared by every thread; idle buckets are forgotten. client_ip is the connection's address unless trust_proxies(n) was called: then it takes the X-Forwarded-For entry the n proxies in front of the server added, counting from the right (entries further left were written by the client).

import http

fn main():
    lim = http.limiter(1.0, 2)
    print(lim.consume("10.0.0.1"), lim.consume("10.0.0.1"), lim.consume("10.0.0.1") > 0.0)
    print(len(http.request_id()), http.secure_equal("t0k3n", "t0k3n"), http.secure_equal("t0k3n", "guess"))
Output
0.0 0.0 true
36 true false
Source: docs/std/http.md. Every example on this page is compiled and run by tern x test docs.