HTTP server

A native, production HTTP server — no framework to add (async hyper/tokio). Everything is deny-by-default, so a server needs require serve(port).

-- Doc example: the serve response contract. Helpers return {status, value}; the
-- runtime renders them. (A real `serve on` block doesn't terminate, so the doctest
-- asserts the response shapes the handlers give — see the prose for a full server.)
intent: "doc example: serve response contract"

print("ok → " + text(status of ok({"a": 1})) + ",  fail(400) → " + text(status of fail(400, "bad")))

test "uniform response helpers carry a status + value"
    assert_eq(status of ok({"a": 1}), 200)
    assert_eq(status of created({"id": 1}), 201)
    assert_eq(status of fail(400, "bad input"), 400)
    assert_eq(status of not_found("missing"), 404)
    assert_eq((value of fail(400, "bad input"))["error"], "bad input")

Routes & params

require serve(8080)

serve on 8080
    route "GET /products"
        give sql("SELECT id, name, price FROM products")
    route "GET /products/:id"
        give sql("SELECT * FROM products WHERE id = ?", [params.id])
    route "GET /files/*path"            -- catch-all (variable depth)
        give read_file(params.path)

Routes match by specificity (exact > :param > *catchall), not declaration order.

Auth & validation

serve on 8080
    auth with check_token
    route "POST /products" requires auth
        expect body {name: text, price: number}    -- 400 if it doesn't match
        give created(json of request)

The auth task receives the bearer token; declare it with 2 parameters (task check(token, request)) and it also receives the request map — that's what unlocks cookie sessions (Login & sessions).

The request & responses

request has .method .path .body .json .headers .cookies .query .params .user .ip .body_file (.cookies — engine v0.5.5+). .headers, .query and .params are maps — index by key (request.headers["authorization"]; header names are lowercased). Indexing a missing key errors, so guard optional ones with contains(request.headers, "x"). query and params are also bound as bare locals, so params.id works directly. When a large body spills to disk (over ~1 MiB), .body is empty and .body_file is a temp-file path — read it with read_body() / read_body_bytes().

Handler scope: request, query and params live only in the handler's own scope — a task the handler calls does not see them. Pass what the task needs as an argument (e.g. lookup_user(request)), never a bare request referenced inside that task.

Responses use the uniform helpers — ok(x), created(x), fail(code, msg), not_found(msg), respond(text, content_type), redirect(url) — or give a value directly. Any of them can carry extra headers or cookies: with_header(resp, name, value) / set_cookie(resp, name, value, opts?) — see Login & sessions.

Built in

• Pagination: give paged("SELECT … ORDER BY id") — LIMIT/OFFSET pushdown + exact COUNT(*).
• SSE: a stream block with send for server-sent events — an LLM can stream into it token by token with llm_stream.
• Rate limiting: rate_limit N per window.
• Static files: static "/assets" from "./static" (ETag/Range/gzip). Declared routes win over static — from a declared route, serve a binary asset with binary(read_file_bytes(p), "image/png") (plain read_file is UTF-8-lossy). More in Frontend.
• CORS: cors "*". Negotiation: content() serves HTML/Markdown/JSON from one source.
• TLS / automatic HTTPS via CLI flags (--domain … --tls-auto); HTTP/2, vhosts, reverse proxy.
• Observability: log/print reach the terminal with a [serve] prefix.

See Frontend for HTML pages.