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

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)
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)
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),
    )
pub type Response(body) {
  Response(status: Int, headers: List(Header), body: body)
}

Constructors

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

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
pub type Scheme {
  Http
  Https
}

Constructors

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

Functions

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

pub fn default_req() -> Request(String)
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.

pub fn get_query(
  request: Request(a),
) -> Result(List(#(String, String)), Nil)
pub fn get_req_cookies(
  req: Request(String),
) -> List(#(String, String))
pub fn get_req_header(
  request: Request(a),
  key: String,
) -> Result(String, Nil)
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.

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

Deprecated. Use get_resp_cookies instead.

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)

pub fn get_resp_header(
  response: Response(a),
  key: String,
) -> Result(String, Nil)
pub fn map_req_body(
  request: Request(a),
  transform: fn(a) -> b,
) -> Request(b)
pub fn map_resp_body(
  response: Response(a),
  transform: fn(a) -> b,
) -> Response(b)
pub external fn method_from_dynamic(
  Dynamic,
) -> Result(Method, Nil)
pub fn method_to_string(method: Method) -> String
pub fn parse_method(s: String) -> Result(Method, Nil)
pub fn path_segments(request: Request(a)) -> List(String)
pub fn prepend_req_header(
  request: Request(a),
  key: String,
  value: String,
) -> Request(a)
pub fn prepend_resp_header(
  response: Response(a),
  key: String,
  value: String,
) -> Response(a)
pub fn redirect(uri: String) -> Response(String)
pub fn req_from_uri(uri: Uri) -> Result(Request(String), Nil)
pub fn req_to_uri(request: Request(a)) -> Uri
pub fn response(status: Int) -> Response(Nil)
pub fn scheme_from_string(scheme: String) -> Result(Scheme, Nil)
pub fn scheme_to_string(scheme: Scheme) -> String
pub fn set_host(req: Request(a), host: String) -> Request(a)
pub fn set_method(req: Request(a), method: Method) -> Request(a)
pub fn set_path(req: Request(a), path: String) -> Request(a)
pub fn set_port(req: Request(a), port: Int) -> Request(a)
pub fn set_query(
  req: Request(a),
  query: List(#(String, String)),
) -> Request(a)
pub fn set_req_body(req: Request(a), body: b) -> Request(b)
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.

pub fn set_resp_body(
  response: Response(a),
  body: b,
) -> Response(b)
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

pub fn set_scheme(req: Request(a), scheme: Scheme) -> Request(a)
pub fn try_map_resp_body(
  response: Response(a),
  transform: fn(a) -> Result(b, c),
) -> Result(Response(b), c)