Module cowboy_req

HTTP request manipulation API.

Description

HTTP request manipulation API.

The functions in this module try to follow this pattern for their return types:
access:
{Value, Req}
action:
{Result, Req} | {Result, Value, Req} | {error, atom()}
modification:
Req
question (has_* or is_*):
boolean()

Exceptions include chunk/2 which always returns 'ok', to_list/1 which returns a list of key/values, and transport/1 which returns {ok, Transport, Socket}.

Also note that all body reading functions perform actions, as Cowboy doesn't read the request body until they are called.

Whenever Req is returned, it should always be kept in place of the one given as argument in your function call, because it keeps track of the request and response state. Doing so allows Cowboy to do some lazy evaluation and cache results when possible.

Data Types

cookie_option()

cookie_option() = {max_age, non_neg_integer()} | {domain, binary()} | {path, binary()} | {secure, boolean()} | {http_only, boolean()}

cookie_opts()

cookie_opts() = [cookie_option()]

req()

abstract datatype: req()

resp_body_fun()

resp_body_fun() = fun((inet:socket(), module()) -> ok)

Function Index

binding/2Equivalent to binding(Name, Req, undefined).
binding/3Return the binding value for the given key obtained when matching the host and path against the dispatch list, or a default if missing.
bindings/1Return the full list of binding values.
body/1Equivalent to body(8000000, Req).
body/2Return the body sent with the request.
body_length/1Return the request message body length, if known.
body_qs/1Equivalent to body_qs(16000, Req).
body_qs/2Return the body sent with the request, parsed as an application/x-www-form-urlencoded string.
chunk/2Send a chunk of data.
chunked_reply/2Equivalent to chunked_reply(Status, [], Req).
chunked_reply/3Initiate the sending of a chunked reply to the client.
compact/1Compact the request data by removing all non-system information.
cookie/2Equivalent to cookie(Name, Req, undefined).
cookie/3Return the cookie value for the given key, or a default if missing.
cookies/1Return the full list of cookie values.
delete_resp_header/2
fragment/1Return the raw fragment directly taken from the request.
has_body/1Return whether the request message has a body.
has_resp_body/1Return whether a body has been set for the response.
has_resp_header/2Return whether the given header has been set for the response.
header/2Equivalent to header(Name, Req, undefined).
header/3Return the header value for the given key, or a default if missing.
headers/1Return the full list of headers.
host/1Return the host binary string.
host_info/1Return the extra host information obtained from partially matching the hostname using '...'.
host_url/1Return the request URL as a binary without the path and query string.
init_stream/4Equivalent to init_stream(1000000, TransferDecode, TransferState, ContentDecode, Req).
init_stream/5Initialize body streaming and set custom decoding functions.
meta/2Equivalent to meta(Name, Req, undefined).
meta/3Return metadata information about the request.
method/1Return the HTTP method of the request.
multipart_data/1Return data from the multipart parser.
multipart_skip/1Skip a part returned by the multipart parser.
parse_header/2Semantically parse headers.
parse_header/3Semantically parse headers.
path/1Return the path binary string.
path_info/1Return the extra path information obtained from partially matching the patch using '...'.
peer/1Return the peer address and port number of the remote host.
peer_addr/1Returns the peer address calculated from headers.
port/1Return the port used for this request.
qs/1Return the raw query string directly taken from the request.
qs_val/2Equivalent to qs_val(Name, Req, undefined).
qs_val/3Return the query string value for the given key, or a default if missing.
qs_vals/1Return the full list of query string values.
reply/2Equivalent to reply(Status, [], [], Req).
reply/3Equivalent to reply(Status, Headers, [], Req).
reply/4Send a reply to the client.
set_meta/3Set metadata information.
set_resp_body/2Add a body to the response.
set_resp_body_fun/2Add a body stream function to the response.
set_resp_body_fun/3Add a body function to the response.
set_resp_cookie/4Add a cookie header to the response.
set_resp_header/3Add a header to the response.
skip_body/1
stream_body/1Stream the request's body.
to_list/1Convert the Req object to a list of key/values.
url/1Return the full request URL as a binary.
version/1Return the HTTP version used for the request.

Function Details

binding/2

binding(Name::atom(), Req) -> {binary() | undefined, Req}

Equivalent to binding(Name, Req, undefined).

binding/3

binding(Name::atom(), Req, Default) -> {binary() | Default, Req}

Return the binding value for the given key obtained when matching the host and path against the dispatch list, or a default if missing.

bindings/1

bindings(Req) -> {[{atom(), binary()}], Req}

Return the full list of binding values.

body/1

body(Req) -> {ok, binary(), Req} | {error, atom()}

Equivalent to body(8000000, Req).

body/2

body(MaxBodyLength::non_neg_integer() | infinity, Req) -> {ok, binary(), Req} | {error, atom()}

Return the body sent with the request.

body_length/1

body_length(Req) -> {undefined | non_neg_integer(), Req}

Return the request message body length, if known.

The length may not be known if Transfer-Encoding is not identity, and the body hasn't been read at the time of the call.

body_qs/1

body_qs(Req) -> {ok, [{binary(), binary() | true}], Req} | {error, atom()}

Equivalent to body_qs(16000, Req).

body_qs/2

body_qs(MaxBodyLength::non_neg_integer() | infinity, Req) -> {ok, [{binary(), binary() | true}], Req} | {error, atom()}

Return the body sent with the request, parsed as an application/x-www-form-urlencoded string. Essentially a POST query string.

chunk/2

chunk(Data::iodata(), Http_req::req()) -> ok | {error, atom()}

Send a chunk of data.

A chunked reply must have been initiated before calling this function.

chunked_reply/2

chunked_reply(Status::cowboy_http:status(), Req) -> {ok, Req}

Equivalent to chunked_reply(Status, [], Req).

chunked_reply/3

chunked_reply(Status::cowboy_http:status(), Headers::cowboy_http:headers(), Req) -> {ok, Req}

Initiate the sending of a chunked reply to the client.

See also: cowboy_req:chunk/2.

compact/1

compact(Req) -> Req

Compact the request data by removing all non-system information.

This essentially removes the host and path info, query string, bindings, headers and cookies.

Use it when you really need to save up memory, for example when having many concurrent long-running connections.

cookie/2

cookie(Name::binary(), Req) -> {binary() | true | undefined, Req}

Equivalent to cookie(Name, Req, undefined).

cookie/3

cookie(Name::binary(), Req, Default) -> {binary() | true | Default, Req}

Return the cookie value for the given key, or a default if missing.

cookies/1

cookies(Req) -> {[{binary(), binary() | true}], Req}

Return the full list of cookie values.

delete_resp_header/2

delete_resp_header(Name::binary(), Req) -> Req

fragment/1

fragment(Req) -> {binary(), Req}

Return the raw fragment directly taken from the request.

has_body/1

has_body(Req::cowboy_req:req()) -> boolean()

Return whether the request message has a body.

has_resp_body/1

has_resp_body(Http_req::req()) -> boolean()

Return whether a body has been set for the response.

has_resp_header/2

has_resp_header(Name::binary(), Http_req::req()) -> boolean()

Return whether the given header has been set for the response.

header/2

header(Name::binary(), Req) -> {binary() | undefined, Req}

Equivalent to header(Name, Req, undefined).

header/3

header(Name::binary(), Req, Default) -> {binary() | Default, Req}

Return the header value for the given key, or a default if missing.

headers/1

headers(Req) -> {cowboy_http:headers(), Req}

Return the full list of headers.

host/1

host(Req) -> {binary(), Req}

Return the host binary string.

host_info/1

host_info(Req) -> {cowboy_router:tokens() | undefined, Req}

Return the extra host information obtained from partially matching the hostname using '...'.

host_url/1

host_url(Req) -> {undefined | binary(), Req}

Return the request URL as a binary without the path and query string.

The URL includes the scheme, host and port only.

See also: cowboy_req:url/1.

init_stream/4

init_stream(TransferDecode::function(), TransferState::any(), ContentDecode::function(), Req) -> {ok, Req}

Equivalent to init_stream(1000000, TransferDecode, TransferState, ContentDecode, Req).

init_stream/5

init_stream(MaxLength::non_neg_integer(), TransferDecode::function(), TransferState::any(), ContentDecode::function(), Req) -> {ok, Req}

Initialize body streaming and set custom decoding functions.

Calling this function is optional. It should only be used if you need to override the default behavior of Cowboy. Otherwise you should call stream_body/1 directly.

Two decodings happen. First a decoding function is applied to the transferred data, and then another is applied to the actual content.

Transfer encoding is generally used for chunked bodies. The decoding function uses a state to keep track of how much it has read, which is also initialized through this function.

Content encoding is generally used for compression.

Standard encodings can be found in cowboy_http.

meta/2

meta(Name::atom(), Req) -> {any() | undefined, Req}

Equivalent to meta(Name, Req, undefined).

meta/3

meta(Name::atom(), Req, Default::any()) -> {any(), Req}

Return metadata information about the request.

Metadata information varies from one protocol to another. Websockets would define the protocol version here, while REST would use it to indicate which media type, language and charset were retained.

method/1

method(Req) -> {binary(), Req}

Return the HTTP method of the request.

multipart_data/1

multipart_data(Req) -> {headers, cowboy_http:headers(), Req} | {body, binary(), Req} | {end_of_part | eof, Req}

Return data from the multipart parser.

Use this function for multipart streaming. For each part in the request, this function returns {headers, Headers} followed by a sequence of {body, Data} tuples and finally end_of_part. When there is no part to parse anymore, eof is returned.

If the request Content-Type is not a multipart one, {error, badarg} is returned.

multipart_skip/1

multipart_skip(Req) -> {ok, Req}

Skip a part returned by the multipart parser.

This function repeatedly calls multipart_data/1 until end_of_part or eof is parsed.

parse_header/2

parse_header(Name::binary(), Req) -> {ok, any(), Req} | {undefined, binary(), Req} | {error, badarg}

Semantically parse headers.

When the value isn't found, a proper default value for the type returned is used as a return value.

See also: parse_header/3.

parse_header/3

parse_header(Name::binary(), Req, Default::any()) -> {ok, any(), Req} | {undefined, binary(), Req} | {error, badarg}

Semantically parse headers.

When the header is unknown, the value is returned directly without parsing.

path/1

path(Req) -> {binary(), Req}

Return the path binary string.

path_info/1

path_info(Req) -> {cowboy_router:tokens() | undefined, Req}

Return the extra path information obtained from partially matching the patch using '...'.

peer/1

peer(Req) -> {undefined | {inet:ip_address(), inet:port_number()}, Req}

Return the peer address and port number of the remote host.

peer_addr/1

peer_addr(Req) -> {inet:ip_address(), Req}

Returns the peer address calculated from headers.

port/1

port(Req) -> {inet:port_number(), Req}

Return the port used for this request.

qs/1

qs(Req) -> {binary(), Req}

Return the raw query string directly taken from the request.

qs_val/2

qs_val(Name::binary(), Req) -> {binary() | true | undefined, Req}

Equivalent to qs_val(Name, Req, undefined).

qs_val/3

qs_val(Name::binary(), Req, Default) -> {binary() | true | Default, Req}

Return the query string value for the given key, or a default if missing.

qs_vals/1

qs_vals(Req) -> {[{binary(), binary() | true}], Req}

Return the full list of query string values.

reply/2

reply(Status::cowboy_http:status(), Req) -> {ok, Req}

Equivalent to reply(Status, [], [], Req).

reply/3

reply(Status::cowboy_http:status(), Headers::cowboy_http:headers(), Req) -> {ok, Req}

Equivalent to reply(Status, Headers, [], Req).

reply/4

reply(Status::cowboy_http:status(), Headers::cowboy_http:headers(), Body::iodata() | {non_neg_integer() | resp_body_fun()}, Req) -> {ok, Req}

Send a reply to the client.

set_meta/3

set_meta(Name::atom(), Value::any(), Req) -> Req

Set metadata information.

You can use this function to attach information about the request.

If the value already exists it will be overwritten.

set_resp_body/2

set_resp_body(Body::iodata(), Req) -> Req

Add a body to the response.

The body set here is ignored if the response is later sent using anything other than reply/2 or reply/3. The response body is expected to be a binary or an iolist.

set_resp_body_fun/2

set_resp_body_fun(StreamFun::resp_body_fun(), Req) -> Req

Add a body stream function to the response.

The body set here is ignored if the response is later sent using anything other than reply/2 or reply/3.

Setting a response stream function without a length means that the body will be sent until the connection is closed. Cowboy will make sure that the connection is closed with no extra step required.

To inform the client that a body has been sent with this request, Cowboy will add a "Transfer-Encoding: identity" header to the response.

set_resp_body_fun/3

set_resp_body_fun(StreamLen::non_neg_integer(), StreamFun::resp_body_fun(), Req) -> Req

Add a body function to the response.

The body set here is ignored if the response is later sent using anything other than reply/2 or reply/3.

Cowboy will call the given response stream function after sending the headers. This function must send the specified number of bytes to the socket it will receive as argument.

If the body function crashes while writing the response body or writes fewer bytes than declared the behaviour is undefined.

set_resp_cookie/4

set_resp_cookie(Name::iodata(), Value::iodata(), Opts::cookie_opts(), Req) -> Req

Add a cookie header to the response.

The cookie name cannot contain any of the following characters: =,;\s\t\r\n\013\014

The cookie value cannot contain any of the following characters: ,; \t\r\n\013\014

set_resp_header/3

set_resp_header(Name::binary(), Value::iodata(), Req) -> Req

Add a header to the response.

skip_body/1

skip_body(Req) -> {ok, Req} | {error, atom()}

stream_body/1

stream_body(Req) -> {ok, binary(), Req} | {done, Req} | {error, atom()}

Stream the request's body.

This is the most low level function to read the request body.

In most cases, if they weren't defined before using stream_body/4, this function will guess which transfer and content encodings were used for building the request body, and configure the decoding functions that will be used when streaming.

It then starts streaming the body, returning {ok, Data, Req} for each streamed part, and {done, Req} when it's finished streaming.

to_list/1

to_list(Req::req()) -> [{atom(), any()}]

Convert the Req object to a list of key/values.

url/1

url(Req) -> {undefined | binary(), Req}

Return the full request URL as a binary.

The URL includes the scheme, host, port, path, query string and fragment.

version/1

version(Req) -> {cowboy_http:version(), Req}

Return the HTTP version used for the request.


Generated by EDoc, Aug 16 2014, 11:28:18.