Get the body of the request, if there is one.

Return the value of the name header from the request, if it exists.

Return the query string portion of the request URL, if there is one.

If there is a valid UTF-8 body, return it as a string, otherwise return None.

A list of the #(header_name, header_value) pairs from the incoming request.

fn first(tuple: #(a, a)) -> a {
   tuple.0
}


pub fn handle(in: Incoming) -> Outgoing {
  let header_names = handle.headers(in) |> list.map(first)
  let body =
    ["Your request had the following headers:", ..header_names]
    |> string.join("\n")

  mout.ok() |> mout.with_string_body(body)
}

The method used in the incoming request.

pub fn handler(in: Incoming(Nil)) -> Outgoing {
  let method = case handle.method(in) {
    http.Get -> "GET"
    _ -> "do something more complicated than a GET with"
  }

  let body = ["You asked me to ", method, " a resource."]
  |> string.concat()

  mout.ok()
  |> mout.with_string_body(body)
}

The path portion of the URL used in the incoming request.

Decode the request query string and return it as a list of #(name, value) tuples.

This will percent-decode the key-value pairs, and no query string will result in an empty list.

This handler Function

fn handle(in: Incoming(Nil)) -> Outgoing {
  let query_pairs = handle.query_pairs(in) |> string.inspect() <> "\n"

  mout.ok() |> mout.with_string_body(query_pairs)
}

Will exhibit the following behavior:

$ curl "http://localhost:8080?frog=blue&salamander=orange"
[#("frog", "blue"), #("salamander", "orange")]

$ curl "http://localhost:8080?bird+name=lu+lu"
[#("bird name", "lu lu")]

$ curl "http://localhost:8080"
[]

Will supply the body of the request if there is one, otherwise it will return a 400 response.

use body_bits <- handle.require_body(in, 1024 * 1024)

case do_something_with_bits(body_bits) {
  Ok(answer_string) -> mout.ok() |> mout.with_string_body(answer_string)
  Error(problem_string) -> mout.fail() |> mout.with_body_string(problem_string)
}

Get the value of the name header from the request, or return a “Bad Request” response with an error message.

Given this handler function:

fn handle(in: Incoming(Nil)) -> Outgoing {
  use frog_color <- handle.require_header(in, "x-frog-color")
  let body = ["You prefer ", frog_color, " frogs.\n"] |> string.concat()

  mout.ok()
  |> mout.with_string_body(body)
}

You should see this behavior:

$ curl -s -D - http://localhost:8080
HTTP/1.1 400 Bad Request
content-length: 54
content-type: text/plain
date: Fri, 19 Dec 2025 21:14:21 GMT
connection: keep-alive

Request requires a valid "x-frog-color" header value.

$ curl -s -D - http://localhost:8080 -H "x-frog-color: blue"
HTTP/1.1 200 OK
content-type: text/plain
content-length: 23
date: Fri, 19 Dec 2025 21:14:11 GMT
connection: keep-alive

You prefer blue frogs.

Require a JSON-encoded body that can be decoded successfully by the supplied decoder. If there’s no body, or it fails to decode, a 400 response will be returned.

Supply the query string portion of the request URL, or return a 400 response.

If there is a valid UTF-8 body, supply it as a string, otherwise return a 400 response.

If the header with the supplied name exists, and the associated value returns an Ok() result from the supplied parser, will use that value. Otherwise, will return an error response with an explanatory message.

For example, this hander:

fn handle(in: Incoming(Nil)) -> Outgoing {
  use frog_count <- handle.require_valid_header(in, "x-frog-count", int.parse)
  let body =
    ["You requested ", int.to_string(frog_count), " frogs.\n"]
    |> string.concat()

  mout.ok() |> mout.with_string_body(body)
}

Should produce this behavior:

~/ $ curl -s -D - http://localhost:8080
HTTP/1.1 400 Bad Request
content-length: 54
content-type: text/plain
date: Tue, 23 Dec 2025 17:39:10 GMT
connection: keep-alive

Request requires a valid "x-frog-count" header value.

~/ $ curl -s -D - http://localhost:8080 -H "x-frog-count: 7"
HTTP/1.1 200 OK
content-type: text/plain
content-length: 23
date: Tue, 23 Dec 2025 17:39:13 GMT
connection: keep-alive

You requested 7 frogs.

~/ $ curl -s -D - http://localhost:8080 -H "x-frog-count: seven"
HTTP/1.1 400 Bad Request
content-length: 54
content-type: text/plain
date: Tue, 23 Dec 2025 17:39:16 GMT
connection: keep-alive

Request requires a valid "x-frog-count" header value.

If the given header name is present and returns an Ok() value from parser(), the handling function will be furnished with Some(value); if parser() returns an Error(), messua will return an appropriate error response. If the header name is not present, the handler will be furnished with None.

Yes, this is a confusing function name, and probalby a confusing explanation. Here’s an example.

This request handler:

fn handle(in: Incoming(Nil)) -> Outgoing {
  use maybe_frog_count <- handle.require_valid_optional_header(
    in,
    "x-frog-count",
    int.parse,
  )

  let message = case maybe_frog_count {
    None -> "You don't want any frogs?"
    Some(n) if n < 0 -> "You want... us to take frogs from you?"
    Some(1) -> "You requested a single frog."
    Some(n) -> "You requested " <> int.to_string(n) <> " frogs."
  }

  mout.ok() |> mout.with_string_body(message)
}

Should exhibit this behavior:

$ curl http://localhost:8080
You don't want any frogs?

$ curl http://localhost:8080 -H "x-frog-count: none"
"none" is not a valid "x-frog-count" value.

$ curl http://localhost:8080 -H "x-frog-count: 12"
You requested 12 frogs.

The scheme used in the incoming request.