The response type used throughout this library.

Outgoing is a Result type, which takes advantage of the “early return on error” behavior¹ of use sugar. The Error(Failure) variant is turned into an actual HTTP response before being spit back out into the world.

(This example contains some hypothetical functions and types that we do not define, but the general idea should be clear from context.)

// This wrapper around our database module's `check_auth()` function
// is designed to work with `result.try()`.
fn check_auth(
  db_handle: DatabaseHandle,
  auth_header: String,
) -> Result(User, Failure) {
  case dbase.get_user_from_auth(auth_header) {
    Ok(user) -> Ok(user)
    Error(dbase.UserNotFound) -> fail.error(fail.Unauthorized) |> Error()
    Error(_) -> fail.error(fail.InternalServerError) |> Error()
  }
}

fn handle(in: Incoming(DatabaseHandle)) -> Outgoing {
  // If the request doesn't have an "authorization" header, this returns a
  // 400: Bad Request response with a body noting the required header.
  use auth_header <- handle.require_header(in, "authorization")
  // If, for some reason, we can't get our hands on the server state, this
  // returns a 500: Internal Server Error response.
  use db_handle <- handle.require_state(in)
  // If `check_auth()` fails, we return the `Error(Failure)` response
  // it gives us, otherwise we have our authenticated `User`.
  use user <- result.try(check_auth(db_handle, auth_header))
  // If we can't decode request data from the body (because it's invalid
  // or missing), we return a 400: Bad Request response.
  use request_data <- handle.require_json_body(
    in,
    1024 * 1024,
    request_data_decoder(),
  )
  // If our actual processing of the request fails, we return a
  // 500: Internal Server Error response here, otherwise we have
  // the data for our response.
  use result_data <- result.try(
    dbase.do_business_logic(db_handle, user, request_data)
    |> result.replace_error(fail.new()),
  )
  let result_json = result_data_to_json(result_data)
  // And we return our response data in a 200: Ok response.
  mout.ok()
  |> mout.with_json_body(result_json)
}