man cowboy_req.txt

cowboy_req(3)             Cowboy Function Reference             cowboy_req(3)

NAME
       cowboy_req - HTTP request and response

DESCRIPTION
       The  module  cowboy_req  provides  functions to access, manipulate and
       respond to requests.

       There are four types of functions in this module. They can be  differ‐
       entiated by their name and their return type:

       ┌─────────────┬─────────────────────┬─────────────────────┐
       │Type         │ Name pattern        │ Return type         │
       ├─────────────┼─────────────────────┼─────────────────────┤
       │access       │ no  verb,  parse_*, │ Value               │
       │             │ match_*             │                     │
       ├─────────────┼─────────────────────┼─────────────────────┤
       │question     │ has_*               │ boolean()           │
       ├─────────────┼─────────────────────┼─────────────────────┤
       │modification │ set_*               │ Req                 │
       ├─────────────┼─────────────────────┼─────────────────────┤
       │action       │ any other verb      │ ok  {Result, Value, │
       │             │                     │ Req}                │
       └─────────────┴─────────────────────┴─────────────────────┘

       Any  Req returned must be used in place of the one passed as argument.
       Functions that perform an action in particular write state in the  Req
       object to make sure you are using the function correctly. For example,
       it's only possible to send one response, and to read the body once.

EXPORTS
       Raw request:

       · cowboy_req:method(3) - HTTP method
       · cowboy_req:version(3) - HTTP version
       · cowboy_req:scheme(3) - URI scheme
       · cowboy_req:host(3) - URI host name
       · cowboy_req:port(3) - URI port number
       · cowboy_req:path(3) - URI path
       · cowboy_req:qs(3) - URI query string
       · cowboy_req:uri(3) - Reconstructed URI
       · cowboy_req:header(3) - Raw HTTP header value
       · cowboy_req:headers(3) - Raw HTTP headers
       · cowboy_req:peer(3) - Peer address and port

       Processed request:

       · cowboy_req:parse_qs(3) - Parse the query string
       · cowboy_req:match_qs(3) - Match the query string against constraints
       · cowboy_req:parse_header(3) - Parse the given HTTP header
       · cowboy_req:parse_cookies(3) - Parse cookie headers
       · cowboy_req:match_cookies(3) - Match cookies against constraints
       · cowboy_req:binding(3) - Access a value bound from the route
       · cowboy_req:bindings(3) - Access all values bound from the route
       · cowboy_req:host_info(3) - Access the route's heading host segments
       · cowboy_req:path_info(3) - Access the route's trailing path segments

       Request body:

       · cowboy_req:has_body(3) - Is there a request body?
       · cowboy_req:body_length(3) - Body length
       · cowboy_req:read_body(3) - Read the request body
       · cowboy_req:read_urlencoded_body(3) - Read  and  parse  a  urlencoded
         request body
       · cowboy_req:read_part(3) - Read the next part of a multipart body
       · cowboy_req:read_part_body(3)  -  Read  the  current part's body in a
         multipart body

       Response:

       · cowboy_req:set_resp_cookie(3) - Set a cookie
       · cowboy_req:set_resp_header(3) - Set a response header
       · cowboy_req:has_resp_header(3) - Is the given response header set?
       · cowboy_req:delete_resp_header(3) - Delete a response header
       · cowboy_req:set_resp_body(3) - Set the response body
       · cowboy_req:has_resp_body(3) - Is there a response body?
       · cowboy_req:reply(3) - Send the response
       · cowboy_req:stream_reply(3) - Send the response and stream its body
       · cowboy_req:stream_body(3) - Send a chunk of the response body
       · cowboy_req:push(3) - Push a resource to the client

TYPES
   push_opts()
           push_opts() :: #{
               method => binary(),            %% case sensitive
               scheme => binary(),            %% lowercase; case insensitive
               host   => binary(),            %% lowercase; case insensitive
               port   => inet:port_number(),
               qs     => binary()             %% case sensitive
           }

       Push options.

       By default, Cowboy will use the GET method, an empty query string, and
       take  the  scheme,  host  and port directly from the current request's
       URI.

   read_body_opts()
           read_body_opts() :: #{
               length  => non_neg_integer(),
               period  => non_neg_integer(),
               timeout => timeout()
           }

       Body reading options.

       The defaults are function-specific.

   req()
           req() :: #{
               method  := binary(),               %% case sensitive
               version := cowboy:http_version() | atom(),
               scheme  := binary(),               %% lowercase; case insensitive
               host    := binary(),               %% lowercase; case insensitive
               port    := inet:port_number(),
               path    := binary(),               %% case sensitive
               qs      := binary(),               %% case sensitive
               headers := cowboy:http_headers(),
               peer    := {inet:ip_address(), inet:port_number()}
           }

       The Req object.

       Contains information about the request and response. While some fields
       are publicly documented, others aren't and shouldn't be used.

       You  may add custom fields if required. Make sure to namespace them by
       prepending an underscore and the name of your application:

       Setting a custom field
           Req#{_myapp_auth_method => pubkey}.

   resp_body()
           resp_body() :: iodata()
               | {sendfile, Offset, Length, Filename}

           Offset   :: non_neg_integer()
           Length   :: pos_integer()
           Filename :: file:name_all()

       Response body.

       It can take two forms: the actual data to be sent or a tuple  indicat‐
       ing which file to send.

       When  sending data directly, the type is either a binary or an iolist.
       Iolists are an efficient way to build output. Instead of concatenating
       strings  or binaries, you can simply build a list containing the frag‐
       ments you want to send in the order they should be sent:

       Example iolists usage
           1> RespBody = ["Hello ", [<<"world">>, $!]].
           ["Hello ",[<<"world">>,33]]
           2> io:format("~s~n", [RespBody]).
           Hello world!

       When using the sendfile tuple, the Length value is mandatory and  must
       be  higher  than 0. It is sent with the response in the content-length
       header.

SEE ALSO
       cowboy(7)

Cowboy 2.0                        1984-10-28                    cowboy_req(3)