forked from webmachine/webmachine
-
Notifications
You must be signed in to change notification settings - Fork 27
/
reqdata.html
143 lines (107 loc) · 8.5 KB
/
reqdata.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
<head>
<meta name="author" content="Basho Technologies" />
<meta name="description" content="Webmachine request/response data" />
<meta name="keywords" content="webmachine http rest web" />
<meta http-equiv="content-type" content="text/html;charset=utf-8" />
<link rel="stylesheet" href="css/style-1c.css" type="text/css" />
<title>Webmachine request/response data</title>
</head>
<body>
<div id="content">
<h1><span class="hr"></span><a href="/">webmachine</a></h1>
<ul id="top">
<li><a href="/">Home</a></li>
<li><a href="http://bitbucket.org/justin/webmachine/">Source Code</a></li>
<li><a href="contact.html">Contact</a></li>
</ul>
<div id="left">
<h3>Webmachine request/response data</h3>
<p>
This is documentation of the Webmachine Request Data API as embodied
by the <code>"wrq"</code> module. This module is the means by which
resources access and manipulate the state of the request they are
handling.
</p>
<p>
Given that all webmachine resource functions have this signature:
</p>
<span class="fwf">f(ReqData, Context) -> {Result, ReqData, Context}</span>
<p>
we should explain in detail the <code>ReqData</code> 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 <code>wrq</code> module is used to access the values in
the input parameter. Most functions in most resources have no need to
modify the output <code>ReqData</code> 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
<code>Result</code> and in those cases it should use the
<code>wrq</code> module to build a modified <code>ReqData</code> from
the original one for the return value.
</p>
<p>
A couple of nonstandard types are assumed here:
</p>
<table><tr><th>Type</th><th>Description</th></tr>
<tr><td>string()</td><td>a list() with all elements in the ASCII range</td></tr>
<tr><td>rd()</td><td>opaque record, used as the input/output <code>ReqData</code></td></tr>
<tr><td>streambody()</td><td>A webmachine <a href="streambody.html">streamed body format</a></td></tr>
<tr><td>mochiheaders()</td><td>a structure used in mochiweb for HTTP header storage</td></tr>
</table>
<p>The accessors are:</p>
<table><tr><th>Function</th><th>Description</th></tr>
<tr><td><code> method(rd()) -> 'DELETE' | 'GET' | 'HEAD' | 'OPTIONS' | 'POST' | 'PUT' | 'TRACE' </code></td><td>The HTTP method used by the client. (note that it is an <code> atom() </code>)</td></tr>
<tr><td><code> version(rd()) -> {integer(),integer()} </code></td><td>The HTTP version used by the client. Most often <code> {1,1} </code>.</td></tr>
<tr><td><code> peer(rd()) -> string() </code></td><td>The IP address of the client.</td></tr>
<tr><td><code> disp_path(rd()) -> string() </code></td><td>The "local" path of the resource URI; the part after any prefix used in <a href="dispatcher.html">dispatch configuration</a>. Of the three path accessors, this is the one you usually want. This is also the one that will change after <code>create_path</code> is called in your <a href="resources.html">resource</a>.</td></tr>
<tr><td><code> path(rd()) -> string() </code></td><td>The path part of the URI -- after the host and port, but not including any query string.</td></tr>
<tr><td><code> raw_path(rd()) -> string() </code></td><td>The entire path part of the URI, including any query string present.</td></tr>
<tr><td><code> path_info(atom(),rd()) -> 'undefined' | string() </code></td><td>Looks up a binding as described in <a href="dispatcher.html">dispatch configuration</a>.</td></tr>
<tr><td><code> path_info(rd()) -> any() </code></td><td>The dictionary of bindings as described in <a href="dispatcher.html">dispatch configuration</a>.</td></tr>
<tr><td><code> path_tokens(rd()) -> list() </code></td><td>This is a list of <code> string() </code> terms, the disp_path components split by "/".</td></tr>
<tr><td><code> get_req_header(string(),rd()) -> 'undefined' | string() </code></td><td>Look up the value of an incoming request header.</td></tr>
<tr><td><code> req_headers(rd()) -> mochiheaders() </code></td><td>The incoming HTTP headers. Generally, get_req_header is more useful.</td></tr>
<tr><td><code> req_body(rd()) -> 'undefined' | binary() </code></td><td>The incoming request body, if any.</td></tr>
<tr><td><code> stream_req_body(rd(),integer()) -> streambody() </code></td><td>The incoming request body in <a href="streambody.html">streamed</a> form, with hunks no bigger than the integer argument.</td></tr>
<tr><td><code> get_cookie_value(string(),rd()) -> string() </code></td><td>Look up the named value in the incoming request cookie header.</td></tr>
<tr><td><code> req_cookie(rd()) -> string() </code></td><td>The raw value of the cookie header. Note that get_cookie_value is often more useful.</td></tr>
<tr><td><code> get_qs_value(string(),rd()) -> 'undefined' | string() </code></td><td>Given the name of a key, look up the corresponding value in the query string.</td></tr>
<tr><td><code> get_qs_value(string(),string(),rd()) -> string() </code></td><td>Given the name of a key and a default value if not present, look up the corresponding value in the query string.</td></tr>
<tr><td><code> req_qs(rd()) -> [{string(), string()}] </code></td><td>The parsed query string, if any. Note that get_qs_value is often more useful.</td></tr>
<tr><td><code> get_resp_header(string(),rd()) -> string() </code></td><td>Look up the current value of an outgoing request header.</td></tr>
<tr><td><code> resp_redirect(rd()) -> bool() </code></td><td>the last value passed to do_redirect, false otherwise -- if true, then some responses will be 303 instead of 2xx where applicable</td></tr>
<tr><td><code> resp_headers(rd()) -> mochiheaders() </code></td><td>The outgoing HTTP headers. Generally, get_resp_header is more useful.</td></tr>
<tr><td><code> resp_body(rd()) -> 'undefined' | binary() </code></td><td>The outgoing response body, if one has been set. Usually, append_to_response_body is the best way to set this.</td></tr>
<tr><td><code> app_root(rd()) -> string() </code></td><td>Indicates the "height" above the requested URI that this resource is dispatched from. Typical values are <code> "." </code>, <code> ".." </code>, <code> "../.." </code> and so on.</td></tr>
</table>
<p
>The functions for (nondestructive) modification of <code> rd() </code> terms are:
</p>
<table><tr><th>Function</th><th>Description</th></tr>
<tr><td><code> set_resp_header(string(),string(),rd()) -> rd() </code></td><td>Given a header name and value, set an outgoing request header to that value.</td></tr>
<tr><td><code> append_to_response_body(binary(),rd()) -> rd() </code></td><td>Append the given value to the body of the outgoing response.</td></tr>
<tr><td><code> do_redirect(bool(),rd()) -> rd() </code></td><td>see resp_redirect; this sets that value.</td></tr>
<tr><td><code> set_disp_path(string(),rd()) -> rd() </code></td><td>The disp_path is the only path that can be changed during a request. This function will do so.</td></tr>
<tr><td><code> set_req_body(binary(),rd()) -> rd() </code></td><td>Replace the incoming request body with this for the rest of the processing.</td></tr>
<tr><td><code> set_resp_body(binary(),rd()) -> rd() </code></td><td>Set the outgoing response body to this value.</td></tr>
<tr><td><code> set_resp_body(streambody(),rd()) -> rd() </code></td><td>Use this <a href="streambody.html">streamed body</a> to produce the outgoing response body on demand.</td></tr>
<tr><td><code> set_resp_headers([{string(),string()}],rd()) -> rd() </code></td><td>Given a list of two-tuples of {headername,value}, set those outgoing response headers.</td></tr>
<tr><td><code> remove_resp_header(string(),rd()) -> rd() </code></td><td>Remove the named outgoing response header.</td></tr>
</table>
</div>
<div id="footer">
</div>
</div>
<script type="text/javascript">
var gaJsHost = (("https:" == document.location.protocol) ? "https://ssl." : "http://www.");
document.write(unescape("%3Cscript src='" + gaJsHost + "google-analytics.com/ga.js' type='text/javascript'%3E%3C/script%3E"));
</script>
<script type="text/javascript">
try {
var pageTracker = _gat._getTracker("UA-4979965-5");
pageTracker._trackPageview();
} catch(err) {}</script>
</body>
</html>