HTTP
Making requests
Section titled “Making requests”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
enddbg line 20: ran.value = Ok("hello from /greet/ann b")
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.
Handlers and routes
Section titled “Handlers and routes”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})}"
enddbg line 14: Response.text(found) = Ok("user 7")
dbg line 15: Router.serve(router, testing.request(.Get, "/users/ann")).status = Status(404)
dbg line 16: "${Route.path_with(user, {id: 8})}" = "/users/8"
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
endmain.nomi:4:47: `Route` literal "GET /posts/{id}" is invalid: the pattern has `{id}`, but `{post_id: Int}` has no field `id`
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, "/")))
enddbg line 24: Response.text(profile(testing.request(.Get, "/"))) = Ok("<main>\n <h1><nobody> <span class='badge'>3</span></h1>\n</main>")
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", [])))
enddbg line 67: Response.text(get("/users/7")) = Ok("<h1>Ada</h1>")
dbg line 68: get("/users/8").status = Status(404)
dbg line 69: Response.text(Router.serve(router, testing.form_request(.Post, "/users/7", []))) = Ok("the form has no name\n")
Serving
Section titled “Serving”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.
Request bodies
Section titled “Request bodies”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
endok a todo is created from its JSON
test result: ok. 1 passed, 0 failed
Middleware
Section titled “Middleware”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")
enddbg line 62: Response.text(get("bob", "/dashboard")) = Ok("hello, Bob")
dbg line 63: get("bob", "/admin/stats").status = Status(403)
dbg line 64: Response.text(get("ada", "/admin/stats")) = Ok("42 users")
dbg line 65: app(testing.request(.Get, "/dashboard")).status = Status(401)
dbg line 66: Headers.get(get("ada", "/dashboard").headers, "X-Frame-Options") = Some("DENY")
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.
Sessions
Section titled “Sessions”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
enddbg line 63: Response.text(app(Request.add_cookie(testing.request(.Get, "/dashboard"), cookie))) = Ok("<h1>Hello, Ada</h1>")
dbg line 64: app(testing.request(.Get, "/dashboard")).status = Status(303)
dbg line 71: app(Request.add_cookie(forged, cookie)).status = Status(403)
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.
Storing files
Section titled “Storing files”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")
enddbg line 17: "${save_avatar(store, 7, String.to_bytes("png"))!}" = "/files/avatars/7.png"
dbg line 22: Headers.get(response.headers, "Content-Type") = Some("image/png")
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.
WebSockets
Section titled “WebSockets”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")))
endok the server shouts back
test result: ok. 1 passed, 0 failed
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.
Testing against a real server
Section titled “Testing against a real server”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.