messua/fail

Failure is the Error half of the Outgoing result.

import messua/fail
import messua/mout.{type Outgoing}

pub fn handle_failure(message: String) -> Outgoing {
  fail.new()
  |> fail.with_error(fail.InternalServerError)
  |> fail.with_message(message)
  |> Error()
}

Types

ErrorStatus

</>

A type for select 400 and 500 types of HTTP status codes, so your IDE can help you remember them instead of having to look the numeric values up on MDN all the time. (Which is “Unauthorized” and which is “Forbidden”?)

pub type ErrorStatus {
  BadRequest
  Unauthorized
  Forbidden
  NotFound
  MethodNotAllowed
  RequestTimeout
  Gone
  LengthRequired
  PreconditionFailed
  ContentTooLarge
  UriTooLong
  UnsupportedMediaType
  ExpectationFailed
  ImATeapot
  MisdirectedRequest
  PreconditionRequired
  TooManyRequests
  RequestHeaderFieldsTooLarge
  UnavailableForLegalReasons
  InternalServerError
  NotImplemented
  BadGateway
  ServiceUnavailable
  GatewayTimeout
  NetworkAuthenticationRequired
}

Constructors

```
BadRequest
```
```
Unauthorized
```
```
Forbidden
```
```
NotFound
```
```
MethodNotAllowed
```
```
RequestTimeout
```
```
Gone
```
```
LengthRequired
```
```
PreconditionFailed
```
```
ContentTooLarge
```
```
UriTooLong
```
```
UnsupportedMediaType
```
```
ExpectationFailed
```
```
ImATeapot
```
```
MisdirectedRequest
```
```
PreconditionRequired
```
```
TooManyRequests
```
```
RequestHeaderFieldsTooLarge
```
```
UnavailableForLegalReasons
```
```
InternalServerError
```
```
NotImplemented
```
```
BadGateway
```
```
ServiceUnavailable
```
```
GatewayTimeout
```
```
NetworkAuthenticationRequired
```

Failure

</>

The Error type in an Outgoing response.

pub type Failure {
  Failure(
    status: Int,
    headers: List(#(String, String)),
    body_chunks: option.Option(bytes_tree.BytesTree),
  )
}

Constructors

Failure(
  status: Int,
  headers: List(#(String, String)),
  body_chunks: option.Option(bytes_tree.BytesTree),
)

Values

chunks

</>

pub fn chunks(
  fail: Failure,
  message_chunks: List(String),
) -> Failure

Add a message to the response body.

When building an error message programmatically, it’s often cleaner to be able to specify a list of chunks.

fail.error(fail.MisdirectedRequest)
|> fail.chunks(["We only supply information about ", current_subject, "."])

code

</>

pub fn code(fail: Failure, status: Int) -> Failure

Return a Failure with the given response code.

No checking is done on the status value, so it’s entirely possible to return a fail.code(200). This will generate a legitimate response, but is a weird and difficult-to-read way of going about it.

fail.new() |> fail.code(418) |> Error()

The above is equivalent to

fail.error(fail.ImATeapot) |> Error()

error

</>

pub fn error(status: ErrorStatus) -> Failure

Return a default response, but with the given error status instead of just a 500.

</>

pub fn header(
  fail: Failure,
  name: String,
  value: String,
) -> Failure

Add the supplied header to the Failure response.

fail.error(fail.MethodNotAllowed)
|> fail.header("allowed", "GET, HEAD, PUT, DELETE")

message

</>

pub fn message(fail: Failure, message: String) -> Failure

Add a message to the response body.

This function can be used several times (perhaps by different Layers), appending to the body each time.

fail.error(fail.LengthRequired)
|> fail.message("Your POST request requires a Content-Length header.")

new

</>

pub fn new() -> Failure

A default Failure.

(500: Internal Server Error, no headers or body)

with_error

</>

pub fn with_error(fail: Failure, status: ErrorStatus) -> Failure

Set the Failure to have the given error status.