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), )

A HTTP header is a key-value pair. Header keys should be all lowercase characters.

pub type Header =
  tuple(String, String)

Method

HTTP standard method as defined by RFC 2616, and PATCH which is defined by RFC 5789.

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)
Non-standard but valid HTTP methods.

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

The two URI schemes for HTTP

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)

A request with commonly used default values. This request can be used as an initial value and then update to create the desired request.

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(tuple(String, String)), Nil)

Decode the query of a request.

get_req_cookies

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

Fetch the cookies sent in a request.

Note badly formed cookie pairs will be ignored. RFC6265 specifies that invalid cookie names/attributes should be ignored.

get_req_header

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

Get the value for a given header.

If the request does not have that header then Error(Nil) is returned.

get_req_origin

pub fn get_req_origin(req: Request(a)) -> Option(String)

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(tuple(String, String))

Deprecated. Use get_resp_cookies instead.

get_resp_cookies

pub fn get_resp_cookies(
  resp: Response(Nil),
) -> List(tuple(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)

Get the value for a given header.

If the request does not have that header then Error(Nil) is returned.

map_req_body

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

Update the body of a request using a given function.

map_resp_body

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

Update the body of a response using a given function.

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)

Return the non-empty segments of a request path.

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)

Create a response that redirects to the given uri.

req_from_uri

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

Construct a request from a URI.

req_to_uri

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

Return the uri that a request was sent to.

response

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

Construct an empty Response.

The body type of the returned response is Nil, and should be set with a call to set_resp_body.

scheme_from_string

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

Parse a HTTP scheme from a string

Examples

> scheme_to_string("http")
Ok(Http)

> scheme_to_string("ftp")
Error(Nil)

scheme_to_string

pub fn scheme_to_string(scheme: Scheme) -> String

Convert a scheme into a string.

Examples

> scheme_to_string(Http)
"http"

> scheme_to_string(Https)
"https"

set_host

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

Set the method of the request.

set_method

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

Set the method of the request.

set_path

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

Set the path of the request.

set_port

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

Set the port of the request.

set_query

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

Set the query of the request.

set_req_body

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

Set the body of the request, overwriting any existing body.

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 the body of the response, overwriting any existing body.

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)

Set the scheme (protocol) of the request.

try_map_resp_body

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

Update the body of a response using a given result returning function.

If the given function returns an Ok value the body is set, if it returns an Error value then the error is returned.