HTTP request manipulation API.
The functions in this module try to follow this pattern for their return types: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.cookie_option() = {max_age, non_neg_integer()} | {domain, binary()} | {path, binary()} | {secure, boolean()} | {http_only, boolean()}
cookie_opts() = [cookie_option()]
abstract datatype: req()
resp_body_fun() = fun((inet:socket(), module()) -> ok)
binding/2 | Equivalent to binding(Name, Req, undefined). |
binding/3 | 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 | Return the full list of binding values. |
body/1 | Equivalent to body(8000000, Req). |
body/2 | Return the body sent with the request. |
body_length/1 | Return the request message body length, if known. |
body_qs/1 | Equivalent to body_qs(16000, Req). |
body_qs/2 | Return the body sent with the request, parsed as an application/x-www-form-urlencoded string. |
chunk/2 | Send a chunk of data. |
chunked_reply/2 | Equivalent to chunked_reply(Status, [], Req). |
chunked_reply/3 | Initiate the sending of a chunked reply to the client. |
compact/1 | Compact the request data by removing all non-system information. |
cookie/2 | Equivalent to cookie(Name, Req, undefined). |
cookie/3 | Return the cookie value for the given key, or a default if missing. |
cookies/1 | Return the full list of cookie values. |
delete_resp_header/2 | |
fragment/1 | Return the raw fragment directly taken from the request. |
has_body/1 | Return whether the request message has a body. |
has_resp_body/1 | Return whether a body has been set for the response. |
has_resp_header/2 | Return whether the given header has been set for the response. |
header/2 | Equivalent to header(Name, Req, undefined). |
header/3 | Return the header value for the given key, or a default if missing. |
headers/1 | Return the full list of headers. |
host/1 | Return the host binary string. |
host_info/1 | Return the extra host information obtained from partially matching the hostname using '...'. |
host_url/1 | Return the request URL as a binary without the path and query string. |
init_stream/4 | Equivalent to init_stream(1000000, TransferDecode, TransferState, ContentDecode, Req). |
init_stream/5 | Initialize body streaming and set custom decoding functions. |
meta/2 | Equivalent to meta(Name, Req, undefined). |
meta/3 | Return metadata information about the request. |
method/1 | Return the HTTP method of the request. |
multipart_data/1 | Return data from the multipart parser. |
multipart_skip/1 | Skip a part returned by the multipart parser. |
parse_header/2 | Semantically parse headers. |
parse_header/3 | Semantically parse headers. |
path/1 | Return the path binary string. |
path_info/1 | Return the extra path information obtained from partially matching the patch using '...'. |
peer/1 | Return the peer address and port number of the remote host. |
peer_addr/1 | Returns the peer address calculated from headers. |
port/1 | Return the port used for this request. |
qs/1 | Return the raw query string directly taken from the request. |
qs_val/2 | Equivalent to qs_val(Name, Req, undefined). |
qs_val/3 | Return the query string value for the given key, or a default if missing. |
qs_vals/1 | Return the full list of query string values. |
reply/2 | Equivalent to reply(Status, [], [], Req). |
reply/3 | Equivalent to reply(Status, Headers, [], Req). |
reply/4 | Send a reply to the client. |
set_meta/3 | Set metadata information. |
set_resp_body/2 | Add a body to the response. |
set_resp_body_fun/2 | Add a body stream function to the response. |
set_resp_body_fun/3 | Add a body function to the response. |
set_resp_cookie/4 | Add a cookie header to the response. |
set_resp_header/3 | Add a header to the response. |
skip_body/1 | |
stream_body/1 | Stream the request's body. |
to_list/1 | Convert the Req object to a list of key/values. |
url/1 | Return the full request URL as a binary. |
version/1 | Return the HTTP version used for the request. |
binding(Name::atom(), Req) -> {binary() | undefined, Req}
Equivalent to binding(Name, Req, undefined).
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(Req) -> {[{atom(), binary()}], Req}
Return the full list of binding values.
body(Req) -> {ok, binary(), Req} | {error, atom()}
Equivalent to body(8000000, Req).
body(MaxBodyLength::non_neg_integer() | infinity, Req) -> {ok, binary(), Req} | {error, atom()}
Return the body sent with the request.
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(Req) -> {ok, [{binary(), binary() | true}], Req} | {error, atom()}
Equivalent to body_qs(16000, Req).
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(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(Status::cowboy_http:status(), Req) -> {ok, Req}
Equivalent to chunked_reply(Status, [], Req).
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(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(Name::binary(), Req) -> {binary() | true | undefined, Req}
Equivalent to cookie(Name, Req, undefined).
cookie(Name::binary(), Req, Default) -> {binary() | true | Default, Req}
Return the cookie value for the given key, or a default if missing.
cookies(Req) -> {[{binary(), binary() | true}], Req}
Return the full list of cookie values.
delete_resp_header(Name::binary(), Req) -> Req
fragment(Req) -> {binary(), Req}
Return the raw fragment directly taken from the request.
has_body(Req::cowboy_req:req()) -> boolean()
Return whether the request message has a body.
has_resp_body(Http_req::req()) -> boolean()
Return whether a body has been set for the response.
has_resp_header(Name::binary(), Http_req::req()) -> boolean()
Return whether the given header has been set for the response.
header(Name::binary(), Req) -> {binary() | undefined, Req}
Equivalent to header(Name, Req, undefined).
header(Name::binary(), Req, Default) -> {binary() | Default, Req}
Return the header value for the given key, or a default if missing.
headers(Req) -> {cowboy_http:headers(), Req}
Return the full list of headers.
host(Req) -> {binary(), Req}
Return the host binary string.
host_info(Req) -> {cowboy_router:tokens() | undefined, Req}
Return the extra host information obtained from partially matching the hostname using '...'.
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(TransferDecode::function(), TransferState::any(), ContentDecode::function(), Req) -> {ok, Req}
Equivalent to init_stream(1000000, TransferDecode, TransferState, ContentDecode, Req).
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(Name::atom(), Req) -> {any() | undefined, Req}
Equivalent to meta(Name, Req, undefined).
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(Req) -> {binary(), Req}
Return the HTTP method of the request.
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(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(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(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(Req) -> {binary(), Req}
Return the path binary string.
path_info(Req) -> {cowboy_router:tokens() | undefined, Req}
Return the extra path information obtained from partially matching the patch using '...'.
peer(Req) -> {undefined | {inet:ip_address(), inet:port_number()}, Req}
Return the peer address and port number of the remote host.
peer_addr(Req) -> {inet:ip_address(), Req}
Returns the peer address calculated from headers.
port(Req) -> {inet:port_number(), Req}
Return the port used for this request.
qs(Req) -> {binary(), Req}
Return the raw query string directly taken from the request.
qs_val(Name::binary(), Req) -> {binary() | true | undefined, Req}
Equivalent to qs_val(Name, Req, undefined).
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(Req) -> {[{binary(), binary() | true}], Req}
Return the full list of query string values.
reply(Status::cowboy_http:status(), Req) -> {ok, Req}
Equivalent to reply(Status, [], [], Req).
reply(Status::cowboy_http:status(), Headers::cowboy_http:headers(), Req) -> {ok, Req}
Equivalent to reply(Status, Headers, [], Req).
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(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(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(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(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(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\014set_resp_header(Name::binary(), Value::iodata(), Req) -> Req
Add a header to the response.
skip_body(Req) -> {ok, Req} | {error, atom()}
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(Req::req()) -> [{atom(), any()}]
Convert the Req object to a list of key/values.
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(Req) -> {cowboy_http:version(), Req}
Return the HTTP version used for the request.
Generated by EDoc, Aug 16 2014, 11:28:18.