From: Daniel Gruno <humbedooh@apache.org>
Date: Thu, 2 Aug 2012 08:13:54 +0000 (+0000)
Subject: - Add some information about the fields in the request_rec structure
X-Git-Tag: 2.5.0-alpha~6531
X-Git-Url: https://granicus.if.org/sourcecode?a=commitdiff_plain;h=f985f4cd71c8e37a88ad63a8a1dc550e7af45dfd;p=apache

- Add some information about the fields in the request_rec structure
- Add r.is_https to the list of fields
- Add r:escape_html to the list of function calls

git-svn-id: https://svn.apache.org/repos/asf/httpd/httpd/trunk@1368377 13f79535-47bb-0310-9956-ffa450edef68
---

diff --git a/docs/manual/mod/mod_lua.xml b/docs/manual/mod/mod_lua.xml
index ef6270942f..4893519286 100644
--- a/docs/manual/mod/mod_lua.xml
+++ b/docs/manual/mod/mod_lua.xml
@@ -228,8 +228,8 @@ end
      substitution, including the core translate_name hook which maps based
      on the DocumentRoot.
 
-     Note: It is currently undefined as to whether this runs before or after
-     mod_alias.
+     Note: Use the early/late flags in the directive to make it run before
+           or after mod_alias.
 --]]
 
 require 'apache2'
@@ -251,165 +251,214 @@ end
         <dd>
         <p>The request_rec is mapped in as a userdata. It has a metatable
         which lets you do useful things with it. For the most part it
-        has the same fields as the request_rec struct (see httpd.h
-        until we get better docs here) many of which are writeable as
+        has the same fields as the request_rec struct, many of which are writeable as
         well as readable.  (The table fields' content can be changed, but the
         fields themselves cannot be set to different tables.)</p>
 
-        <table border="1">
+        <table border="1" style="zebra">
 
         <tr>
           <th><strong>Name</strong></th>
           <th><strong>Lua type</strong></th>
           <th><strong>Writable</strong></th>
+          <th><strong>Description</strong></th>
         </tr>
         <tr>
           <td><code>ap_auth_type</code></td>
           <td>string</td>
           <td>no</td>
+          <td>If an authentication check was made, this is set to the type 
+          of authentication (f.x. <code>basic</code>)</td>
         </tr>
         <tr>
           <td><code>args</code></td>
           <td>string</td>
           <td>yes</td>
+          <td>The query string arguments extracted from the request 
+            (f.x. <code>foo=bar&amp;name=johnsmith</code>)</td>
         </tr>
         <tr>
           <td><code>assbackwards</code></td>
           <td>boolean</td>
           <td>no</td>
+          <td>Set to true if this is an HTTP/0.9 style request 
+            (e.g. <code>GET /foo</code> (with no headers) )</td>
         </tr>
 
         <tr>
           <td><code>canonical_filename</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The canonical filename of the request</td>
         </tr>
         <tr>
           <td><code>content_encoding</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The content encoding of the current request</td>
         </tr>
         <tr>
           <td><code>content_type</code></td>
           <td>string</td>
           <td>yes</td>
+          <td>The content type of the current request, as determined in the 
+            type_check phase (f.x. <code>image/gif</code> or <code>text/html</code>)</td>
         </tr>
         <tr>
           <td><code>context_prefix</code></td>
           <td>string</td>
           <td>no</td>
+          <td></td>
         </tr>
         <tr>
           <td><code>context_document_root</code></td>
           <td>string</td>
           <td>no</td>
+          <td></td>
         </tr>
 
         <tr>
           <td><code>document_root</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The document root of the host</td>
         </tr>
         <tr>
           <td><code>err_headers_out</code></td>
           <td>table</td>
           <td>no</td>
+          <td>MIME header environment for the response, printed even on errors and
+            persist across internal redirects</td>
         </tr>
         <tr>
           <td><code>filename</code></td>
           <td>string</td>
           <td>yes</td>
+          <td>The file name that the request maps to, f.x. /www/example.com/foo.txt. This can be 
+            changed in the translate-name or map-to-storage phases of a request to allow the 
+            default handler (or script handlers) to serve a different file than what was requested.</td>
         </tr>
         <tr>
           <td><code>handler</code></td>
           <td>string</td>
           <td>yes</td>
+          <td>The name of the <a href="../handler.html">handler</a> that should serve this request, f.x. 
+            <code>lua-script</code> if it is to be served by mod_lua. This is typically set by the 
+            <directive module="mod_mime">AddHandler</directive> or <directive module="core">SetHandler</directive> 
+            directives, but could also be set via mod_lua to allow another handler to serve up a specific request 
+            that would otherwise not be served by it.
+            </td>
         </tr>
 
         <tr>
           <td><code>headers_in</code></td>
           <td>table</td>
           <td>yes</td>
+          <td>MIME header environment from the request. This contains headers such as <code>Host, 
+            User-Agent, Referer</code> and so on.</td>
         </tr>
         <tr>
           <td><code>headers_out</code></td>
           <td>table</td>
           <td>yes</td>
+          <td>MIME header environment for the response.</td>
         </tr>
         <tr>
           <td><code>hostname</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The host name, as set by the <code>Host:</code> header or by a full URI.</td>
+        </tr>
+        <tr>
+          <td><code>is_https</code></td>
+          <td>boolean</td>
+          <td>no</td>
+          <td>Whether or not this request is done via HTTPS</td>
         </tr>
         <tr>
           <td><code>log_id</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The ID to identify request in access and error log.</td>
         </tr>
         <tr>
           <td><code>method</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The request method, f.x. <code>GET</code> or <code>POST</code>.</td>
         </tr>
         <tr>
           <td><code>notes</code></td>
           <td>table</td>
           <td>yes</td>
+          <td>A list of notes that can be passed on from one module to another.</td>
         </tr>
         <tr>
           <td><code>path_info</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The PATH_INFO extracted from this request.</td>
         </tr>
         <tr>
           <td><code>protocol</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The protocol used, f.x. <code>HTTP/1.1</code></td>
         </tr>
         <tr>
           <td><code>proxyreq</code></td>
           <td>string</td>
           <td>yes</td>
+          <td>Denotes whether this is a proxy request or not. This value is generally set in 
+            the post_read_request/translate_name phase of a request.</td>
         </tr>
         <tr>
           <td><code>range</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The contents of the <code>Range:</code> header.</td>
         </tr>
         <tr>
           <td><code>subprocess_env</code></td>
           <td>table</td>
           <td>yes</td>
+          <td>The environment variables set for this request.</td>
         </tr>
         <tr>
           <td><code>status</code></td>
           <td>number</td>
           <td>yes</td>
+          <td>The (current) HTTP return code for this request, f.x. <code>200</code> or <code>404</code>.</td>
         </tr>
         <tr>
           <td><code>the_request</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The request string as sent by the client, f.x. <code>GET /foo/bar HTTP/1.1</code>.</td>
         </tr>
         <tr>
           <td><code>unparsed_uri</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The unparsed URI of the request</td>
         </tr>
         <tr>
           <td><code>uri</code></td>
           <td>string</td>
           <td>yes</td>
+          <td>The URI after it has been parsed by httpd</td>
         </tr>
         <tr>
           <td><code>user</code></td>
           <td>string</td>
           <td>yes</td>
+          <td>If an authentication check has been made, this is set to the name of the authenticated user.</td>
         </tr>
         <tr>
           <td><code>useragent_ip</code></td>
           <td>string</td>
           <td>no</td>
+          <td>The IP of the user agent making the request</td>
         </tr>
         </table>
 
@@ -434,6 +483,10 @@ end
         <highlight language="lua">
         r:write("a single string") -- print to response body
         </highlight>
+
+        <highlight language="lua">
+        r:escape_html("&lt;html&gt;test&lt;/html&gt;") -- Escapes HTML code and returns the escaped result
+        </highlight>
         </dd>
     </dl>