Skip to content

Commit

Permalink
updated docs to reflect recent changes.
Browse files Browse the repository at this point in the history
  • Loading branch information
@agentzh
agentzh committed Mar 15, 2012
1 parent c9c5f94 commit 2ac3aa2
Show file tree
Hide file tree
Showing 3 changed files with 144 additions and 31 deletions.
69 changes: 58 additions & 11 deletions README
View file
Expand Up @@ -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
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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

Expand All @@ -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**
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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
Expand All @@ -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"
Expand Down Expand Up @@ -4553,5 +4599,6 @@ See Also

* The ngx_openresty bundle (<http://openresty.org>)

* [Chinese (HttpLuaModuleZh)]
Translations
* Chinese

54 changes: 44 additions & 10 deletions README.markdown
View file
Expand Up @@ -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
========
Expand Down Expand Up @@ -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
Expand Down Expand Up @@ -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**
Expand Down Expand Up @@ -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).
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.

Expand Down Expand Up @@ -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)

52 changes: 42 additions & 10 deletions doc/HttpLuaModule.wiki
View file
Expand Up @@ -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">
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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*''
Expand Down Expand Up @@ -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]].
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.
Expand Down Expand Up @@ -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.