updated docs to reflect recent changes.

Author: agentzh

README

@@ -8,8 +8,8 @@ Status
  This module is under active development and is production ready.
 
 Version
- This document describes ngx_lua v0.5.0rc17
- (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 6
+ This document describes ngx_lua v0.5.0rc19
+ (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 15
  March 2012.
 
 Synopsis
@@ -845,6 +845,29 @@ Directives
 
  This directive was first introduced in the "v0.5.0rc1" release.
 
+ lua_http10_buffering
+ syntax: *lua_http10_buffering on|off*
+
+ default: *lua_http10_buffering on*
+
+ context: *http, server, location, location-if*
+
+ Enables or disables the automatic response caching for HTTP 1.0 (or
+ older) requests. This buffering mechanism is mainly used for HTTP 1.0
+ keep-alive which replies on a proper "Content-Length" response header.
+
+ If the Lua code explicitly sets a "Content-Length" response header
+ before sending the headers (either explicity via ngx.send_headers or
+ implicitly via the first ngx.say or ngx.print call).
+
+ If you want to output huge response data in a streaming fashion (via the
+ ngx.flush call, for example), then you MUST turn off this directive to
+ prevent memory footprint boost.
+
+ This directive is turned "on" by default.
+
+ THis directive was first introduced in the "v0.5.0rc19" release.
+
 Nginx API for Lua
  Introduction
  The various *_by_lua and *_by_lua_file configuration directives serve as
@@ -960,9 +983,11 @@ Nginx API for Lua
  ngx.ERROR (-1)
  ngx.AGAIN (-2)
  ngx.DONE (-4)
+ ngx.DECLINED (-5)
 
- Note that only two of these constants are utilized by the Nginx API for
- Lua (i.e., ngx.exit accepts "NGX_OK" and "NGX_ERROR" as input).
+ Note that only three of these constants are utilized by the Nginx API
+ for Lua (i.e., ngx.exit accepts "NGX_OK", "NGX_ERROR", and
+ "NGX_DECLINED" as input).
 
  ngx.null
 
@@ -972,6 +997,9 @@ Nginx API for Lua
  library's "cjson.null" constant. This constant was first introduced in
  the "v0.5.0rc5" release.
 
+ The "ngx.DECLINED" constant was first introduced in the "v0.5.0rc19"
+ release.
+
  HTTP method constants
  context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
  header_filter_by_lua**
@@ -1677,6 +1705,12 @@ Nginx API for Lua
  where in the latter case, this method will automatically escape argument
  keys and values according to the URI escaping rule.
 
+ Multi-value arguments are also supported:
+
+ ngx.req.set_uri_args({ a = 3, b = {5, 6} })
+
+ which will result in a querystring like "a=3&b=5&b=6".
+
  This interface was first introduced in the "v0.3.1rc13" release.
 
  See also ngx.req.set_uri.
@@ -3722,13 +3756,23 @@ Nginx API for Lua
 HTTP 1.0 support
  The HTTP 1.0 protocol does not support chunked outputs and always
  requires an explicit "Content-Length" header when the response body is
- non-empty. So when an HTTP 1.0 request is present, This module will
+ non-empty in order to support the HTTP 1.0 keep-alive (as required by
+ the ApacheBench (ab) tool). So when an HTTP 1.0 request is present and
+ the lua_http10_buffering directive is turned "on", this module will
  automatically buffer all the outputs of user calls of ngx.say and
  ngx.print and postpone sending response headers until it sees all the
  outputs in the response body, and at that time ngx_lua can calculate the
  total length of the body and construct a proper "Content-Length" header
  for the HTTP 1.0 client.
 
+ If the user Lua code sets the "Content-Length" response header itself,
+ then the automatic buffering will be disabled even if the
+ lua_http10_buffering directive is turned "on".
+
+ For big responses' streaming outputs, it's important to disable the
+ lua_http10_buffering directive, otherwise the memory usage will grow
+ very quickly.
+
  Note that, common HTTP benchmark tools like "ab" and "http_load" always
  issue HTTP 1.0 requests by default. To force "curl" to send HTTP 1.0
  requests, use the -0 option.
@@ -4095,14 +4139,19 @@ Bugs and Patches
 
 TODO
  Short Term
- * implement the "ngx.sleep(time)" Lua API.
+ * implement the "ngx.sleep(time)" Lua API. (For now, use
+ ngx.location.capture with [[HttpEchoModule]]'s echo_sleep config
+ directive instead.)
 
- * implement the "ngx.worker.get_pid()" Lua API.
+ * implement the "ngx.worker.get_pid()" Lua API. (For now, use
+ "ngx.var.pid" directly.)
 
  * implement LuaSocket UDP API
  (<http://w3.impa.br/~diego/software/luasocket/udp.html>) in our
  cosocket API.
 
+ * implement the SSL cosocket API.
+
  * implement the "ngx.re.split" method.
 
  * use "ngx_hash_t" to optimize the built-in header look-up process for
@@ -4120,9 +4169,6 @@ TODO
 
  * deal with TCP 3-second delay problem under great connection harness.
 
- * add support for multi-value arguments to ngx.req.set_uri_args if its
- "args" argument is a Lua table.
-
  * add APIs to access cookies as key/value pairs.
 
  * add "ignore_resp_headers", "ignore_resp_body", and "ignore_resp"
@@ -4553,5 +4599,6 @@ See Also
 
  * The ngx_openresty bundle (<http://openresty.org>)
 
- * [Chinese (HttpLuaModuleZh)]
+Translations
+ * Chinese
 

README.markdown

@@ -13,7 +13,7 @@ This module is under active development and is production ready.
 Version
 =======
 
-This document describes ngx_lua [v0.5.0rc17](https://github.com/chaoslawful/lua-nginx-module/tags) released on 6 March 2012.
+This document describes ngx_lua [v0.5.0rc19](https://github.com/chaoslawful/lua-nginx-module/tags) released on 15 March 2012.
 
 Synopsis
 ========
@@ -786,6 +786,25 @@ The `<time>` argument can be an integer, with an optional time unit, like `s` (s
 
 This directive was first introduced in the `v0.5.0rc1` release.
 
+lua_http10_buffering
+--------------------
+
+**syntax:** *lua_http10_buffering on|off*
+
+**default:** *lua_http10_buffering on*
+
+**context:** *http, server, location, location-if*
+
+Enables or disables the automatic response caching for HTTP 1.0 (or older) requests. This buffering mechanism is mainly used for HTTP 1.0 keep-alive which replies on a proper `Content-Length` response header.
+
+If the Lua code explicitly sets a `Content-Length` response header before sending the headers (either explicity via [ngx.send_headers](http://wiki.nginx.org/HttpLuaModule#ngx.send_headers) or implicitly via the first [ngx.say](http://wiki.nginx.org/HttpLuaModule#ngx.say) or [ngx.print](http://wiki.nginx.org/HttpLuaModule#ngx.print) call).
+
+If you want to output huge response data in a streaming fashion (via the [ngx.flush](http://wiki.nginx.org/HttpLuaModule#ngx.flush) call, for example), then you MUST turn off this directive to prevent memory footprint boost.
+
+This directive is turned `on` by default.
+
+THis directive was first introduced in the `v0.5.0rc19` release.
+
 Nginx API for Lua
 =================
 Introduction
@@ -900,16 +919,19 @@ Core constants
   ngx.ERROR (-1)
   ngx.AGAIN (-2)
   ngx.DONE (-4)
+  ngx.DECLINED (-5)
 
 
-Note that only two of these constants are utilized by the [Nginx API for Lua](http://wiki.nginx.org/HttpLuaModule#Nginx_API_for_Lua) (i.e., [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit) accepts `NGX_OK` and `NGX_ERROR` as input).
+Note that only three of these constants are utilized by the [Nginx API for Lua](http://wiki.nginx.org/HttpLuaModule#Nginx_API_for_Lua) (i.e., [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit) accepts `NGX_OK`, `NGX_ERROR`, and `NGX_DECLINED` as input).
 
 
   ngx.null
 
 
 The `ngx.null` constant is a `NULL` light userdata which is usually used to represent nil values in Lua tables and etc. It is identical with the [lua-cjson](http://www.kyne.com.au/~mark/software/lua-cjson.php) library's `cjson.null` constant. This constant was first introduced in the `v0.5.0rc5` release.
 
+The `ngx.DECLINED` constant was first introduced in the `v0.5.0rc19` release.
+
 HTTP method constants
 ---------------------
 **context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua**
@@ -1623,6 +1645,14 @@ or a Lua table holding the query arguments' key-value pairs, as in
 
 where in the latter case, this method will automatically escape argument keys and values according to the URI escaping rule.
 
+Multi-value arguments are also supported:
+
+
+ ngx.req.set_uri_args({ a = 3, b = {5, 6} })
+
+
+which will result in a querystring like `a=3&b=5&b=6`.
+
 This interface was first introduced in the `v0.3.1rc13` release.
 
 See also [ngx.req.set_uri](http://wiki.nginx.org/HttpLuaModule#ngx.req.set_uri).
@@ -3425,13 +3455,17 @@ HTTP 1.0 support
 ================
 
 The HTTP 1.0 protocol does not support chunked outputs and always requires an
-explicit `Content-Length` header when the response body is non-empty. So when
-an HTTP 1.0 request is present, This module will automatically buffer all the
+explicit `Content-Length` header when the response body is non-empty in order to support the HTTP 1.0 keep-alive (as required by the ApacheBench (ab) tool). So when
+an HTTP 1.0 request is present and the [lua_http10_buffering](http://wiki.nginx.org/HttpLuaModule#lua_http10_buffering) directive is turned `on`, this module will automatically buffer all the
 outputs of user calls of [ngx.say](http://wiki.nginx.org/HttpLuaModule#ngx.say) and [ngx.print](http://wiki.nginx.org/HttpLuaModule#ngx.print) and
 postpone sending response headers until it sees all the outputs in the response
 body, and at that time ngx_lua can calculate the total length of the body and
 construct a proper `Content-Length` header for the HTTP 1.0 client.
 
+If the user Lua code sets the `Content-Length` response header itself, then the automatic buffering will be disabled even if the [lua_http10_buffering](http://wiki.nginx.org/HttpLuaModule#lua_http10_buffering) directive is turned `on`.
+
+For big responses' streaming outputs, it's important to disable the [lua_http10_buffering](http://wiki.nginx.org/HttpLuaModule#lua_http10_buffering) directive, otherwise the memory usage will grow very quickly.
+
 Note that, common HTTP benchmark tools like `ab` and `http_load` always issue
 HTTP 1.0 requests by default. To force `curl` to send HTTP 1.0 requests, use
 the `-0` option.
@@ -3718,16 +3752,16 @@ TODO
 
 Short Term
 ----------
-* implement the `ngx.sleep(time)` Lua API.
-* implement the `ngx.worker.get_pid()` Lua API.
+* implement the `ngx.sleep(time)` Lua API. (For now, use [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) with [HttpEchoModule](http://wiki.nginx.org/HttpEchoModule)'s [echo_sleep](http://wiki.nginx.org/HttpEchoModule#echo_sleep) config directive instead.)
+* implement the `ngx.worker.get_pid()` Lua API. (For now, use `ngx.var.pid` directly.)
 * implement [LuaSocket UDP API](http://w3.impa.br/~diego/software/luasocket/udp.html) in our cosocket API.
+* implement the SSL cosocket API.
 * implement the `ngx.re.split` method.
 * use `ngx_hash_t` to optimize the built-in header look-up process for [ngx.req.set_header](http://wiki.nginx.org/HttpLuaModule#ngx.req.set_header), [ngx.header.HEADER](http://wiki.nginx.org/HttpLuaModule#ngx.header.HEADER), and etc.
 * fix HTTP 1.0 support: we should by default close the current HTTP 1.0 connection right away if no `Content-Length` response header is set. the current automatic full buffering bahvior is way too expensive.
 * add configure options for different strategies of handling the cosocket connection exceeding in the pools.
 * add directives to run Lua codes when nginx stops/reloads.
 * deal with TCP 3-second delay problem under great connection harness.
-* add support for multi-value arguments to [ngx.req.set_uri_args](http://wiki.nginx.org/HttpLuaModule#ngx.req.set_uri_args) if its `args` argument is a Lua table.
 * add APIs to access cookies as key/value pairs.
 * add `ignore_resp_headers`, `ignore_resp_body`, and `ignore_resp` options to [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) and [ngx.location.capture_multi](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture_multi) methods, to allow micro performance tuning on the user side.
 
@@ -3916,7 +3950,7 @@ See Also
 * [HttpMemcModule](http://wiki.nginx.org/HttpMemcModule)
 * [The ngx_openresty bundle](http://openresty.org)
 
-<div id="translations">
-* [ Chinese](http://wiki.nginx.org/HttpLuaModuleZh)
-</div>
+Translations
+============
+* [Chinese](http://wiki.nginx.org/HttpLuaModuleZh)
 

doc/HttpLuaModule.wiki

@@ -10,7 +10,7 @@ This module is under active development and is production ready.
 
 = Version =
 
-This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.0rc17] released on 6 March 2012.
+This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.0rc19] released on 15 March 2012.
 
 = Synopsis =
 <geshi lang="nginx">
@@ -757,6 +757,24 @@ The <code><time></code> argument can be an integer, with an optional time unit,
 
 This directive was first introduced in the <code>v0.5.0rc1</code> release.
 
+== lua_http10_buffering ==
+
+'''syntax:''' ''lua_http10_buffering on|off''
+
+'''default:''' ''lua_http10_buffering on''
+
+'''context:''' ''http, server, location, location-if''
+
+Enables or disables the automatic response caching for HTTP 1.0 (or older) requests. This buffering mechanism is mainly used for HTTP 1.0 keep-alive which replies on a proper <code>Content-Length</code> response header.
+
+If the Lua code explicitly sets a <code>Content-Length</code> response header before sending the headers (either explicity via [[#ngx.send_headers|ngx.send_headers]] or implicitly via the first [[#ngx.say|ngx.say]] or [[#ngx.print|ngx.print]] call).
+
+If you want to output huge response data in a streaming fashion (via the [[#ngx.flush|ngx.flush]] call, for example), then you MUST turn off this directive to prevent memory footprint boost.
+
+This directive is turned <code>on</code> by default.
+
+THis directive was first introduced in the <code>v0.5.0rc19</code> release.
+
 = Nginx API for Lua =
 == Introduction ==
 The various <code>*_by_lua</code> and <code>*_by_lua_file</code> configuration directives serve as gateways to the Lua API within the <code>nginx.conf</code> file. The Nginx Lua API described below can only be called within the user Lua code run in the context of these configuration directives.
@@ -866,16 +884,19 @@ Setting <code>ngx.var.Foo</code> to a <code>nil</code> value will unset the <cod
  ngx.ERROR (-1)
  ngx.AGAIN (-2)
  ngx.DONE (-4)
+ ngx.DECLINED (-5)
 </geshi>
 
-Note that only two of these constants are utilized by the [[#Nginx API for Lua|Nginx API for Lua]] (i.e., [[#ngx.exit|ngx.exit]] accepts <code>NGX_OK</code> and <code>NGX_ERROR</code> as input).
+Note that only three of these constants are utilized by the [[#Nginx API for Lua|Nginx API for Lua]] (i.e., [[#ngx.exit|ngx.exit]] accepts <code>NGX_OK</code>, <code>NGX_ERROR</code>, and <code>NGX_DECLINED</code> as input).
 
 <geshi lang="lua">
  ngx.null
 </geshi>
 
 The <code>ngx.null</code> constant is a <code>NULL</code> light userdata which is usually used to represent nil values in Lua tables and etc. It is identical with the [http://www.kyne.com.au/~mark/software/lua-cjson.php lua-cjson] library's <code>cjson.null</code> constant. This constant was first introduced in the <code>v0.5.0rc5</code> release.
 
+The <code>ngx.DECLINED</code> constant was first introduced in the <code>v0.5.0rc19</code> release.
+
 == HTTP method constants ==
 '''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*''
 
@@ -1578,6 +1599,14 @@ or a Lua table holding the query arguments' key-value pairs, as in
 
 where in the latter case, this method will automatically escape argument keys and values according to the URI escaping rule.
 
+Multi-value arguments are also supported:
+
+<geshi lang="lua">
+ ngx.req.set_uri_args({ a = 3, b = {5, 6} })
+</geshi>
+
+which will result in a querystring like <code>a=3&b=5&b=6</code>.
+
 This interface was first introduced in the <code>v0.3.1rc13</code> release.
 
 See also [[#ngx.req.set_uri|ngx.req.set_uri]].
@@ -3312,13 +3341,17 @@ This feature requires the [https://github.com/simpl/ngx_devel_kit ngx_devel_kit]
 = HTTP 1.0 support =
 
 The HTTP 1.0 protocol does not support chunked outputs and always requires an
-explicit <code>Content-Length</code> header when the response body is non-empty. So when
-an HTTP 1.0 request is present, This module will automatically buffer all the
+explicit <code>Content-Length</code> header when the response body is non-empty in order to support the HTTP 1.0 keep-alive (as required by the ApacheBench (ab) tool). So when
+an HTTP 1.0 request is present and the [[#lua_http10_buffering|lua_http10_buffering]] directive is turned <code>on</code>, this module will automatically buffer all the
 outputs of user calls of [[#ngx.say|ngx.say]] and [[#ngx.print|ngx.print]] and
 postpone sending response headers until it sees all the outputs in the response
 body, and at that time ngx_lua can calculate the total length of the body and
 construct a proper <code>Content-Length</code> header for the HTTP 1.0 client.
 
+If the user Lua code sets the <code>Content-Length</code> response header itself, then the automatic buffering will be disabled even if the [[#lua_http10_buffering|lua_http10_buffering]] directive is turned <code>on</code>.
+
+For big responses' streaming outputs, it's important to disable the [[#lua_http10_buffering|lua_http10_buffering]] directive, otherwise the memory usage will grow very quickly.
+
 Note that, common HTTP benchmark tools like <code>ab</code> and <code>http_load</code> always issue
 HTTP 1.0 requests by default. To force <code>curl</code> to send HTTP 1.0 requests, use
 the <code>-0</code> option.
@@ -3592,16 +3625,16 @@ Please report bugs or submit patches by:
 = TODO =
 
 == Short Term ==
-* implement the <code>ngx.sleep(time)</code> Lua API.
-* implement the <code>ngx.worker.get_pid()</code> Lua API.
+* implement the <code>ngx.sleep(time)</code> Lua API. (For now, use [[#ngx.location.capture|ngx.location.capture]] with [[HttpEchoModule]]'s [[HttpEchoModule#echo_sleep|echo_sleep]] config directive instead.)
+* implement the <code>ngx.worker.get_pid()</code> Lua API. (For now, use <code>ngx.var.pid</code> directly.)
 * implement [http://w3.impa.br/~diego/software/luasocket/udp.html LuaSocket UDP API] in our cosocket API.
+* implement the SSL cosocket API.
 * implement the <code>ngx.re.split</code> method.
 * use <code>ngx_hash_t</code> to optimize the built-in header look-up process for [[#ngx.req.set_header|ngx.req.set_header]], [[#ngx.header.HEADER|ngx.header.HEADER]], and etc.
 * fix HTTP 1.0 support: we should by default close the current HTTP 1.0 connection right away if no <code>Content-Length</code> response header is set. the current automatic full buffering bahvior is way too expensive.
 * add configure options for different strategies of handling the cosocket connection exceeding in the pools.
 * add directives to run Lua codes when nginx stops/reloads.
 * deal with TCP 3-second delay problem under great connection harness.
-* add support for multi-value arguments to [[#ngx.req.set_uri_args|ngx.req.set_uri_args]] if its <code>args</code> argument is a Lua table.
 * add APIs to access cookies as key/value pairs.
 * add <code>ignore_resp_headers</code>, <code>ignore_resp_body</code>, and <code>ignore_resp</code> options to [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]] methods, to allow micro performance tuning on the user side.
 
@@ -3782,7 +3815,6 @@ THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND
 * [[HttpMemcModule]]
 * [http://openresty.org The ngx_openresty bundle]
 
-<div id="translations">
-* [[HttpLuaModuleZh| Chinese]]
-</div>
+= Translations =
+* [[HttpLuaModuleZh|Chinese]]