cowboy/guide/req.md

Request object

Purpose

The request object is a special variable that can be used to interact with a request, extracting information from it or modifying it, and sending a response.

It's a special variable because it contains both immutable and mutable state. This means that some operations performed on the request object will always return the same result, while others will not. For example, obtaining request headers can be repeated safely. Obtaining the request body can only be done once, as it is read directly from the socket.

With few exceptions, all calls to the cowboy_req module will return an updated request object. You MUST use the new request object instead of the old one for all subsequent operations.

Request

Cowboy allows you to retrieve a lot of information about the request. All these calls return a {Value, Req} tuple, with Value the requested value and Req the updated request object.

The following access functions are defined in cowboy_req:

• method/1: the request method (<<"GET">>, <<"POST">>...)
• version/1: the HTTP version ({1,0} or {1,1})
• peer/1: the peer address and port number
• peer_addr/1: the peer address guessed using the request headers
• host/1: the hostname requested
• host_info/1: the result of the [...] match on the host
• port/1: the port number used for the connection
• path/1: the path requested
• path_info/1: the result of the [...] match on the path
• qs/1: the entire query string unmodified
• qs_val/{2,3}: the value for the requested query string key
• qs_vals/1: all key/values found in the query string
• fragment/1: the fragment part of the URL (e.g. #nav-links)
• host_url/1: the requested URL without the path, qs and fragment
• url/1: the requested URL
• binding/{2,3}: the value for the requested binding found during routing
• bindings/1: all key/values found during routing
• header/{2,3}: the value for the requested header name
• headers/1: all headers name/value
• cookie/{2,3}: the value for the requested cookie name
• cookies/1: all cookies name/value
• meta/{2,3}: the meta information for the requested key

All the functions above that can take two or three arguments take an optional third argument for the default value if none is found. Otherwise it will return undefined.

In addition, Cowboy allows you to parse headers using the parse_header/{2,3} function, which takes a header name as lowercase binary, the request object, and an optional default value. It returns {ok, ParsedValue, Req} if it could be parsed, {undefined, RawValue, Req} if Cowboy doesn't know this header, and {error, badarg} if Cowboy encountered an error while trying to parse it.

Finally, Cowboy allows you to set request meta information using the set_meta/3 function, which takes a name, a value and the request object and returns the latter modified.

Request body

@todo Describe.

Response

@todo Describe.