-
Notifications
You must be signed in to change notification settings - Fork 5
Request Data API
Marc Worrell edited this page Jul 25, 2019
·
7 revisions
This is documentation of the Cowmachine Request Data API as embodied
by the webmachine_req module. This module is the means by which controllers
access and manipulate the state of the request they are handling.
Given that all [[Cowmachine controller functions|Controller Functions] have the following signature:
f(Context) -> {Result, Context}The request Context argument and return value is one of:
- A map, then it is assumed to be a
cowboy_req:req()request map - A tuple, then the 2nd field must be the
cowboy_req:req()request map
Example of such a tuple definition:
-record(context, { req :: cowboy_req:req(), ... }.After the req you can add any fields for your application.
Cowmachine can modify the cowboy request in your request context state.
The request in the Context must only be accessed and manipulated
using the cowmachine_req functions.
Application specific fields in the Context record must be accessed
directly, without calling cowmachine_req functions.
A couple of nonstandard types are assumed here:
| Type | Description |
|---|---|
| context() | record (see above) or a cowboy_req:req() map |
| streambody() | A Cowmachine streamed body format |
| headers() | a structure used in Cowboy for HTTP header storage |
| Function | Description |
|---|---|
| method(context()) -> <<"GET">> <<"POST">>, <<"DELETE">>, ... | The HTTP method used by the client. |
| version(context()) -> {integer(),integer()} | The HTTP version used by the client. Most often {1,1} or {2,0}. |
| peer(context()) -> binary() | The IP address of the client. |
| disp_path(context()) -> binary() | The "local" path of the dispatched URI; the part after any prefix used in dispatching. Of the three path accessors, this is the one you usually want. This is also the one that will change after create_path is called in your controller functions. |
| path(context()) -> binary() | The path part of the URI -- after the host and port, but not including any query string. |
| raw_path(context()) -> binary() | The entire path part of the URI, including any query string present. |
| path_info(atom(),context()) -> 'undefined', binary() | Looks up a binding as described in [[dispatch configuration |
| path_info(context()) -> any() | The dictionary of bindings as described in [[dispatch configuration |
| path_tokens(context()) -> list() | This is a list of binary() terms, the disp_path components split by "/". |
| get_req_header(binary(),context()) -> 'undefined', binary() | Look up the value of an incoming request header. The header must be lower case (example: <<"content-type">>) |
| req_headers(context()) -> mochiheaders() | The incoming HTTP headers. Generally, get_req_header is more useful. |
| req_body(context()) -> 'undefined', binary() | The incoming request body, if any. |
| stream_req_body(context(),integer()) -> streambody() | The incoming request body in streamed form, with hunks no bigger than the integer argument. |
| get_cookie_value(binary(),context()) -> binary() | Look up the named value in the incoming request cookie header. |
| req_cookie(context()) -> binary() | The raw value of the cookie header. Note that get_cookie_value is often more useful. |
| get_qs_value(binary(),context()) -> 'undefined', binary() | Given the name of a key, look up the corresponding value in the query string. |
| get_qs_value(binary(),binary(),context()) -> binary() | Given the name of a key and a default value if not present, look up the corresponding value in the query string. |
| req_qs(context()) -> [{binary(), binary()}] | The parsed query string, if any. Note that get_qs_value is often more useful. |
| get_resp_header(binary(),context()) -> binary() | Look up the current value of an outgoing request header. |
| resp_redirect(context()) -> bool() | the last value passed to do_redirect, false otherwise -- if true, then some responses will be 303 instead of 2xx where applicable |
| resp_headers(context()) -> headers() | The outgoing HTTP headers. Generally, get_resp_header is more useful. |
| resp_body(context()) -> 'undefined', binary() | The outgoing response body, if one has been set. Usually, append_to_response_body is the best way to set this. |
The functions for (nondestructive) modification of context() terms are:
| Function | Description |
|---|---|
| set_resp_header(binary(),binary(),context()) -> context() | Given a header name and value, set an outgoing request header to that value. |
| set_disp_path(binary(),context()) -> context() | The disp_path is the only path that can be changed during a request. This function will do so. |
| set_req_body(binary(),context()) -> context() | Replace the incoming request body with this for the rest of the processing. |
| set_resp_body(binary(),context()) -> context() | Set the outgoing response body to this value. |
| set_resp_body(streambody(),context()) -> context() | Use this streamed body to produce the outgoing response body on demand. |
| set_resp_headers([{binary(),binary()}],context()) -> context() | Given a list of two-tuples of {headername,value}, set those outgoing response headers. |
| remove_resp_header(binary(),context()) -> context() | Remove the named outgoing response header. |