While we call it an "object", it is not an object in the OOP sense of the term. In fact it is completely opaque to you and the only way you can perform operations using it is by calling the functions from the cowboy_req module.

Almost all the calls to the cowboy_req module will return an updated request object. Just like you would keep the updated State variable in a gen_server, you MUST keep the updated Req variable in a Cowboy handler. Cowboy will use this object to know whether a response has been sent when the handler has finished executing.

The Req object allows accessing both immutable and mutable state. This means that calling some of the functions twice will not produce the same result. For example, when streaming the request body, the function will return the body by chunks, one at a time, until there is none left.

With the exception of functions manipulating the request body, all functions return a single value. Depending on the function this can be the requested value (method, host, path, …), a boolean (has_body, has_resp_header…) a new Req object (set_resp_body, set_resp_header…), or simply the atom ok (chunk, continue, …).

The request body reading functions may return {Result, Req} or {Result, Value, Req}. The functions in this category are body/{1,2}, body_qs/{1,2}, part/{1,2}, part_body/{1,2}.

This chapter covers the access functions mainly. Cookies, request body and response functions are covered in their own chapters.

When a client performs a request, it first sends a few required values. They are sent differently depending on the protocol being used, but the intent is the same. They indicate to the server the type of action it wants to do and how to locate the resource to perform it on.

The method identifies the action. Standard methods include GET, HEAD, OPTIONS, PATCH, POST, PUT, DELETE. Method names are case sensitive.

The host, port and path parts of the URL identify the resource being accessed. The host and port information may not be available if the client uses HTTP/1.0.

The version used by the client can of course also be obtained.

Do note however that clients claiming to implement one version of the protocol does not mean they implement it fully, or even properly.

After routing the request, bindings are available. Bindings are these parts of the host or path that you chose to extract when defining the routes of your application.

You can fetch a single binding. The value will be undefined if the binding doesn’t exist.

If you need a different value when the binding doesn’t exist, you can change the default.

You can also obtain all bindings in one call. They will be returned as a list of key/value tuples.

If you used ... at the beginning of the route’s pattern for the host, you can retrieve the matched part of the host. The value will be undefined otherwise.

Similarly, if you used ... at the end of the route’s pattern for the path, you can retrieve the matched part, or get undefined otherwise.

The raw query string can be obtained directly.

You can parse the query string and then use standard library functions to access individual values.

You can match the query string into a map.

You can use constraints to validate the values while matching them. The following snippet will crash if the id value is not an integer number or if the lang value is empty. Additionally the id value will be converted to an integer term, saving you a conversion step.

Note that in the case of duplicate query string keys, the map value will become a list of the different values.

Read more about ^constraints.

A default value can be provided. The default will be used if the lang key is not found. It will not be used if the key is found but has an empty value.

If no default is provided and the value is missing, the query string is deemed invalid and the process will crash.

You can reconstruct the full URL of the resource.

You can also obtain only the base of the URL, excluding the path and query string.

Cowboy allows you to obtain the header values as string, or parsed into a more meaningful representation.

This will get the string value of a header.

You can of course set a default in case the header is missing.

And also obtain all headers.

To parse the previous header, simply call parse_header/{2,3} where you would call header/{2,3} otherwise.

Cowboy will crash if it doesn’t know how to parse the given header, or if the value is invalid.

You can of course define a default value. Note that the default value you specify here is the parsed value you’d like to get by default.

The list of known headers and default values is defined in the manual.

Cowboy will sometimes associate some meta information with the request. Built-in meta values are listed in the manual for their respective modules.

This will get a meta value. The returned value will be undefined if it isn’t defined.

You can change the default value if needed.

You can also define your own meta values. The name must be an atom().

You can obtain the peer address and port number. This is not necessarily the actual IP and port of the client, but rather the one of the machine that connected to the server.