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.
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 threadsThe 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)pathis the part of the URL before?, exactly as the client sent it: it is not URL-decoded (/a%20bstays/a%20b).http.matchand route parameters decode what they capture.raw_queryis the part after?, also raw, or""if there is none. Read values withreq.query(name).headholds the header lines as the client sent them. Read them withreq.header(name), which ignores case.bodyis 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) RequestCall 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())/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)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
409match
fn match(path: str, pattern: str, params: mut {str: str}) boolRouting 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)true {"id": "42", "post": "7"}
true {"name": "my notes.txt"}
false {"name": "my notes.txt"}
true {"id": ""}
true {}
1001match 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.ResponseListens 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:
| Form | The handler gets | Requests run |
|---|---|---|
serve(port, handle) | nothing but the request | fully in parallel |
serve(port, handle, app) | app: App, read-only, shared by all threads | fully in parallel |
serve(port, handle, &app) | app: mut App, which it may change | one 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:
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)12: error: `handle` changes the app state, so pass it with `&`; requests then run one at a timeWith 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
| Limit | Default | What happens | Change with |
|---|---|---|---|
| Request body size | 16 MB | 413 Payload Too Large, connection closed | TERN_HTTP_MAX_BODY_MB |
| Request line and headers | 64 KB | 400 Bad Request, connection closed | |
| Idle keep-alive connection | 60 s | connection closed | TERN_HTTP_IDLE_SEC |
| Slow client (a request started but not finished) | 10 s | connection closed | TERN_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:
import http
import json
struct Entry:
name: str
message: str
struct Book:
entries: [Entry]
fn escape(s: str) str:
return s.replace("&", "&").replace("<", "<").replace(">", ">").replace(`"`, """)
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}", ¶ms):
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 5For 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()hello ada
ping
404 no route for /nopeA 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) SocketA 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.
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) ResponseA 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 followAn 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"))no response: connect: Connection refused
http: request failed: connect: Connection refused
a%20b%26cFor 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 ownThese 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"))0.0 0.0 true
36 true false