API reference

Everything (http-server) exports, one entry each, and at the end everything (http-server testing) exports, for testing a handler. Types are written as Typed Racket writes them: Nat is an exact non-negative integer, [x] an optional argument, (U a b) either one.

(import (rnrs) (http-server))

Shared types:

Headers  = (Listof (Pair Bytevector Bytevector))
Body     = (U Bytevector #f Producer SizedBody)
Producer = (-> (U Bytevector Eof))
Answer   = (U Response BodyReader Awaiting)

The server

serve

serve : (Request -> (U Answer Switch)) [(String -> (U String #f))] -> Void

Starts the server with this handler and runs until it is sent SIGTERM or SIGINT and has drained. The optional second argument looks up settings in place of the process's environment. Raises &http-server-config-error for a malformed setting. See Handlers and Configuration.

&http-server-error, http-server-error?

An &error: the condition type of the server's own errors. http-server-error? : Any -> Boolean.

&http-server-config-error, http-server-config-error?

An &http-server-error: a setting is malformed, raised by serve before it listens. Its message names the variable. http-server-config-error? : Any -> Boolean.

Reading a request

Every string they give, header names included, has one character per byte of the request (Latin-1), and is made when called. The addresses and ports are the connection's, not the request's, each #f where the server can't say. See Handlers.

Reading a body

See Bodies and streaming.

read-body

read-body : (Bytevector Nat Nat -> Any) (-> Response) -> BodyReader

A reader: the first procedure gets each piece of the body as bv[start, end) as it arrives; the second, called at the body's end, returns the response.

read-whole-body

read-whole-body : (Bytevector -> Response) [(U Nat #f)] -> BodyReader

A reader that collects the whole body, up to the cap (1 MiB by default), and calls the procedure with it. A bigger body gets 413.

Answering

make-response

make-response : Nat (U Bytevector #f) Headers Body -> Response

A response: status (200 to 599), reason phrase (#f for the usual one), headers, body. See Responses.

response?

Any -> Boolean.

sized-body

sized-body : Nat Producer -> SizedBody

A body of that many bytes, made by the producer as it is sent, with its Content-Length. See Bodies and streaming.

request-on-done!

request-on-done! : Request (Symbol -> Any) -> Void

Registers a procedure that the server calls once, just after the request's response is done, or once the request's code that waits has stopped. It gets written, client-closed or failed. Procedures run newest first; one registered after the response is done runs at once, in the caller. See Handlers.

Waiting

See Waiting. The waits below work only inside a thunk given to awaiting, or a reader or producer it answers with.

Conditions, each an &error:

resolve-error-reason : ResolveError -> Symbol says why a lookup failed: EAI_NONAME and the resolver's other codes, or invalid-name.

body-failed-reason : BodyFailed -> Symbol says why a body failed, such as body-too-large, body-timeout or invalid-chunk-size, and body-failed-status : BodyFailed -> Nat is the status the server answers if the raise is let out.

Upgrades

See Upgrades.

switch-protocols

switch-protocols : Headers (Transport Bytevector -> Any) -> Switch

An answer that takes an HTTP/1.1 upgrade: the server writes 101 with these headers, then calls the procedure with the transport and the bytes it had already read past the request.

The transport

make-transport

make-transport : write read-start read-stop close deadline on-drain on-close [abort]
                 -> Transport

A transport of your own, for testing a taker without a server: each argument is the procedure the matching call above ends up in. Without abort, transport-abort! on it is refused.

Testing: (http-server testing)

A host that runs a handler for a scripted client, its waits included, with no socket and a clock the test moves. Each call that does something, a connect, a send, a close, a reset, an advance or an answer, runs all that follows from it before it returns. See Testing handlers.

(import (rnrs) (http-server) (http-server testing))

make-test-host

make-test-host : (Request -> (U Answer Switch)) [(String -> (U String #f))] -> TestHost

A host for the handler serve would get, its clock at 0 ms. The optional second argument gives the settings, as serve's does; without it every setting is its default. Raises &http-server-config-error for a malformed setting, as serve does before it listens. A CHEZ_HTTP_HOST that is not an IP address is not refused: only serve refuses it, as it listens.

The host

The client

A response read