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
Header
A HTTP header is a key-value pair. Header keys should be all lowercase characters.
pub type Header = tuple(String, 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)
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
default_req
pub fn default_req() -> Request(String)
A request with commonly used default values. This request can be used as a an initial value and then update to create the desired request.
get_query
pub fn get_query( request: Request(a), ) -> Result(List(tuple(String, String)), Nil)
Decode the query of a request.
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_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.
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_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_resp_body
pub fn set_resp_body( response: Response(a), body: b, ) -> Response(b)
Set the body of the response, overwriting any existing body.
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.