diff options
Diffstat (limited to 'doc/src/manual/cowboy_req.ezdoc')
-rw-r--r-- | doc/src/manual/cowboy_req.ezdoc | 715 |
1 files changed, 0 insertions, 715 deletions
diff --git a/doc/src/manual/cowboy_req.ezdoc b/doc/src/manual/cowboy_req.ezdoc deleted file mode 100644 index 9b73886..0000000 --- a/doc/src/manual/cowboy_req.ezdoc +++ /dev/null @@ -1,715 +0,0 @@ -::: cowboy_req - -The `cowboy_req` module provides functions to access, manipulate -and respond to requests. - -The functions in this module follow patterns for their return types, -based on the kind of function. - -* access: `Value` -* action: `ok | {Result, Req} | {Result, Value, Req}` -* modification: `Req` -* question: `boolean()` - -Whenever `Req` is returned, you must use this returned value and -ignore any previous you may have had. This value contains various -values which are necessary for Cowboy to keep track of the request -and response states. - -All functions which perform an action should only be called once. -This includes reading the request body or replying. Cowboy will -throw an error on the second call when it detects suspicious behavior. - -It is highly discouraged to pass the Req object to another process. -Doing so and calling `cowboy_req` functions from it leads to -undefined behavior. - -:: Types - -: body_opts() = [{continue, boolean()} - | {length, non_neg_integer()} - | {read_length, non_neg_integer()} - | {read_timeout, timeout()} - | {transfer_decode, transfer_decode_fun(), any()} - | {content_decode, content_decode_fun()}] - -Request body reading options. - -: cookie_opts() = [{max_age, non_neg_integer()} - | {domain, binary()} | {path, binary()} - | {secure, boolean()} | {http_only, boolean()}] - -Cookie options. - -: req() - opaque to the user - -The Req object. - -All functions in this module receive a `Req` as argument, -and most of them return a new object labelled `Req2` in -the function descriptions below. - -:: Request related exports - -: binding(Name, Req) -> binding(Name, Req, undefined) -: binding(Name, Req, Default) -> Value - -Types: - -* Name = atom() -* Default = any() -* Value = any() | Default - -Return the value for the given binding. - -By default the value is a binary, however constraints may change -the type of this value (for example automatically converting -numbers to integer). - -: bindings(Req) -> [{Name, Value}] - -Types: - -* Name = atom() -* Value = any() - -Return all bindings. - -By default the value is a binary, however constraints may change -the type of this value (for example automatically converting -numbers to integer). - -: header(Name, Req) -> header(Name, Req, undefined) -: header(Name, Req, Default) -> Value - -Types: - -* Name = binary() -* Default = any() -* Value = binary() | Default - -Return the value for the given header. - -While header names are case insensitive, this function expects -the name to be a lowercase binary. - -: headers(Req) -> Headers - -Types: - -* Headers = cowboy:http_headers() - -Return all headers. - -: host(Req) -> Host - -Types: - -* Host = binary() - -Return the requested host. - -: host_info(Req) -> HostInfo - -Types: - -* HostInfo = cowboy_router:tokens() | undefined - -Return the extra tokens from matching against `...` during routing. - -: host_url(Req) -> HostURL - -Types: - -* HostURL = binary() | undefined - -Return the requested URL excluding the path component. - -This function will always return `undefined` until the -`cowboy_router` middleware has been executed. - -: match_cookies(Fields, Req) -> Map - -Types: - -* Fields = cowboy:fields() -* Map = map() - -Match cookies against the given fields. - -Cowboy will only return the cookie values specified in the -fields list, and ignore all others. Fields can be either -the name of the cookie requested; the name along with a -list of constraints; or the name, a list of constraints -and a default value in case the cookie is missing. - -This function will crash if the cookie is missing and no -default value is provided. This function will also crash -if a constraint fails. - -The name of the cookie must be provided as an atom. The -key of the returned map will be that atom. The value may -be converted through the use of constraints, making this -function able to extract, validate and convert values all -in one step. - -: match_qs(Fields, Req) -> Map - -Types: - -* Fields = cowboy:fields() -* Map = map() - -Match the query string against the given fields. - -Cowboy will only return the query string values specified -in the fields list, and ignore all others. Fields can be -either the key requested; the key along with a list of -constraints; or the key, a list of constraints and a -default value in case the key is missing. - -This function will crash if the key is missing and no -default value is provided. This function will also crash -if a constraint fails. - -The key must be provided as an atom. The key of the -returned map will be that atom. The value may be converted -through the use of constraints, making this function able -to extract, validate and convert values all in one step. - -: meta(Name, Req) -> meta(Name, Req, undefined) -: meta(Name, Req, Default) -> Value - -Types: - -* Name = atom() -* Default = any() -* Value = any() - -Return metadata about the request. - -: method(Req) -> Method - -Types: - -* Method = binary() - -Return the method. - -Methods are case sensitive. Standard methods are always uppercase. - -: parse_cookies(Req) -> [{Name, Value}] - -Types: - -* Name = binary() -* Value = binary() - -Parse and return all cookies. - -Cookie names are case sensitive. - -: parse_header(Name, Req) -> see below -: parse_header(Name, Req, Default) -> ParsedValue | Default - -Types: - -* Name = binary() -* Default = any() -* ParsedValue - see below - -Parse the given header. - -While header names are case insensitive, this function expects -the name to be a lowercase binary. - -The `parse_header/2` function will call `parser_header/3` with a -different default value depending on the header being parsed. The -following table summarizes the default values used. - -|| Header name Default value -| -| content-length `0` -| cookie `[]` -| transfer-encoding `[<<"identity">>]` -| Any other header `undefined` - -The parsed value differs depending on the header being parsed. The -following table summarizes the different types returned. - -|| Header name Type -| -| accept `[{{Type, SubType, Params}, Quality, AcceptExt}]` -| accept-charset `[{Charset, Quality}]` -| accept-encoding `[{Encoding, Quality}]` -| accept-language `[{LanguageTag, Quality}]` -| authorization `{AuthType, Credentials}` -| content-length `non_neg_integer()` -| content-type `{Type, SubType, ContentTypeParams}` -| cookie `[{binary(), binary()}]` -| expect `[Expect | {Expect, ExpectValue, Params}]` -| if-match `'*' | [{weak | strong, OpaqueTag}]` -| if-modified-since `calendar:datetime()` -| if-none-match `'*' | [{weak | strong, OpaqueTag}]` -| if-unmodified-since `calendar:datetime()` -| range `{Unit, [Range]}` -| sec-websocket-protocol `[binary()]` -| transfer-encoding `[binary()]` -| upgrade `[binary()]` -| x-forwarded-for `[binary()]` - -Types for the above table: - -* Type = SubType = Charset = Encoding = LanguageTag = binary() -* AuthType = Expect = OpaqueTag = Unit = binary() -* Params = ContentTypeParams = [{binary(), binary()}] -* Quality = 0..1000 -* AcceptExt = [{binary(), binary()} | binary()] -* Credentials - see below -* Range = {non_neg_integer(), non_neg_integer() | infinity} | neg_integer() - -The cookie names and values, the values of the sec-websocket-protocol -and x-forwarded-for headers, the values in `AcceptExt` and `Params`, -the authorization `Credentials`, the `ExpectValue` and `OpaqueTag` -are case sensitive. All values in `ContentTypeParams` are case sensitive -except the value of the charset parameter, which is case insensitive. -All other values are case insensitive and will be returned as lowercase. - -The headers accept, accept-encoding and cookie headers can return -an empty list. Some other headers are expected to have a value if provided -and may crash if the value is missing. - -The authorization header parsing code currently only supports basic -HTTP authentication. The `Credentials` type is thus `{Username, Password}` -with `Username` and `Password` being `binary()`. - -The range header value `Range` can take three forms: - -* `{From, To}`: from `From` to `To` units -* `{From, infinity}`: everything after `From` units -* `-Final`: the final `Final` units - -An `undefined` tuple will be returned if Cowboy doesn't know how -to parse the requested header. - -: parse_qs(Req) -> [{Name, Value}] - -Types: - -* Name = binary() -* Value = binary() | true - -Return the request's query string as a list of tuples. - -The atom `true` is returned for keys which have no value. -Keys with no value are different from keys with an empty -value in that they do not have a `=` indicating the presence -of a value. - -: path(Req) -> Path - -Types: - -* Path = binary() - -Return the requested path. - -: path_info(Req) -> PathInfo - -Types: - -* PathInfo = cowboy_router:tokens() | undefined - -Return the extra tokens from matching against `...` during routing. - -: peer(Req) -> Peer - -Types: - -* Peer = {inet:ip_address(), inet:port_number()} - -Return the client's IP address and port number. - -: port(Req) -> Port - -Types: - -* Port = inet:port_number() - -Return the request's port. - -The port returned by this function is obtained by parsing -the host header. It may be different than the actual port -the client used to connect to the Cowboy server. - -: qs(Req) -> QueryString - -Types: - -* QueryString = binary() - -Return the request's query string. - -: set_meta(Name, Value, Req) -> Req2 - -Types: - -* Name = atom() -* Value = any() - -Set metadata about the request. - -An existing value will be overwritten. - -: url(Req) -> URL - -Types: - -* URL = binary() | undefined - -Return the requested URL. - -This function will always return `undefined` until the -`cowboy_router` middleware has been executed. - -: version(Req) -> Version - -Types: - -* Version = cowboy:http_version() - -Return the HTTP version used for this request. - -:: Request body related exports - -: body(Req) -> body(Req, []) -: body(Req, Opts) -> {ok, Data, Req2} | {more, Data, Req2} - -Types: - -* Opts = [body_opt()] -* Data = binary() -* Reason = atom() - -Read the request body. - -This function will read a chunk of the request body. If there is -more data to be read after this function call, then a `more` tuple -is returned. Otherwise an `ok` tuple is returned. - -Cowboy will automatically send a `100 Continue` reply if -required. If this behavior is not desirable, it can be disabled -by setting the `continue` option to `false`. - -Cowboy will by default attempt to read up to 8MB of the body, -but in chunks of 1MB. It will use a timeout of 15s per chunk. -All these values can be changed using the `length`, `read_length` -and `read_timeout` options respectively. Note that the size -of the data may not be the same as requested as the decoding -functions may grow or shrink it, and Cowboy makes not attempt -at returning an exact amount. - -Cowboy will properly handle chunked transfer-encoding by -default. If any other transfer-encoding or content-encoding -has been used for the request, custom decoding functions -can be used. The `content_decode` and `transfer_decode` -options allow setting the decode functions manually. - -After the body has been streamed fully, Cowboy will remove -the transfer-encoding header from the Req object, and add -the content-length header if it wasn't already there. - -This function can only be called once. Cowboy will not cache -the result of this call. - -: body_length(Req) -> Length - -Types: - -* Length = non_neg_integer() | undefined - -Return the length of the request body. - -The length will only be returned if the request does not -use any transfer-encoding and if the content-length header -is present. - -: body_qs(Req) -> body_qs(Req, - [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}]) -: body_qs(Req, Opts) -> {ok, [{Name, Value}], Req2} | {badlength, Req2} - -Types: - -* Opts = [body_opt()] -* Name = binary() -* Value = binary() | true -* Reason = chunked | badlength | atom() - -Return the request body as a list of tuples. - -This function will parse the body assuming the content-type -application/x-www-form-urlencoded, commonly used for the -query string. - -This function calls `body/2` for reading the body, with the -same options it received. By default it will attempt to read -a body of 64KB in one chunk, with a timeout of 5s. If the -body is larger then a `badlength` tuple is returned. - -This function can only be called once. Cowboy will not cache -the result of this call. - -: has_body(Req) -> boolean() - -Return whether the request has a body. - -: part(Req) -> part(Req, - [{length, 64000}, {read_length, 64000}, {read_timeout, 5000}]) -: part(Req, Opts) -> {ok, Headers, Req2} | {done, Req2} - -Types: - -* Opts = [body_opt()] -* Headers = cow_multipart:headers() - -Read the headers for the next part of the multipart message. - -Cowboy will skip any data remaining until the beginning of -the next part. This includes the preamble to the multipart -message but also the body of a previous part if it hasn't -been read. Both are skipped automatically when calling this -function. - -The headers returned are MIME headers, NOT HTTP headers. -They can be parsed using the functions from the `cow_multipart` -module. In addition, the `cow_multipart:form_data/1` function -can be used to quickly figure out `multipart/form-data` messages. -It takes the list of headers and returns whether this part is -a simple form field or a file being uploaded. - -Note that once a part has been read, or skipped, it cannot -be read again. - -This function calls `body/2` for reading the body, with the -same options it received. By default it will only read chunks -of 64KB with a timeout of 5s. This is tailored for reading -part headers, not for skipping the previous part's body. -You might want to consider skipping large parts manually. - -: part_body(Req) -> part_body(Req, []) -: part_body(Req, Opts) -> {ok, Data, Req2} | {more, Data, Req2} - -Types: - -* Opts = [body_opt()] -* Data = binary() - -Read the body of the current part of the multipart message. - -This function calls `body/2` for reading the body, with the -same options it received. It uses the same defaults. - -If there are more data to be read from the socket for this -part, the function will return what it could read inside a -`more` tuple. Otherwise, it will return an `ok` tuple. - -Calling this function again after receiving a `more` tuple -will return another chunk of body. The last chunk will be -returned inside an `ok` tuple. - -Note that once the body has been read, fully or partially, -it cannot be read again. - -:: Response related exports - -: chunk(Data, Req) -> ok - -Types: - -* Data = iodata() -* Reason = atom() - -Send a chunk of data. - -This function should be called as many times as needed -to send data chunks after calling `chunked_reply/{2,3}`. - -When the method is HEAD, no data will actually be sent. - -If the request uses HTTP/1.0, the data is sent directly -without wrapping it in an HTTP/1.1 chunk, providing -compatibility with older clients. - -: chunked_reply(StatusCode, Req) -> chunked_reply(StatusCode, [], Req) -: chunked_reply(StatusCode, Headers, Req) -> Req2 - -Types: - -* StatusCode = cowboy:http_status() -* Headers = cowboy:http_headers() - -Send a response using chunked transfer-encoding. - -This function effectively sends the response status line -and headers to the client. - -This function will not send any body set previously. After -this call the handler must use the `chunk/2` function -repeatedly to send the body in as many chunks as needed. - -If the request uses HTTP/1.0, the data is sent directly -without wrapping it in an HTTP/1.1 chunk, providing -compatibility with older clients. - -This function can only be called once, with the exception -of overriding the response in the `onresponse` hook. - -: continue(Req) -> ok - -Types: - -* Reason = atom() - -Send a 100 Continue intermediate reply. - -This reply is required before the client starts sending the -body when the request contains the `expect` header with the -`100-continue` value. - -Cowboy will send this automatically when required. However -you may want to do it manually by disabling this behavior -with the `continue` body option and then calling this -function. - -: delete_resp_header(Name, Req) -> Req2 - -Types: - -* Name = binary() - -Delete the given response header. - -While header names are case insensitive, this function expects -the name to be a lowercase binary. - -: has_resp_body(Req) -> boolean() - -Return whether a response body has been set. - -This function will return false if a response body has -been set with a length of 0. - -: has_resp_header(Name, Req) -> boolean() - -Types: - -* Name = binary() - -Return whether the given response header has been set. - -While header names are case insensitive, this function expects -the name to be a lowercase binary. - -: reply(StatusCode, Req) -> reply(StatusCode, [], Req) -: reply(StatusCode, Headers, Req) - see below -: reply(StatusCode, Headers, Body, Req) -> Req2 - -Types: - -* StatusCode = cowboy:http_status() -* Headers = cowboy:http_headers() -* Body = iodata() - -Send a response. - -This function effectively sends the response status line, -headers and body to the client, in a single send function -call. - -The `reply/2` and `reply/3` functions will send the body -set previously, if any. The `reply/4` function overrides -any body set previously and sends `Body` instead. - -If a body function was set, and `reply/2` or `reply/3` was -used, it will be called before returning. - -No more data can be sent to the client after this function -returns. - -This function can only be called once, with the exception -of overriding the response in the `onresponse` hook. - -: set_resp_body(Body, Req) -> Req2 - -Types: - -* Body = iodata() - -Set a response body. - -This body will not be sent if `chunked_reply/{2,3}` or -`reply/4` is used, as they override it. - -: set_resp_body_fun(Fun, Req) -> Req2 -: set_resp_body_fun(Length, Fun, Req) -> Req2 - -Types: - -* Fun = fun((Socket, Transport) -> ok) -* Socket = inet:socket() -* Transport = module() -* Length = non_neg_integer() - -Set a fun for sending the response body. - -If a `Length` is provided, it will be sent in the -content-length header in the response. It is recommended -to set the length if it can be known in advance. Otherwise, -the transfer-encoding header will be set to identity. - -This function will only be called if the response is sent -using the `reply/2` or `reply/3` function. - -The fun will receive the Ranch `Socket` and `Transport` as -arguments. Only send and sendfile operations are supported. - -: set_resp_body_fun(chunked, Fun, Req) -> Req2 - -Types: - -* Fun = fun((ChunkFun) -> ok) -* ChunkFun = fun((iodata()) -> ok) - -Set a fun for sending the response body using chunked transfer-encoding. - -This function will only be called if the response is sent -using the `reply/2` or `reply/3` function. - -The fun will receive another fun as argument. This fun is to -be used to send chunks in a similar way to the `chunk/2` function, -except the fun only takes one argument, the data to be sent in -the chunk. - -: set_resp_cookie(Name, Value, Opts, Req) -> Req2 - -Types: - -* Name = iodata() -* Value = iodata() -* Opts = cookie_opts() - -Set a cookie in the response. - -Cookie names are case sensitive. - -: set_resp_header(Name, Value, Req) -> Req2 - -Types: - -* Name = binary() -* Value = iodata() - -Set a response header. - -You should use `set_resp_cookie/4` instead of this function -to set cookies. |