webmachine
Webmachine request/response data
This is documentation of the Webmachine Request Data API as embodied
by the "wrq" module. This module is the means by which
resources access and manipulate the state of the request they are
handling.
Given that all webmachine resource functions have this signature:
f(ReqData, Context) -> {Result, ReqData, Context}
we should explain in detail the ReqData input and output
parameter. This is a data structure used to represent the request
sent by the client as well as the response being built by the
resource. The wrq module is used to access the values in
the input parameter. Most functions in most resources have no need to
modify the output ReqData and can simply pass along the
one received as input. However, in some cases a resource will need to
make some update to the response other than that implied by
Result and in those cases it should use the
wrq module to build a modified ReqData from
the original one for the return value.
A couple of nonstandard types are assumed here:
| Type | Description |
|---|---|
| string() | a list() with all elements in the ASCII range |
| rd() | opaque record, used as the input/output ReqData |
| streambody() | A webmachine streamed body format |
| mochiheaders() | a structure used in mochiweb for HTTP header storage |
The accessors are:
| Function | Description |
|---|---|
method(rd()) -> 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'POST' | 'PUT' | 'TRACE' | The HTTP method used by the client. (note that it is an atom() ) |
version(rd()) -> {integer(),integer()} | The HTTP version used by the client. Most often {1,1} . |
peer(rd()) -> string() | The IP address of the client. |
disp_path(rd()) -> string() | The "local" path of the resource URI; the part after any prefix used in dispatch configuration. 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 resource. |
path(rd()) -> string() | The path part of the URI -- after the host and port, but not including any query string. |
raw_path(rd()) -> string() | The entire path part of the URI, including any query string present. |
path_info(atom(),rd()) -> 'undefined' | string() | Looks up a binding as described in dispatch configuration. |
path_info(rd()) -> any() | The dictionary of bindings as described in dispatch configuration. |
path_tokens(rd()) -> list() | This is a list of string() terms, the disp_path components split by "/". |
get_req_header(string(),rd()) -> 'undefined' | string() | Look up the value of an incoming request header. |
req_headers(rd()) -> mochiheaders() | The incoming HTTP headers. Generally, get_req_header is more useful. |
req_body(rd()) -> 'undefined' | binary() | The incoming request body, if any. |
stream_req_body(rd(),integer()) -> streambody() | The incoming request body in streamed form, with hunks no bigger than the integer argument. |
get_cookie_value(string(),rd()) -> string() | Look up the named value in the incoming request cookie header. |
req_cookie(rd()) -> string() | The raw value of the cookie header. Note that get_cookie_value is often more useful. |
get_qs_value(string(),rd()) -> 'undefined' | string() | Given the name of a key, look up the corresponding value in the query string. |
get_qs_value(string(),string(),rd()) -> string() | Given the name of a key and a default value if not present, look up the corresponding value in the query string. |
req_qs(rd()) -> [{string(), string()}] | The parsed query string, if any. Note that get_qs_value is often more useful. |
get_resp_header(string(),rd()) -> string() | Look up the current value of an outgoing request header. |
resp_redirect(rd()) -> 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(rd()) -> mochiheaders() | The outgoing HTTP headers. Generally, get_resp_header is more useful. |
resp_body(rd()) -> 'undefined' | binary() | The outgoing response body, if one has been set. Usually, append_to_response_body is the best way to set this. |
app_root(rd()) -> string() | Indicates the "height" above the requested URI that this resource is dispatched from. Typical values are "." , ".." , "../.." and so on. |
The functions for (nondestructive) modification of rd() terms are:
| Function | Description |
|---|---|
set_resp_header(string(),string(),rd()) -> rd() | Given a header name and value, set an outgoing request header to that value. |
append_to_response_body(binary(),rd()) -> rd() | Append the given value to the body of the outgoing response. |
do_redirect(bool(),rd()) -> rd() | see resp_redirect; this sets that value. |
set_disp_path(string(),rd()) -> rd() | The disp_path is the only path that can be changed during a request. This function will do so. |
set_req_body(binary(),rd()) -> rd() | Replace the incoming request body with this for the rest of the processing. |
set_resp_body(binary(),rd()) -> rd() | Set the outgoing response body to this value. |
set_resp_body(streambody(),rd()) -> rd() | Use this streamed body to produce the outgoing response body on demand. |
set_resp_headers([{string(),string()}],rd()) -> rd() | Given a list of two-tuples of {headername,value}, set those outgoing response headers. |
remove_resp_header(string(),rd()) -> rd() | Remove the named outgoing response header. |