push_opts() :: #{ method => binary(), %% case sensitive scheme => binary(), %% lowercase; case insensitive host => binary(), %% lowercase; case insensitive port => inet:port_number(), qs => binary() %% case sensitive }
cowboy_req - HTTP request and response
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 differentiated by their name and their return type:
| Type | Name pattern | Return type |
|---|---|---|
access |
no verb, parse_*, match_* |
|
question |
has_* |
|
modification |
set_* |
|
action |
any other verb |
|
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.
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) - HTTP header
cowboy_req:headers(3) - 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 multipart headers
cowboy_req:read_part_body(3) - Read the current part’s 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
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() :: #{ length => non_neg_integer(), period => non_neg_integer(), timeout => timeout() }
Body reading options.
The defaults are function-specific.
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:
Req#{_myapp_auth_method => pubkey}.
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 indicating 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 fragments you want to send in the order they should be sent:
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.