Permalink
Browse files

updated docs to reflect recent changes.

  • Loading branch information...
1 parent c9c5f94 commit 2ac3aa2a059ba3fab46576cb05a8769b43b85389 @agentzh agentzh committed Mar 15, 2012
Showing with 144 additions and 31 deletions.
  1. +58 −11 README
  2. +44 −10 README.markdown
  3. +42 −10 doc/HttpLuaModule.wiki
View
69 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
View
54 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)
View
52 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]]

0 comments on commit 2ac3aa2

Please sign in to comment.