Skip to content

Instantly share code, notes, and snippets.

Embed
What would you like to do?
cowboy_req(3) Cowboy Function Reference cowboy_req(3)
NAME
cowboy_req - HTTP request and response
DESCRIPTION
The module cowboy_req provides functions to access, manipulate and
respond to requests.
There are four types of functions in this module. They can be differ‐
entiated by their name and their return type:
┌─────────────┬─────────────────────┬─────────────────────┐
│Type │ Name pattern │ Return type │
├─────────────┼─────────────────────┼─────────────────────┤
│access │ no verb, parse_*, │ Value │
│ │ match_* │ │
├─────────────┼─────────────────────┼─────────────────────┤
│question │ has_* │ boolean() │
├─────────────┼─────────────────────┼─────────────────────┤
│modification │ set_* │ Req │
├─────────────┼─────────────────────┼─────────────────────┤
│action │ any other verb │ ok {Result, Value, │
│ │ │ Req} │
└─────────────┴─────────────────────┴─────────────────────┘
Any Req returned must be used in place of the one passed as argument.
Functions that perform an action in particular write state in the Req
object to make sure you are using the function correctly. For example,
it's only possible to send one response, and to read the body once.
EXPORTS
Raw request:
· cowboy_req:method(3) - HTTP method
· cowboy_req:version(3) - HTTP version
· cowboy_req:scheme(3) - URI scheme
· cowboy_req:host(3) - URI host name
· cowboy_req:port(3) - URI port number
· cowboy_req:path(3) - URI path
· cowboy_req:qs(3) - URI query string
· cowboy_req:uri(3) - Reconstructed URI
· cowboy_req:header(3) - Raw HTTP header value
· cowboy_req:headers(3) - Raw HTTP headers
· cowboy_req:peer(3) - Peer address and port
Processed request:
· cowboy_req:parse_qs(3) - Parse the query string
· cowboy_req:match_qs(3) - Match the query string against constraints
· cowboy_req:parse_header(3) - Parse the given HTTP header
· cowboy_req:parse_cookies(3) - Parse cookie headers
· cowboy_req:match_cookies(3) - Match cookies against constraints
· cowboy_req:binding(3) - Access a value bound from the route
· cowboy_req:bindings(3) - Access all values bound from the route
· cowboy_req:host_info(3) - Access the route's heading host segments
· cowboy_req:path_info(3) - Access the route's trailing path segments
Request body:
· cowboy_req:has_body(3) - Is there a request body?
· cowboy_req:body_length(3) - Body length
· cowboy_req:read_body(3) - Read the request body
· cowboy_req:read_urlencoded_body(3) - Read and parse a urlencoded
request body
· cowboy_req:read_part(3) - Read the next part of a multipart body
· cowboy_req:read_part_body(3) - Read the current part's body in a
multipart body
Response:
· cowboy_req:set_resp_cookie(3) - Set a cookie
· cowboy_req:set_resp_header(3) - Set a response header
· cowboy_req:has_resp_header(3) - Is the given response header set?
· cowboy_req:delete_resp_header(3) - Delete a response header
· cowboy_req:set_resp_body(3) - Set the response body
· cowboy_req:has_resp_body(3) - Is there a response body?
· cowboy_req:reply(3) - Send the response
· cowboy_req:stream_reply(3) - Send the response and stream its body
· cowboy_req:stream_body(3) - Send a chunk of the response body
· cowboy_req:push(3) - Push a resource to the client
TYPES
push_opts()
push_opts() :: #{
method => binary(), %% case sensitive
scheme => binary(), %% lowercase; case insensitive
host => binary(), %% lowercase; case insensitive
port => inet:port_number(),
qs => binary() %% case sensitive
}
Push options.
By default, Cowboy will use the GET method, an empty query string, and
take the scheme, host and port directly from the current request's
URI.
read_body_opts()
read_body_opts() :: #{
length => non_neg_integer(),
period => non_neg_integer(),
timeout => timeout()
}
Body reading options.
The defaults are function-specific.
req()
req() :: #{
method := binary(), %% case sensitive
version := cowboy:http_version() | atom(),
scheme := binary(), %% lowercase; case insensitive
host := binary(), %% lowercase; case insensitive
port := inet:port_number(),
path := binary(), %% case sensitive
qs := binary(), %% case sensitive
headers := cowboy:http_headers(),
peer := {inet:ip_address(), inet:port_number()}
}
The Req object.
Contains information about the request and response. While some fields
are publicly documented, others aren't and shouldn't be used.
You may add custom fields if required. Make sure to namespace them by
prepending an underscore and the name of your application:
Setting a custom field
Req#{_myapp_auth_method => pubkey}.
resp_body()
resp_body() :: iodata()
| {sendfile, Offset, Length, Filename}
Offset :: non_neg_integer()
Length :: pos_integer()
Filename :: file:name_all()
Response body.
It can take two forms: the actual data to be sent or a tuple indicat‐
ing which file to send.
When sending data directly, the type is either a binary or an iolist.
Iolists are an efficient way to build output. Instead of concatenating
strings or binaries, you can simply build a list containing the frag‐
ments you want to send in the order they should be sent:
Example iolists usage
1> RespBody = ["Hello ", [<<"world">>, $!]].
["Hello ",[<<"world">>,33]]
2> io:format("~s~n", [RespBody]).
Hello world!
When using the sendfile tuple, the Length value is mandatory and must
be higher than 0. It is sent with the response in the content-length
header.
SEE ALSO
cowboy(7)
Cowboy 2.0 1984-10-28 cowboy_req(3)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
You can’t perform that action at this time.