Merge pull request #1252 from h2o/kazuho/restore-1221-doc

restore doc for `%{...}e`

doc/configure/access_log_directives.html

@@ -145,6 +145,7 @@ <h3><a href="configure/access_log_directives.html#access-log"><code>"access-log"
 <tr><td><code>%u</code><td>remote user if the request was authenticated (always <code>-</code>)
 <tr><td><code>%V</code><td>requested server name (or the default server name if not specified by the client)
 <tr><td><code>%v</code><td>canonical server name
+<tr><td><code>%{<i>VARNAME</i>}e</code><td>request environment variable (since version 2.3; see <a href="configure/mruby.html#logging-arbitrary-variable">Logging Arbitrary Variable</a>)
 <tr><td><code>%{<i>HEADERNAME</i>}i</code><td>value of the given request header (e.g. <code>%{user-agent}i</code>)
 <tr><td><code>%{<i>HEADERNAME</i>}o</code><td>value of the given response header sent to client (e.g. <code>%{set-cookie}o</code>)
 <tr><td><code>%&lt;{<i>HEADERNAME</i>}o</code><td>value of the response header received from upstream (or initially generated)

doc/configure/mruby.html

@@ -238,6 +238,36 @@ <h3 id="http-client">Using the HTTP Client</h3>
 When HTTPS is used, servers are verified using the properties of <a href="configure/proxy_directives.html#proxy.ssl.cafile"><code>proxy.ssl.cafile</code></a> and <a href="configure/proxy_directives.html#proxy.ssl.verify-peer"><code>proxy.ssl.verify-peer</code></a> specified at the global level.
 </p>
 
+<h3 id="logging-arbitrary-variable">Logging Arbitrary Variable</h3>
+
+<p>
+In version 2.3, it is possible from mruby to set and log an arbitrary-named variable that is associated to a HTTP request.
+A HTTP response header that starts with <code>x-fallthru-set-</code> is handled specially by the H2O server. Instead of sending the header downstream, the server accepts the value as a request environment variable, taking the suffix of the header name as the name of the variable.
+</p>
+<p>
+This example shows how to read request data, parse json and then log data from mruby.
+</p>
+
+<div class="example">
+<div class="caption">Example. Logging the content of a POST request via request environment variable</div>
+<pre><code>paths:
+  &quot;/&quot;:
+    mruby.handler: |
+      Proc.new do |env|
+        input = env[&quot;rack.input&quot;] ? env[&quot;rack.input&quot;].read : &#39;{&quot;default&quot;: &quot;true&quot;}&#39;
+        parsed_json = JSON.parse(input)
+        parsed_json[&quot;time&quot;] = Time.now.to_i
+        logdata = parsed_json.to_s
+        [204, {&quot;x-fallthru-set-POSTDATA&quot; =&gt; logdata}, []]
+      end
+    access-log:
+      path: /path/to/access-log.json
+      escape: json
+      format: &#39;{&quot;POST&quot;: %{POSTDATA}e}&#39;
+</code></pre>
+</div>
+
+
 
 
 

srcdoc/configure/access_log_directives.mt

@@ -81,6 +81,7 @@ As an example, it is possible to log timestamps in millisecond resolution using
 <tr><td><code>%u</code><td>remote user if the request was authenticated (always <code>-</code>)
 <tr><td><code>%V</code><td>requested server name (or the default server name if not specified by the client)
 <tr><td><code>%v</code><td>canonical server name
+<tr><td><code>%{<i>VARNAME</i>}e</code><td>request environment variable (since version 2.3; see <a href="configure/mruby.html#logging-arbitrary-variable">Logging Arbitrary Variable</a>)
 <tr><td><code>%{<i>HEADERNAME</i>}i</code><td>value of the given request header (e.g. <code>%{user-agent}i</code>)
 <tr><td><code>%{<i>HEADERNAME</i>}o</code><td>value of the given response header sent to client (e.g. <code>%{set-cookie}o</code>)
 <tr><td><code>%&lt;{<i>HEADERNAME</i>}o</code><td>value of the response header received from upstream (or initially generated)

srcdoc/configure/mruby.mt

@@ -168,4 +168,32 @@ Since the API provides an asynchronous HTTP client, it is possible to effectivel
 When HTTPS is used, servers are verified using the properties of <a href="configure/proxy_directives.html#proxy.ssl.cafile"><code>proxy.ssl.cafile</code></a> and <a href="configure/proxy_directives.html#proxy.ssl.verify-peer"><code>proxy.ssl.verify-peer</code></a> specified at the global level.
 </p>
 
+<h3 id="logging-arbitrary-variable">Logging Arbitrary Variable</h3>
+
+<p>
+In version 2.3, it is possible from mruby to set and log an arbitrary-named variable that is associated to a HTTP request.
+A HTTP response header that starts with <code>x-fallthru-set-</code> is handled specially by the H2O server. Instead of sending the header downstream, the server accepts the value as a request environment variable, taking the suffix of the header name as the name of the variable.
+</p>
+<p>
+This example shows how to read request data, parse json and then log data from mruby.
+</p>
+
+<?= $ctx->{example}->('Logging the content of a POST request via request environment variable', <<'EOT')
+paths:
+  "/":
+    mruby.handler: |
+      Proc.new do |env|
+        input = env["rack.input"] ? env["rack.input"].read : '{"default": "true"}'
+        parsed_json = JSON.parse(input)
+        parsed_json["time"] = Time.now.to_i
+        logdata = parsed_json.to_s
+        [204, {"x-fallthru-set-POSTDATA" => logdata}, []]
+      end
+    access-log:
+      path: /path/to/access-log.json
+      escape: json
+      format: '{"POST": %{POSTDATA}e}'
+EOT
+?>
+
 ? })