Http

Method = [Get | Post | Patch | Put | Delete | Head | Options | Trace | Connect | Other(String)]

A request method. Any other method is Other, with its case kept: "PROPFIND" is Other("PROPFIND"), and "get" is Other("get").

Scheme = [Http | Https]

http or https.

Option(a) = [Some(a) | None]

Shorthand for [Some(a) | None], a value that may be absent.

Header = { name: String, value: String }

A header, and every other name/value pair: a query parameter, a cookie, a header parameter.

Request(body) = {
  method: Method,
  headers: List(Header),
  body: body,
  scheme: Scheme,
  host: String,
  port: Option(Int),
  path: String,
  query: Option(String)
}

A request, with a body of any type. A server hands one over with Bytes.@Bytes as its body; mapRequest turns that into what a handler wants to read. Header names are lowercase, and query is the raw query string, without its ?.

Response(body) = { status: Int, headers: List(Header), body: body }

A response, with a body of any type. A server sends one with a Bytes.@Bytes body; mapResponse turns a text body into one.

SameSitePolicy = [Lax | Strict | None]

The SameSite attribute of a cookie.

CookieAttributes = {
  maxAge: Option(Int),
  domain: Option(String),
  path: Option(String),
  secure: Bool,
  httpOnly: Bool,
  sameSite: Option(SameSitePolicy)
}

What a set-cookie header says beside the cookie itself.

ContentDisposition = { disposition: String, parameters: List(Header) }

A content-disposition header: its disposition, such as attachment, and its parameters.

HeaderLink = { uri: String, parameters: List(Header) }

One link of a link header. The URI reference is kept as it is written.

BasicCredentials = { user: String, password: String }

The user name and password of HTTP Basic authentication.

Result(a, e) = [Ok(a) | Err(e)]

Shorthand for [Ok(a) | Err(e)], the variant this module's fallible functions return.

(String) -> Result(Method, [InvalidMethod | e])pure

A standard method by its uppercase name. Any other valid token is Other, case kept, so "get" is Other("get").

(Method) -> Stringpure

The method as a request line writes it, in uppercase: GET, POST, or an Other method's own text.

(Scheme) -> Stringpure

"http" or "https".

(String) -> Result(Scheme, [UnknownScheme | e])pure

Either scheme, in any case.

(String) -> Result(ContentDisposition, [MalformedHeader | e])pure

A content-disposition header: its type and parameters, both names lowercased. A parameter value may be quoted, with \ escaping the next character.

(String) -> Result(List(HeaderLink), [MalformedHeader | e])pure

A link header (RFC 8288): each link's URI reference and its parameters, in order, names lowercased and duplicates kept. A comma inside a quoted value does not end the link. An extended parameter such as title* is kept undecoded.

() -> Request(String)pure

A GET of https://localhost with no headers, no query and an empty body, to update into the request wanted.

(Int) -> Response(String)pure

A response with this status, no headers and an empty body.

(String) -> Response(String)pure

A 303 See Other to uri.

({ headers: List(Header) | r }, String) -> Result(String, [NotFound | e])pure

The value of the first header named key, in any case.

({ headers: List(Header) | r }, String, String) -> { headers: List(Header) | r }pure

Replace the first header named key, or add one at the end.

({ headers: List(Header) | r }, String, String) -> { headers: List(Header) | r }pure

Add a header in front, keeping any already named key.

({ body: b | r }, b) -> { body: b | r }pure

A body of the same type; mapRequest and mapResponse change its type.

(Request(a), (a) -> b) -> Request(b)pure if arg2 is

The request with its body passed through transform.

(Response(a), (a) -> b) -> Response(b)pure if arg2 is

The response with its body passed through transform.

(Response(a), (a) -> Result(b, e)) -> Result(Response(b), e)pure if arg2 is

mapResponse with a transform that may fail, whose error is the result's.

(Request(b)) -> List(String)pure

The path's non-empty segments, dot-segments resolved.

(Request(b)) -> Result(List(Header), [InvalidEncoding | e])pure

The decoded query parameters; no query has none.

(Request(b), List(Header)) -> Request(b)pure

The parameters as the query, each name and value percent-encoded, + included, so that getQuery reads back what was set.

(Request(b), Method) -> Request(b)pure

The request with its method replaced.

(Request(b), Scheme) -> Request(b)pure

The request with its scheme replaced.

(Request(b), String) -> Request(b)pure

The request with its host replaced.

(Request(b), Int) -> Request(b)pure

The request with its port set.

(Request(b), String) -> Request(b)pure

The request with its path replaced.

(Request(b)) -> List(Header)pure

Every cookie of every cookie header. A malformed pair is skipped.

(Request(b), String, String) -> Request(b)pure

Set a cookie in the cookie header, replacing one of the same name. The header moves to the front. With more than one cookie header, only the first is searched for the name.

(Request(b), String) -> Request(b)pure

Drop the cookies named name from the first cookie header. It does not remove the cookie from the client.

(Response(b)) -> List(Header)pure

Every cookie of every set-cookie header, attributes included as pairs. A malformed pair is skipped.

(Response(b), String, String, CookieAttributes) -> Response(b)pure

Adds a set-cookie header that sets the cookie name to value, with these attributes.

(Response(b), String, CookieAttributes) -> Response(b)pure

Expire a cookie on the client. The attributes should be the ones it was set with.

(String) -> List(Header)pure

The cookies of a cookie header. Pairs are separated by ;, or by , as the obsolete RFC 2965 allows; a pair with no =, an empty name, or whitespace inside its name or value is skipped.

(String, String, CookieAttributes) -> Stringpure

The value of a set-cookie header. A maxAge of 0 also writes an Expires in the past, so that a client that predates Max-Age deletes the cookie too.

(Scheme) -> CookieAttributespure

Attributes for a cookie on the site at scheme: path /, HttpOnly, SameSite=Lax, and Secure over HTTPS.

(Request(b)) -> Result(BasicCredentials, [MissingAuthorization | InvalidAuthorization | e])pure

The credentials of an authorization header with the Basic scheme (RFC 7617): the scheme in any case, one or more spaces, and the standard, padded base64 of user:password in UTF-8. The user name ends at the first colon, so the password may hold colons and either may be empty. No such header is MissingAuthorization; any other scheme, or a token that is not base64 of UTF-8 with a colon in it, is InvalidAuthorization.

(Request(b), BasicCredentials) -> Request(b)pure

Set the authorization header to basicAuthHeader(credentials), replacing any there is.

(BasicCredentials) -> Stringpure

The value of an authorization header with the Basic scheme: Basic and the standard, padded base64 of user:password in UTF-8. A user name with a colon in it is encoded as it is, and getBasicAuth reads it back split at that first colon.