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 ReqDatainput 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 wrqmodule is used to access the values in the input parameter. Most functions in most resources have no need to modify the output ReqDataand 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 Resultand in those cases it should use the wrqmodule to build a modified ReqDatafrom 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_resp_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_resp_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.