Skip to content

HTTP

std::http sends HTTP requests and responds to them. http.get fetches a URL and returns a Response with its whole body read, http.post sends a body, and http.fetch sends a Request you build. A status is not an error: a 404 is a Response like a 200, and Status.is_success says which it is. An Err means no response arrived, such as a refused connection or a timeout:

import
    std::http.{self, Response, Status}
    std::http::testing
    std::url.Url
end

fn greeting(name: String) -> Result<String, http.Error>
    response = http.get(Url"https://api.example.com/greet/${name}")?
    if not Status.is_success(response.status) then return Ok("no greeting: ${response.status}")
    Response.text(response)
end

fn main()
    ran = testing.run(fn request ->
        Ok(Response{body: .Text("hello from ${request.url.path}")})
    end, fn ->
        greeting("ann b")
    end)

    dbg ran.value
end

The page cannot reach the network, so main runs greeting under std::http::testing, which responds to each request with a function instead, as a test does. Url"..." is a checked literal: it is a Url, not a Result, and it escapes each ${...} for where it stands. ann b goes out as the path segment ann%20b, and the handler’s request.url.path reads it back decoded. A request runs under the context in force, so a deadline or a cancelled task stops it.

A handler is a plain function from a Request to a Response. A Router picks the handler for each request by a Route, a method and a path pattern. A route’s type says what its wildcards hold: Route<{id: Uuid}> for GET /posts/{id}, and a plain Route (Route<Unit>) for a route with none. Route.to_with hands the handler the parameters, each wildcard parsed into its field’s type, and Route.to takes a route with none. A request whose wildcard does not parse gets a 404, as one no route matches does, and one that matches only under another method gets a 405. Route.path_with fills the parameters into a link. Since a handler is a function, a test calls it, or the router, with a request and no network:

import
    std::http.{Request, Response, Route, Router}
    std::http::testing
end

fn show(Request, user: {id: Int}) -> Response
    Response{body: .Text("user ${user.id}")}
end

fn main()
    user: Route<{id: Int}> = "GET /users/{id}"
    router = Router.new([Route.to_with(user, show)])!
    found = Router.serve(router, testing.request(.Get, "/users/7"))
    dbg Response.text(found)
    dbg Router.serve(router, testing.request(.Get, "/users/ann")).status
    dbg "${Route.path_with(user, {id: 8})}"
end

A route literal written as an argument takes its parameters from the handler beside it: with the show above, Route.to_with("GET /users/{id}", show) is a Route<{id: Int}>, and so is "GET /users/{id}" |> Route.to_with(show). With nothing to say what its parameters are, such as a lambda handler that states no types, a route literal has a String field per wildcard: Route"GET /users/{id}" is a Route<{id: String}>. Request.path_value reads a wildcard’s text from the request too. A query parameter is not part of the route: Url.query_values(request.url) |> Query.get("page") returns the first page of /posts?page=2 as a Maybe<String>.

std::http::testing.form_request(.Post, "/signup", [("email", "ada@example.com")]) builds a request that posts a form, as Frontends does. An HTML form sends only GET and POST, so Router.handler(router) |> http.method_override() routes a posted form with a _method field of PUT, PATCH or DELETE as that method.

A route literal is checked when the program is checked. A malformed pattern is a compile error at the literal, and so is a wildcard that is not one of the parameters’ fields, a method other than the standard ones in capitals, such as GETX (Route.with_method routes WebDAV’s PROPFIND and the like), and a brace outside a wildcard that is a whole segment, such as /token}:

import std::http.Route

fn main()
    post: Route<{post_id: Int}> = "GET /posts/{id}"
    dbg post
end

Router.new still returns an Err for two routes that match the same requests, since each literal sees only its own pattern. Route.parse checks a pattern built at run time.

A handler responds with a page through Response.html, which takes an Html. Write one with an Html"..." literal, an HTML template the compiler checks. Each ${...} is escaped for where it stands, so the <nobody> below arrives as text, and an unclosed tag or a slot in a <script> is a compile error. A one-line fragment quotes its attributes with ', since a " would end the literal. Markup of several lines goes in triple quotes:

import
    std::html.Html
    std::http.{Request, Response}
    std::http::testing
end

fn badge(count: Int) -> Html
    Html"<span class='badge'>${count}</span>"
end

fn profile(request: Request) -> Response
    name = Request.path_value(request, "name") |> Maybe.with_default("<nobody>")

    page = Html"""
        <main>
          <h1>${name} ${badge(3)}</h1>
        </main>
        """

    Response.html(page)
end

fn main()
    dbg Response.text(profile(testing.request(.Get, "/")))
end

A slot shows a Maybe’s value or nothing, so ${if unread > 0 then Some(Html"<b>${unread} new</b>") else None} shows its part only when the condition holds. Inside a quoted attribute value it adds its text or nothing, as in class='tab ${if active then Some("active") else None}'. An unquoted class=${if active then Some("active") else None} writes the attribute or leaves it out. What a slot in an attribute, a URL or a style takes is in the spec’s HTML templates.

A handler may return any value whose type implements ToResponse: a Response, an Html page, or a Result of two such types. A lambda handler that only ever returns Ok(...) names no error type, and the one it leaves open is Infallible, the type with no values. The handler’s type, (Request) -> ToResponse, is named http.Handler, which Router.new, http.serve and middleware such as http.limit_body take. So a handler with several steps that can fail returns a Result and passes each failure up with ?, and the app’s error enum says what response each failure gets. One route list holds both kinds of handler:

import
    std::html.Html
    std::http.{Request, Response, Route, Router, Status, ToResponse}
    std::http::testing
    std::log.{self, Logger}
end

once logger = Logger.text()

enum AppError
    NotFound
    BadInput {reason: String}
    Internal {reason: String}
end

impl ToResponse for AppError
    fn to_response(error: AppError) -> Response
        case error
            .NotFound ->
                Response.not_found()

            .BadInput{reason:} ->
                Response.error(Status.bad_request, reason)

            .Internal{reason:} ->
                log.error(logger, reason)
                Response.error(Status.internal_server_error, "something went wrong")
        end
    end
end

fn find_user(id: Int) -> Result<String, AppError>
    if id == 7 then
        Ok("Ada")
    else
        Err(AppError.NotFound)
    end
end

fn show(Request, user: {id: Int}) -> Result<Html, AppError>
    name = find_user(user.id)?
    Ok(Html"<h1>${name}</h1>")
end

fn rename(request: Request, user: {id: Int}) -> Result<Html, AppError>
    name = find_user(user.id)?

    renamed =
        Request.form_value(request, "name")
        |> Maybe.to_result(AppError.BadInput{reason: "the form has no name"})?

    Ok(Html"<h1>${name} is now ${renamed}</h1>")
end

fn health(Request) -> Response
    Response{body: .Text("ok")}
end

fn main()
    router = Router.new([
        Route.to("GET /health", health),
        Route.to_with("GET /users/{id}", show),
        Route.to_with("POST /users/{id}", rename),
    ])!

    get = fn target: String -> Router.serve(router, testing.request(.Get, target))
    dbg Response.text(get("/users/7"))
    dbg get("/users/8").status
    dbg Response.text(Router.serve(router, testing.form_request(.Post, "/users/7", [])))
end

http.listen binds the server’s address, and http.serve serves each request as a task of a supervisor, so its max_running bounds the requests served at once. Each handler runs under its request’s context, and its task stops if the client goes away. When the program shuts down, at a signal or when main returns, the server stops accepting at once, and the requests it already took finish within its shutdown_timeout:

import
    std::http.{self, Request, Response, Route, Router, Server}
    std::supervisors.Supervisor
end

struct App
    web: Supervisor
end

fn boot(Startup) -> Result<App, String>
    Ok(App{web: Supervisor.new(max_running: 256)})
end

fn show(Request, user: {id: String}) -> Response
    Response{body: .Text("user ${user.id}")}
end

fn main() -> Result<Unit, http.Error>
    router = Router.new([Route.to_with("GET /users/{id}", show)])?
    listener = http.listen(Server{address: ":8080"})?
    http.serve(listener, Router.handler(router), App.web)
    Ok(Unit)
end

The page cannot listen on a port, so this one does not run here. nomi run serves it on port 8080.

http.file_server(dir) serves a folder from the disk. http.file_server_embedded(files) serves files the program embeds, so a built server needs no folder beside it.

Frontends shows a React or Vue app served this way, with a Nomi JSON API behind it.

A handler that reads a posted form with Request.form reads at most 10 MB of it, and Request.multipart_form at most 32 MB; a larger body is Error.BodyTooLarge. Request.text reads a body as text and Request.json_as<T> decodes it as JSON into a T, under the 10 MB limit too. A body that is not JSON of that shape is Error.MalformedBody, and http.Error implements ToResponse, so a handler returning Result<Response, http.Error> turns it into a 400 through ?. Server{max_body: Some(n)} sets one limit for every request, and upload |> http.limit_body(n) one for a route, such as an upload route that needs more.

A JSON API handler decodes the body into a type that derives FromJson, and a body without a title gets a 400:

import
    std::http.{self, Request, Response, Status, ToResponse}
    std::http::testing
    std::json.{FromJson, ToJson}
end

struct NewTodo
    title: String
end

derive FromJson for NewTodo

struct Todo
    id:    Int
    title: String
end

derive ToJson for Todo

fn create_todo(request: Request) -> Result<Response, http.Error>
    input: NewTodo = Request.json_as(request)?
    todo = Todo{id: 1, title: input.title}
    Ok(Response.json(todo, status: Status.created))
end

test "a todo is created from its JSON"
    post = fn text: String -> {..testing.request(.Post, "/todos"), body: .Text(text)}

    created = ToResponse.to_response(create_todo(post(`{"title": "milk"}`)))
    assert created.status == Status.created
    assert Response.text(created) == Ok(`{"id":1,"title":"milk"}`)

    refused = ToResponse.to_response(create_todo(post(`{"name": "milk"}`)))
    assert refused.status == Status.bad_request
end

A middleware takes a handler first and returns a new handler that does something before or after it. Since a pipe passes its head as the first argument, a stack of middleware reads top to bottom, each stage wrapping the ones above it. http.wrap_routes wraps one group of routes, such as every /admin route, before they join the others. std::http has cors, log_requests, security_headers, request_id, limit_body, timeout, cross_origin_protection, compress, basic_auth and method_override; see the reference for their options. http.compress() gzips a response for a client that takes gzip. http.basic_auth("admin", check) returns 401, naming the realm admin, until the browser sends a user and password check accepts; compare them with hash.equal_in_constant_time, never ==, whose timing shows how much of a guess was right.

A middleware that finds a value for the handler, such as the signed-in user, takes a handler that accepts it, as require_user does below. There is no map of values on the request. The handler’s type says what it needs, so the compiler rejects a route that needs a user and is not wrapped by the middleware that finds one:

import
    std::http.{self, Cors, Handler, Headers, Origin, Request, Response, Route, Router, Status, ToResponse}
    std::http::testing
end

struct User
    name:  String
    admin: Bool
end

fn signed_in(request: Request) -> Maybe<User>
    case Headers.get(request.headers, "Authorization")
        Some("Bearer ada") -> Some(User{name: "Ada", admin: True})
        Some("Bearer bob") -> Some(User{name: "Bob", admin: False})
        _                  -> None
    end
end

fn require_user(handler: (Request, User) -> ToResponse) -> (Request) -> Response
    fn request ->
        case signed_in(request)
            Some(user) -> ToResponse.to_response(handler(request, user))
            None       -> Response.error(Status.unauthorized, "sign in first")
        end
    end
end

fn require_admin(handler: Handler) -> (Request) -> Response
    require_user(fn request, user ->
        if user.admin then
            ToResponse.to_response(handler(request))
        else
            Response.error(Status.forbidden, "admins only")
        end
    end)
end

fn dashboard(Request, user: User) -> Response
    Response{body: .Text("hello, ${user.name}")}
end

fn stats(Request) -> Response
    Response{body: .Text("42 users")}
end

fn main()
    admin = [Route.to("GET /admin/stats", stats)] |> http.wrap_routes(require_admin)
    routes = [Route.to("GET /dashboard", require_user(dashboard))] + admin
    router = Router.new(routes)!

    app =
        Router.handler(router)
        |> http.cors(Cors{origins: [Origin"https://app.example.com"]})
        |> http.security_headers()
        |> http.request_id()

    get = fn token: String, path: String ->
        request = testing.request(.Get, path)
        app({..request, headers: Headers[("Authorization", "Bearer ${token}")]})
    end

    dbg Response.text(get("bob", "/dashboard"))
    dbg get("bob", "/admin/stats").status
    dbg Response.text(get("ada", "/admin/stats"))
    dbg app(testing.request(.Get, "/dashboard")).status
    dbg Headers.get(get("ada", "/dashboard").headers, "X-Frame-Options")
end

log_requests(logger) writes one record per request with its method, path, status and time. Put it before request_id in the pipe, so it runs inside it and logs the id request_id gives the request.

std::sessions keeps a value of your own type across requests in one cookie, encrypted and authenticated with AES-256-GCM under a key derived from a secret the app holds. sessions.with_session(store) is middleware that hands the handler the session beside the request, as a Session<T>, so require_user can be built on it. A handler changes the session with Session.set or Session.clear and writes it onto its response with sessions.write; a response that writes nothing leaves the cookie alone. Session.add_flash leaves a message the next request reads once, in session.flash. A cookie that was changed or has expired reads as no session:

import
    std::html.Html
    std::http.{self, CrossOrigin, Headers, Request, Response, Route, Router, Status, ToResponse}
    std::http::testing
    std::json.{FromJson, ToJson}
    std::sessions.{self, CookieStore, Session, SessionKey}
end

struct Visit
    user: String
end

derive ToJson for Visit
derive FromJson for Visit

// A real app derives the key in boot, from a secret in its environment.
once store = CookieStore{key: SessionKey.derive("a secret of 32 bytes or more, kept out of git")!}

fn sign_in(request: Request, session: Session<Visit>) -> Response
    user = Request.form_value(request, "user") |> Maybe.with_default("")

    Response.redirect(request, "/dashboard", Status.see_other)
    |> sessions.write(Session.set(session, Visit{user:}))
end

fn sign_out(request: Request, session: Session<Visit>) -> Response
    Response.redirect(request, "/", Status.see_other) |> sessions.write(Session.clear(session))
end

fn require_user(handler: (Request, Visit) -> ToResponse) -> (Request) -> Response
    check = fn request: Request, session: Session<Visit> ->
        case session.value
            Some(visit) -> ToResponse.to_response(handler(request, visit))
            None        -> Response.redirect(request, "/sign-in", Status.see_other)
        end
    end

    check |> sessions.with_session(store)
end

fn dashboard(Request, visit: Visit) -> Html
    Html"<h1>Hello, ${visit.user}</h1>"
end

fn main()
    routes = [
        Route.to(
            "POST /sign-in",
            sign_in
            |> sessions.with_session(store),
        ),
        Route.to(
            "POST /sign-out",
            sign_out
            |> sessions.with_session(store),
        ),
        Route.to("GET /dashboard", require_user(dashboard)),
    ]

    app = Router.handler(Router.new(routes)!) |> http.cross_origin_protection(CrossOrigin{})
    signed_in = app(testing.form_request(.Post, "/sign-in", [("user", "Ada")]))
    cookie = List.first(Response.cookies(signed_in))!
    dbg Response.text(app(Request.add_cookie(testing.request(.Get, "/dashboard"), cookie)))
    dbg app(testing.request(.Get, "/dashboard")).status

    forged = {
        ..testing.form_request(.Post, "/sign-out", []),
        headers: Headers[("Sec-Fetch-Site", "cross-site")],
    }

    dbg app(Request.add_cookie(forged, cookie)).status
end

There is no CSRF token. cross_origin_protection refuses a POST, PUT, PATCH or DELETE that the browser says came from another origin, and the session cookie is SameSite=Lax, so a browser leaves it off a form another site posts. Keep GET routes free of changes, since neither check stops them.

The sign-in above takes any name. A real one checks a password against a hash stored with the user. std::passwords makes the hash, PBKDF2-SHA256 with a random salt, and checks it in constant time; the stored string records how it was made, so passwords.needs_rehash says when to store a new one at sign-in:

stored = passwords.hash(form.password)?

// at sign-in:
if passwords.verify(form.password, user.password_hash) == Ok(True) then ...

Argon2id and bcrypt are in the lib/password_hashers module. For an API whose clients send a bearer token instead of a cookie, std::jwt signs and checks JSON Web Tokens.

Uploaded files go in a Store, which keeps each file whole under a key. storage.local(root) keeps them in a directory, lib/storage/s3 in a bucket on any S3-protocol server, and std::storage::testing.Memory in memory for tests. Code that stores files takes a Store, so boot picks the backend and the rest of the code doesn’t change. Store.url returns where a file can be fetched, and storage.handler serves a store’s files through the app with their stored content type:

import
    std::http.{Headers, Route, Router}
    std::http::testing
    std::storage.{self, Store}
    std::storage::testing.Memory
    std::url.Url
end

fn save_avatar(store: Store, user: Int, image: Bytes) -> Result<Url, storage.Error>
    key = "avatars/${user}.png"
    Store.put(store, key, image, "image/png")?
    Store.url(store, key)
end

fn main()
    store = Memory.new(public_base: Url"/files/")
    dbg "${save_avatar(store, 7, String.to_bytes("png"))!}"

    files = storage.handler(store)
    router = Router.new([Route.to_with("GET /files/{key...}", fn r, _ -> files(r))])!
    response = Router.serve(router, testing.request(.Get, "/files/avatars/7.png"))
    dbg Headers.get(response.headers, "Content-Type")
end

A key is segments separated by /. A segment may hold spaces, punctuation and letters of any script, but not a control character or a \, and it may not start with a dot. So a key taken from a request cannot reach outside a local store’s directory.

Store.list(store, ListOptions{prefix: "avatars/", delimiter: "/"}) returns a page of the keys under a prefix, in order, with the deeper keys folded into their common prefixes, and storage.list_all follows the pages to the end.

A WebSocket keeps one connection open, and either end sends messages on it whenever it likes. A handler accepts one with websocket.accept, which returns the 101 Switching Protocols response and then runs its function over the connection, on the request’s task, until the function returns. WebSocket.receive returns Ok(None) once the client has closed, and any task may call WebSocket.send, so an actor can hold a room’s connections and broadcast to them:

import
    std::actors.Actor
    std::http.{self, Request, Response, Server}
    std::supervisors.Supervisor
    std::websocket.{self, WebSocket}
end

enum Room
    Join WebSocket
    Leave Int
    Say String
end

struct App
    web:  Supervisor
    room: Actor<Room>
end

fn boot(Startup) -> Result<App, String>
    web = Supervisor.new(max_running: 256)

    room = Actor.start(web, {}, fn members: Map<Int, WebSocket>, message: Room ->
        case message
            .Join(ws) ->
                Map.put(members, WebSocket.id(ws), ws)

            .Leave(id) ->
                Map.remove(members, id)

            .Say(text) ->
                Iter.each(Map.values(members), fn ws ->
                    _ = WebSocket.send_text(ws, text)
                end)

                members
        end
    end)

    Ok(App{web:, room:})
end

fn chat(request: Request) -> Response
    websocket.accept(request, fn ws ->
        _ = Actor.cast(App.room, .Join(ws))

        _ = WebSocket.each(ws, fn message ->
            if .Text(text) = message then
                _ = Actor.cast(App.room, .Say(text))
            end
        end)

        _ = Actor.cast(App.room, .Leave(WebSocket.id(ws)))
    end)
end

fn main() -> Result<Unit, http.Error>
    listener = http.listen(Server{address: ":8080"})?
    http.serve(listener, chat, App.web)
    Ok(Unit)
end

accept refuses a page from another origin with 403 unless AcceptOptions.allowed_origins lists it, and closes a connection whose message is over max_message_size, 1 MiB unless set. A client connects with websocket.connect(Url"wss://example.com/chat"). A test hands a handler a connection in memory with std::http::testing.open_websocket:

import
    std::http.{Request, Response}
    std::http::testing
    std::websocket.{self, Message, WebSocket}
end

fn shout(request: Request) -> Response
    websocket.accept(request, fn ws ->
        _ = WebSocket.each(ws, fn message ->
            if .Text(text) = message then
                _ = WebSocket.send_text(ws, String.uppercase(text))
            end
        end)
    end)
end

test "the server shouts back"
    heard = testing.open_websocket(shout, "/", fn ws ->
        _ = WebSocket.send_text(ws, "hello")
        WebSocket.receive(ws)
    end)

    assert Ok(reply) = heard
    assert reply == Ok(Some(Message.Text("HELLO")))
end

Middleware sees the 101 response when the handler returns it, so log_requests logs the handshake, timeout does not stop the connection after it, and compress leaves it alone. Server.request_timeout is a deadline for the request’s whole task, so leave it unset on a server with WebSockets.

A test that needs a real connection, for a client’s redirects, cookies or timeouts, runs a server with std::http::testing.with_server. It serves a handler on a free port of 127.0.0.1 while its body runs, then shuts down:

import
    std::http.{Client, Request, Response}
    std::http::testing
end

fn hello(Request) -> Response
    Response{body: .Text("hi")}
end

test "a client reaches the server"
    said = testing.with_server(hello, fn server ->
        Client.get(server.client, server.url) |> Result.map(Response.text)
    end)

    assert said == Ok(Ok("hi"))
end

Server{address: ":8443", tls: Some(ServerConfig{certificates: [certificate]})} serves HTTPS, with a tls.Certificate loaded from PEM files. with_server(handler, tls: True, ...) makes a certificate for the test, and server.client trusts it.

Frontends is next. It shows the ways to build the pages of a Nomi web app.