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:

TypeDescription
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:

FunctionDescription
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:

FunctionDescription
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.