gleam/http

Functions for working with HTTP data structures in Gleam.

This module makes it easy to create and modify Requests and Responses, data types. A general HTTP message type is defined that enables functions to work on both requests and responses.

This module does not implement a HTTP client or HTTP server, but it can be used as a base for them.

Types

CookieAttributes

Attributes of a cookie when sent to a client in the set-cookie header.

pub type CookieAttributes {
  CookieAttributes(
    max_age: Option(Int),
    domain: Option(String),
    path: Option(String),
    secure: Bool,
    http_only: Bool,
    same_site: Option(SameSitePolicy),
  )
}

Constructors

CookieAttributes(
  max_age: Option(Int),
  domain: Option(String),
  path: Option(String),
  secure: Bool,
  http_only: Bool,
  same_site: Option(SameSitePolicy),
)

pub type Header =
  #(String, String)

Method

pub type Method {
  Get
  Post
  Head
  Put
  Delete
  Trace
  Connect
  Options
  Patch
  Other(String)
}

Constructors

```
Get
```
```
Post
```
```
Head
```
```
Put
```
```
Delete
```
```
Trace
```
```
Connect
```
```
Options
```
```
Patch
```
```
Other(String)
```

Request

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

Constructors

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

Response

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

Constructors

Response(status: Int, headers: List(Header), body: body)

SameSitePolicy

Policy options for the SameSite cookie attribute

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie/SameSite

pub type SameSitePolicy {
  Lax
  Strict
  None
}

Constructors

```
Lax
```
```
Strict
```
```
None
```

Scheme

pub type Scheme {
  Http
  Https
}

Constructors

```
Http
```
```
Https
```

Service

pub type Service(in, out) =
  fn(Request(in)) -> Response(out)

Functions

cookie_defaults

pub fn cookie_defaults(scheme: Scheme) -> CookieAttributes

Helper to create sensible default attributes for a set cookie.

Note these defaults may not be sufficient to secure your application. You should consider setting the SameSite field.

https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Set-Cookie#Attributes

default_req

pub fn default_req() -> Request(String)

expire_resp_cookie

pub fn expire_resp_cookie(
  resp: Response(a),
  name: String,
  attributes: CookieAttributes,
) -> Response(a)

Expire a cookie value for a client

Not the attributes value should be the same as when the response cookie was set.

get_query

pub fn get_query(
  request: Request(a),
) -> Result(List(#(String, String)), Nil)

get_req_cookies

pub fn get_req_cookies(
  req: Request(String),
) -> List(#(String, String))

get_req_header

pub fn get_req_header(
  request: Request(a),
  key: String,
) -> Result(String, Nil)

get_req_origin

pub fn get_req_origin(req: Request(a)) -> Result(String, Nil)

Get the origin request header

If no “origin” header is found in the request, falls back to the “referer” header.

get_resp_cookie

pub fn get_resp_cookie(
  resp: Response(Nil),
) -> List(#(String, String))

Deprecated. Use get_resp_cookies instead.

get_resp_cookies

pub fn get_resp_cookies(
  resp: Response(Nil),
) -> List(#(String, String))

Fetch the cookies sent in a response

Follows the same logic as fetching the cookie from the request (i.e. badly formed cookies will be ignored)

get_resp_header

pub fn get_resp_header(
  response: Response(a),
  key: String,
) -> Result(String, Nil)

map_req_body

pub fn map_req_body(
  request: Request(a),
  transform: fn(a) -> b,
) -> Request(b)

map_resp_body

pub fn map_resp_body(
  response: Response(a),
  transform: fn(a) -> b,
) -> Response(b)

method_from_dynamic

pub external fn method_from_dynamic(
  Dynamic,
) -> Result(Method, Nil)

method_to_string

pub fn method_to_string(method: Method) -> String

parse_method

pub fn parse_method(s: String) -> Result(Method, Nil)

path_segments

pub fn path_segments(request: Request(a)) -> List(String)

prepend_req_header

pub fn prepend_req_header(
  request: Request(a),
  key: String,
  value: String,
) -> Request(a)

prepend_resp_header

pub fn prepend_resp_header(
  response: Response(a),
  key: String,
  value: String,
) -> Response(a)

redirect

pub fn redirect(uri: String) -> Response(String)

req_from_uri

pub fn req_from_uri(uri: Uri) -> Result(Request(String), Nil)

req_to_uri

pub fn req_to_uri(request: Request(a)) -> Uri

response

pub fn response(status: Int) -> Response(Nil)

scheme_from_string

pub fn scheme_from_string(scheme: String) -> Result(Scheme, Nil)

scheme_to_string

pub fn scheme_to_string(scheme: Scheme) -> String

set_host

pub fn set_host(req: Request(a), host: String) -> Request(a)

set_method

pub fn set_method(req: Request(a), method: Method) -> Request(a)

set_path

pub fn set_path(req: Request(a), path: String) -> Request(a)

set_port

pub fn set_port(req: Request(a), port: Int) -> Request(a)

set_query

pub fn set_query(
  req: Request(a),
  query: List(#(String, String)),
) -> Request(a)

set_req_body

pub fn set_req_body(req: Request(a), body: b) -> Request(b)

set_req_cookie

pub fn set_req_cookie(
  req: Request(a),
  name: String,
  value: String,
) -> Request(a)

Send a cookie with a request

Multiple cookies are added to the same cookie header.

set_resp_body

pub fn set_resp_body(
  response: Response(a),
  body: b,
) -> Response(b)

set_resp_cookie

pub fn set_resp_cookie(
  resp: Response(a),
  name: String,
  value: String,
  attributes: CookieAttributes,
) -> Response(a)

Set a cookie value for a client

The attributes record is defined in gleam/http/cookie

set_scheme

pub fn set_scheme(req: Request(a), scheme: Scheme) -> Request(a)

try_map_resp_body

pub fn try_map_resp_body(
  response: Response(a),
  transform: fn(a) -> Result(b, c),
) -> Result(Response(b), c)