http
An HTTP/1.1 client and server built on core net. The client uses net.tcp for http:// and net.tls for https://. It makes one request per connection, follows up to 5 redirects, and reads Content-Length, chunked and read-until-close bodies. The server (http.server) runs on net.listen: it serves one connection at a time, handles one request per connection, and routes with Auk's clause patterns.
Effects: net. Dependencies: json and url (which brings in encoding); none of them use effects. To call json.* yourself, as below, add it as a direct dependency too: raft add json.
Client
fn main(): int! uses net {
let r = await http.get("https://api.example.com/users/1")?
if r.status != 200 { fail("status {r.status}") }
let user = r.json()?
print("{r.header("content-type") else "?"}: {json.str(user)}")
let made = await http.post_json("https://api.example.com/users", Map({"name": Str("ann")}))?
print("created: {made.status}")
0
}
struct Resp { status: int, headers: {str: str}, body: str }: header names are lower-case; repeated headers are joined with", ".struct Req { method: str, url: str, headers: {str: str}, body: str }enum HttpErr { BadUrl(why), BadRequest(why), BadResponse(why), TooManyRedirects(url) }: errors from corenetpass through as they are.async fn request(r: Req): Resp! uses net: sendsrand follows 301/302/303/307/308 up to 5 times. A 303 becomes GET with no body.AuthorizationandCookieare dropped when a redirect leaves the origin.async fn get(to: str): Resp! uses netasync fn post(to: str, body: str): Resp! uses net: sendsContent-Type: text/plain; charset=utf-8.async fn post_json(to: str, v: Value): Resp! uses net: sendsContent-Type: application/json.fn json(r: Resp): Value!: parses the body (r.json()).fn header(r: Resp, name: str): str?: looks up a header, ignoring case (r.header("Content-Type")).
Every request sends Host, User-Agent: auk-http/0.1 and Connection: close. It also sends Content-Length when there is a body or the method is POST, PUT or PATCH. You can override Host and User-Agent. Any framing headers you set are ignored. Header values containing CR or LF are rejected.
URLs are strict RFC 3986 (via url)
URL parsing and redirect resolution use the url package: http.uri.parse is url.parse plus an http/https check, and redirects resolve with url.resolve. Build query strings with url.build_query or url.with_params. The rules:
- Some characters must be percent-encoded. Raw non-ASCII, spaces, control characters and
"<>\^`{|}in a URL are aBadUrlerror, so encode them first, for example"https://a.com/" + encoding.percent_encode("café"). http 0.1 used to send non-ASCII and"<>{}|through unchanged. - A
%must be followed by two hex digits. - The scheme is case-insensitive (
HTTP://a.comworks). - Dot segments in a redirect
Locationare removed exactly as RFC 3986 §5.2 says. - URLs with credentials (
user:pw@host) and port 0 are rejected.
Server
struct Todo { title: str, done: bool }
fn route("GET", "/", _: http.server.Req): http.Resp = http.server.text(200, "hello from auk\n")
fn route("GET", "/hello/" + name, r: http.server.Req): http.Resp {
let greeting = r.param("greeting") else "hi"
http.server.text(200, "{greeting}, {name}!\n")
}
fn route("POST", "/todos", r: http.server.Req): http.Resp = match r.decode() {
ok(Todo { title, done }) => http.server.reply(201, Todo { title, done })
err(e) => http.server.text(400, "{e}\n")
}
fn route(_: str, _: str, _: http.server.Req): http.Resp = http.server.not_found()
fn main(args: [str]): ()! uses net {
let port = if args.len() > 1 { int.parse(args[1])? } else { 8080 }
var s = http.server.listen("127.0.0.1", port)?
eprint("listening on http://127.0.0.1:{s.port()}")
await http.server.serve(s, http.server.router(route))?
}
To try it, run raft new demo, set effects = ["net"], run raft add http, put the code above in src/main.auk, and start it with auk run src/main.auk. Then:
$ curl "localhost:8080/hello/ann?greeting=hey+there"
hey there, ann!
$ curl -d '{"title":"x","done":true}' localhost:8080/todos
{"done":true,"title":"x"}
API (http.server)
struct Req { method, target, path, query, headers: {str: str}, body }:targetis the origin form (/a/b?x=1, or*), andpathandqueryare its two halves, still percent-encoded (queryis""when there is no?). Header names are lower-case, and repeated headers are joined with", ". An absolute-form target (http://h/p) arrives as/p.struct Server,listen(host, port): Server! uses net(""means every interface; port 0 picks a free port),port(s): int,close(var s).async fn serve(host, port, handler: (Req) => http.Resp): ()!andserve(s: Server, handler)run forever. They return only ifacceptfails.async fn serve_live(host, port, handler: (Req) => Reply): ()!andserve_live(s: Server, handler)give each connection a task of its own, with at mostMAX_CONNS(256) at once. A slow client or a long stream holds up nobody else, and a handler that panics only drops its own connection.serve_live_n(s, n, handler)servesnconnections and then waits for them, for tests.enum Reply { Whole(resp: http.Resp), Stream(status, headers, chunks: Chan<str>) }is what aserve_livehandler returns. A stream sends its head (no length), then each string sent onchunksas it arrives, untilchunksis closed. If the client goes away, the server closeschunks, so a sender can tell: its nextsendpanics. That's what Server-Sent Events need (content-type: text/event-stream, messages like"data: hi\n\n").async fn serve_n(host, port, n, handler)andserve_n(s: Server, n, handler)servenconnections and then return; the first form also closes its listener. These are meant for tests. Run the server and a client together withawait (serve_n(s, 1, h), http.get(u)).- Responses:
text(status, body),html(status, body),reply<T: Data>(status, x)(a JSON body),redirect(status, location)andnot_found(). Anyhttp.Respworks. - Requests:
header(r, name): str?(ignores case),json(r): Value!,decode<T: Data>(r): T!(a JSON body),params(r): [(str, str)]andparam(r, key): str?(decoded query). router(route: (str, str, Req) => http.Resp): (Req) => http.Respcallsroute(method, path, req), so routes are clauses with string patterns:fn route("GET", "/users/" + id, r: Req). A HEAD request is routed as"GET".request(method, target, headers, body): Reqbuilds aReq, for testing handlers without a socket.
The server works like this:
- Bodies. It reads
Content-Lengthand chunked request bodies (chunk extensions and trailers are ignored), and answersExpect: 100-continue. - Closing. Every response carries
Content-LengthandConnection: close, and the server then closes the connection. There is no keep-alive or pipelining. - HEAD and bodiless statuses. A HEAD response gets its
Content-Lengthbut no body. 1xx, 204 and 304 responses have neither. - Malformed requests. These get an error response and never reach the handler:
- 400 for bad syntax, a missing
Hoston HTTP/1.1, a target that isn't strict RFC 3986, or a body that isn't UTF-8 - 413 for a body over 16 MiB (
http.wire.MAX_BODY) - 431 for headers over 64 KiB (
http.wire.MAX_HEAD) - 501 for a transfer coding other than chunked
- 505 for an HTTP version other than 1.0 or 1.1
- 400 for bad syntax, a missing
- Bad handler output. A response with a bad status or header becomes a 500.
- Dropped connections. A client that disconnects or sends nothing is dropped, and the loop goes on.
Pure layers
These are public, so you can test or reuse them:
http.uri:struct Url { tls, host, port, target },parse(s): Url!,from_url(u: url.Url): Url!,resolve(base: Url, loc: str): Url!,format(u): str,authority(u): str.http.wire, the client side:encode(method, target, host, headers, body): str!anddecode(bytes: [int], head_req: bool): (int, {str: str}, str)!.http.wire, the server side:decode_request(bytes): Got!ReqErr, whereGot { More(need, cont), Done(method, target, headers, body) }encode_response(status, headers, body, head_req): str!ReqErr { BadRequest(why), TooLarge, HeadTooLarge, NotImplemented(why), BadVersion(version) }, withstatus(e)andmessage(e)reason(status): str
Limits in 0.1
- Bodies must be UTF-8 text.
- There is no keep-alive, compression or proxy support.
- URLs can't carry credentials.
- The server runs one connection at a time. A slow client holds up the others, and there are no timeouts yet: core has no
timeout(see docs/package-list.md §6, gap 8). - A handler that panics stops the server.
- There is no server-side TLS.