201
201
'''context:''' ''main, server, location, location if''
203
Enable or disable the Lua code cache for [[#set_by_lua_file|set_by_lua_file]],
203
Enables or disables the Lua code cache for [[#set_by_lua_file|set_by_lua_file]],
204
204
[[#content_by_lua_file|content_by_lua_file]], [[#rewrite_by_lua_file|rewrite_by_lua_file]], and
205
205
[[#access_by_lua_file|access_by_lua_file]], and also force Lua module reloading on a per-request basis.
207
207
The Lua files referenced in [[#set_by_lua_file|set_by_lua_file]],
208
208
[[#content_by_lua_file|content_by_lua_file]], [[#access_by_lua_file|access_by_lua_file]],
209
and [[#rewrite_by_lua_file|rewrite_by_lua_file]] will not be cached at all,
210
and Lua's <code>package.loaded</code> table will be cleared
209
and [[#rewrite_by_lua_file|rewrite_by_lua_file]] will not be cached
210
and the Lua <code>package.loaded</code> table will be cleared
211
211
at the entry point of every request (such that Lua modules
212
will not be cached either). With this in place, developers can follow
213
the PHP way, i.e., edit-and-refresh.
212
will not be cached either). With this in place, developers can adopt an edit and refresh approach.
215
214
Please note however, that Lua code inlined into nginx.conf
216
215
such as those specified by [[#set_by_lua|set_by_lua]], [[#content_by_lua|content_by_lua]],
280
279
'''phase:''' ''rewrite''
282
Execute user code specified by <code><lua-script-str></code> with input arguments <code>$arg1 $arg2 ...</code>, and set the script's return value to <code>$res</code> in string form.
283
The code in <code><lua-script-str></code> can retrieve input arguments from the <code>ngx.arg</code> table (index starts from <code>1</code> and increases sequentially) and the lua code may make [[#Nginx API for Lua|API calls]].
285
The [[#set_by_lua|set_by_lua]] directive is designed to execute short, fast running code blocks as the Nginx event loop is blocked during code execution. Time consuming code sequences should therefore be avoided.
287
Note that [[#set_by_lua|set_by_lua]] can only output a value to a single Nginx variable at
288
a time but a workaround is possible by using the [[#ngx.var.VARIABLE|ngx.var.VARIABLE]] interface.
281
Executes code specified in <code><lua-script-str></code> with optional input arguments <code>$arg1 $arg2 ...</code>, and returns string output to <code>$res</code>.
282
The code in <code><lua-script-str></code> can make [[#Nginx API for Lua|API calls]] and can retrieve input arguments from the <code>ngx.arg</code> table (index starts from <code>1</code> and increases sequentially).
284
This directive is designed to execute short, fast running code blocks as the Nginx event loop is blocked during code execution. Time consuming code sequences should therefore be avoided.
286
Note that I/O operations such as [[#ngx.say|ngx.say]], [[#ngx.exec|ngx.exec]], [[HttpEchoModule#echo|echo]] and similar are not permitted within the context of this directive.
288
In addition, note that this directive can only output a value to a single Nginx variable at
289
a time. However, a workaround is possible using the [[#ngx.var.VARIABLE|ngx.var.VARIABLE]] interface.
291
291
<geshi lang="nginx">
561
561
'''context:''' ''http, server, location, location if''
563
'''phase:''' ''post-access''
563
'''phase:''' ''access tail''
565
565
Equivalent to [[#access_by_lua|access_by_lua]], except that the file specified by <code><path-to-lua-script-file></code> contains the Lua code to be executed.
567
567
Nginx variables can be used in the <code><path-to-lua-script-file></code> string to provide flexibility. This however carries some risks and is not ordinarily recommended.
569
569
When the Lua code cache is on (default state), the user code is loaded once at the first request and cached
570
and the Nginx config must be reloaded each time you modify the Lua source file.
571
You can temporarily disable the Lua code cache during development by
572
switching [[#lua_code_cache|lua_code_cache]] <code>off</code> in your <code>nginx.conf</code> to avoid reloading Nginx.
570
and the Nginx config must be reloaded each time the Lua source file is modified.
571
The Lua code cache can be temporarily disabled during development by switching [[#lua_code_cache|lua_code_cache]] <code>off</code> in <code>nginx.conf</code> to avoid repeatedly reloading Nginx.
574
573
== header_filter_by_lua ==
1498
Multiple occurrences of an argument key will result in a table value holding all of the values for that key in order.
1500
Multiple occurrences of an argument key will result in a table value holding all the values for that key in order.
1500
Keys and values will be automatically unescaped according to URI escaping rules. For example, in the above settings, <code>GET /test?a%20b=1%61+2</code> will yield the output
1502
Keys and values are automatically unescaped according to URI escaping rules. In the settings above, <code>GET /test?a%20b=1%61+2</code> will yield:
1502
1504
<geshi lang="bash">
1506
Arguments without the <code>=<value></code> parts are treated as boolean arguments. For example, <code>GET /test?foo&bar</code> will yield the outputs
1508
Arguments without the <code>=<value></code> parts are treated as boolean arguments. <code>GET /test?foo&bar</code> will yield:
1508
1510
<geshi lang="bash">
1513
That is, they will take Lua boolean values <code>true</code>. However, they're different from arguments taking empty string values. For example, <code>GET /test?foo=&bar=</code> will give something like
1515
That is, they will take Lua boolean values <code>true</code>. However, they are different from arguments taking empty string values. <code>GET /test?foo=&bar=</code> will give something like
1515
1517
<geshi lang="bash">
1520
Empty key arguments are discarded, for instance, <code>GET /test?=hello&=world</code> will yield empty outputs.
1522
Empty key arguments are discarded. <code>GET /test?=hello&=world</code> will yield an empty output for instance.
1522
Updating query arguments via the nginx variable <code>$args</code> (or <code>ngx.var.args</code> in Lua) at runtime are also supported:
1524
Updating query arguments via the nginx variable <code>$args</code> (or <code>ngx.var.args</code> in Lua) at runtime is also supported:
1524
1526
<geshi lang="lua">
1525
1527
ngx.var.args = "a=3&b=42"
1535
1537
regardless of the actual request query string.
1539
Note that a maximum of 100 request arguments are parsed by default (including those with the same name) and that additional request arguments are silently discarded to guard against potential denial of service attacks.
1541
However, the optional <code>count_limit</code> function argument can be used to override this limit:
1544
local args = ngx.req.get_uri_args(10)
1547
This argument can be set to zero to remove the limit and to process all request arguments received:
1550
local args = ngx.req.get_uri_args(0)
1553
Removing the <code>count_limit</code> cap is strongly discouraged.
1537
1555
== ngx.req.get_post_args ==
1538
'''syntax:''' ''ngx.req.get_post_args()''
1556
'''syntax:''' ''ngx.req.get_post_args(count_limit?)''
1540
1558
'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*''
1542
Returns a Lua table holds all of the current request's POST query arguments (of the MIME type <code>application/x-www-form-urlencoded</code>). It is required to read the request body first by calling [[#ngx.req.read_body|ngx.req.read_body]] or to turn on the [[#lua_need_request_body|lua_need_request_body]] directive, or a Lua exception will be thrown.
1560
Returns a Lua table holding all the current request POST query arguments (of the MIME type <code>application/x-www-form-urlencoded</code>). Call [[#ngx.req.read_body|ngx.req.read_body]] to read the request body first or turn on the [[#lua_need_request_body|lua_need_request_body]] directive to avoid Lua exception errors.
1546
1562
<geshi lang="nginx">
1547
1563
location = /test {
1576
1592
Multiple occurrences of an argument key will result in a table value holding all of the values for that key in order.
1578
Keys and values will be automatically unescaped according to URI escaping rules. For example, in the above settings,
1594
Keys and values will be automatically unescaped according to URI escaping rules.
1596
With the settings above,
1580
1598
<geshi lang="bash">
1581
1599
# POST request with body 'a%20b=1%61+2'
1582
1600
$ curl -d 'a%20b=1%61+2' localhost/test
1585
will yield the output
1587
1605
<geshi lang="bash">
1591
Arguments without the <code>=<value></code> parts are treated as boolean arguments. For example, <code>GET /test?foo&bar</code> will yield the outputs
1609
Arguments without the <code>=<value></code> parts are treated as boolean arguments. <code>GET /test?foo&bar</code> will yield:
1593
1611
<geshi lang="bash">
1598
That is, they will take Lua boolean values <code>true</code>. However, they're different from arguments taking empty string values. For example, <code>POST /test</code> with request body <code>foo=&bar=</code> will give something like
1616
That is, they will take Lua boolean values <code>true</code>. However, they are different from arguments taking empty string values. <code>POST /test</code> with request body <code>foo=&bar=</code> will return something like
1600
1618
<geshi lang="bash">
1605
Empty key arguments are discarded, for instance, <code>POST /test</code> with body <code>=hello&=world</code> will yield empty outputs.
1623
Empty key arguments are discarded. <code>POST /test</code> with body <code>=hello&=world</code> will yield empty outputs for instance.
1625
Note that a maximum of 100 request arguments are parsed by default (including those with the same name) and that additional request arguments are silently discarded to guard against potential denial of service attacks.
1627
However, the optional <code>count_limit</code> function argument can be used to override this limit:
1630
local args = ngx.req.get_post_args(10)
1633
This argument can be set to zero to remove the limit and to process all request arguments received:
1636
local args = ngx.req.get_post_args(0)
1639
Removing the <code>count_limit</code> cap is strongly discouraged.
1607
1641
== ngx.req.get_headers ==
1608
'''syntax:''' ''headers = ngx.req.get_headers()''
1642
'''syntax:''' ''headers = ngx.req.get_headers(count_limit?)''
1610
1644
'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*''
1612
Returns a Lua table holds all of the current request's request headers.
1646
Returns a Lua table holding all the current request headers.
1616
1648
<geshi lang="lua">
1617
1649
local h = ngx.req.get_headers()
1690
1738
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
1692
Read the client request body synchronously but still non-blockingly.
1694
If the request body is already read previously by turning on [[#lua_need_request_body|lua_need_request_body]] or by using other modules, then this function is a no-op and returns immediately.
1696
If the request body has already been explicitly discarded, either by this module's [[#ngx.req.discard_body|ngx.req.discard_body]] or other modules, this function is a no-op and returns immediately.
1698
In case of errors, like connection errors while reading the data, this method will throw out a Lua exception ''or'' terminate the current request with the 500 status code immediately.
1700
You can later either retrieve the request body data via [[#ngx.req.get_body_data|ngx.req.get_body_data]] or retrieve the temporary file name for the body data cached to disk via [[#ngx.req.get_body_file|ngx.req.get_body_file]], depending on
1702
# whether the current request body is already exceeding your [[HttpCoreModule#client_body_buffer_size|client_body_buffer_size]],
1703
# and whether you have turned on [[HttpCoreModule#client_body_in_file_only|client_body_in_file_only]].
1705
In case that you do not want to read the request body and the current request may have a request body, then it is crucial to use the [[#ngx.req.discard_body|ngx.req.discard_body]] function to explicitly discard the request body, or you'll break HTTP 1.1 keepalive and HTTP 1.1 pipelining.
1707
Here is a small example:
1740
Reads the client request body synchronously without blocking the Nginx event loop.
1709
1742
<geshi lang="lua">
1710
1743
ngx.req.read_body()
1711
1744
local args = ngx.req.get_post_args()
1747
If the request body is already read previously by turning on [[#lua_need_request_body|lua_need_request_body]] or by using other modules, then this function does not run and returns immediately.
1749
If the request body has already been explicitly discarded, either by the [[#ngx.req.discard_body|ngx.req.discard_body]] function or other modules, this function does not run and returns immediately.
1751
In case of errors, such as connection errors while reading the data, this method will throw out a Lua exception ''or'' terminate the current request with a 500 status code immediately.
1753
The request body data read using this function can be retrieved later via [[#ngx.req.get_body_data|ngx.req.get_body_data]] or, alternatively, the temporary file name for the body data cached to disk using [[#ngx.req.get_body_file|ngx.req.get_body_file]]. This depends on
1755
# whether the current request body is already larger than the [[HttpCoreModule#client_body_buffer_size|client_body_buffer_size]],
1756
# and whether [[HttpCoreModule#client_body_in_file_only|client_body_in_file_only]] has been switched on.
1758
In cases where current request may have a request body and the request body data is not required, The [[#ngx.req.discard_body|ngx.req.discard_body]] function must be used to explicitly discard the request body to avoid breaking things under HTTP 1.1 keepalive or HTTP 1.1 pipelining.
1714
1760
This function was first introduced in the <code>v0.3.1rc17</code> release.
1716
1762
== ngx.req.discard_body ==
1798
1844
If the optional <code>auto_clean</code> argument is given a <code>true</code> value, then this file will be automatically removed at request completion or the next time this function or [[#ngx.req.set_body_data|ngx.req.set_body_data]] are called in the same request. The <code>auto_clean</code> is default to <code>false</code>.
1800
You must ensure that the file specified by the <code>file_name</code> argument exists and is readable by an Nginx worker process by setting its permission properly. Otherwise a Lua exception will be thrown.
1846
Please ensure that the file specified by the <code>file_name</code> argument exists and is readable by an Nginx worker process by setting its permission properly to avoid Lua exception errors.
1802
1848
If the current request's request body has not been read, then it will be properly discarded. When the current request's request body has been read into memory or buffered into a disk file, then the old request body's memory will be freed or the disk file will be cleaned up immediately, respectively.
1804
This function requires patching the Nginx core to function properly because the Nginx core does not allow modifying request bodies by the current design. Here is a patch for Nginx 1.0.9: [https://github.com/agentzh/ngx_openresty/blob/master/patches/nginx-1.0.9-allow_request_body_updating.patch nginx-1.0.9-allow_request_body_updating.patch], and this patch should be applied cleanly to other releases of Nginx as well.
1806
If you're using [http://openresty.org/ ngx_openresty] 1.0.8.17+, then you've already had this patch applied.
1850
This function requires patching the Nginx core to function properly because the Nginx core does not allow modifying request bodies by the current design. Here is a patch for Nginx 1.0.9: [https://github.com/agentzh/ngx_openresty/blob/master/patches/nginx-1.0.9-allow_request_body_updating.patch nginx-1.0.9-allow_request_body_updating.patch], and this patch should be applied cleanly to other releases of Nginx as well.
1851
This patch has already been applied to [http://openresty.org/ ngx_openresty] 1.0.8.17 and above.
1808
1853
This function was first introduced in the <code>v0.3.1rc18</code> release.
2828
Your <code>mydata</code> module in this example will only be loaded
2829
and run on the first request to the location <code>/lua</code>,
2830
and all those subsequent requests to the same nginx
2831
worker process will use the reloaded instance of the
2832
module as well as the same copy of the data in it,
2833
until you send a <code>HUP</code> signal to the nginx master
2834
process to enforce a reload.
2836
This data sharing technique is essential for high-performance Lua apps built atop this module. It is common to cache reusable data globally.
2838
It is worth noting that this is ''per-worker'' sharing, not ''per-server'' sharing. That is, when you have multiple nginx worker processes under an nginx master, this data sharing cannot pass process boundary. If you indeed need server-wide data sharing, you can
2840
# Use only a single nginx worker and a single server. This is not recommended when you have a multi-core CPU or multiple CPUs in a single machine.
2841
# Use some true backend storage like <code>memcached</code>, <code>redis</code>, or an RDBMS like <code>mysql</code>.
2885
The <code>mydata</code> module in this example will only be loaded and run on the first request to the location <code>/lua</code>,
2886
and all subsequent requests to the same nginx worker process will use the reloaded instance of the
2887
module as well as the same copy of the data in it, until a <code>HUP</code> signal is sent to the Nginx master process to force a reload.
2888
This data sharing technique is essential for high performance Lua applications based on this module.
2890
Note that this data sharing is on a ''per-worker'' basis and not on a ''per-server' basis'. That is, when there are multiple nginx worker processes under an Nginx master, data sharing cannot cross the process boundary between these workers.
2892
If server wide data sharing is required:
2893
# Use the [[#ngx.shared.DICT|ngx.shared.DICT]] API provied by this module.
2894
# Use only a single nginx worker and a single server. This is however not recommended when there is a multi core CPU or multiple CPUs in a single machine.
2895
# Use data storage mechanisms such as <code>memcached</code>, <code>redis</code>, <code>MySQL</code> or <code>PostgreSQL</code>. [http://openresty.org The ngx_openresty bundle] associated with this module comes with a set of companion Nginx modules that provide interfaces with these data storage mechanisms. See the [[HttpMemcModule]], [[HttpRedis2Module]], [[HttpDrizzleModule]] and [http://github.com/FRiCKLE/ngx_postgres/ HttpPostgresModule] modules for details
2843
2897
= Known Issues =
2845
2899
== Lua Coroutine Yielding/Resuming ==
2846
2900
* As the module's predefined Nginx I/O API uses the coroutine yielding/resuming mechanism, user code should not call any Lua modules that use the Lua coroutine mechanism in order to prevent conflicts with the module's predefined Nginx API methods such as [[#ngx.location.capture|ngx.location.capture]] (Actually, coroutine modules have been masked off in [[#content_by_lua|content_by_lua]] directives and others). This limitation is significant and work is ongoing on an alternative coroutine implementation that can fit into the Nginx event model to address this. When this is done, it will be possible to use the Lua coroutine mechanism freely as it is in standard Lua implementations.
2847
* Lua's <code>dofile</code> builtin is implemented as a C function in both Lua 5.1 and LuaJIT 2.0 and when you call [[#ngx.location.capture|ngx.location.capture]], [[#ngx.exec|ngx.exec]], [[#ngx.exit|ngx.exit]] or [[#ngx.req.read_body|ngx.req.read_body]] or similar in the file to be loaded by <code>dofile</code>, a coroutine yield across the C function boundary will be initiated. This however is not allowed within ngx_lua and will usually result in error messages like <code>lua handler aborted: runtime error: attempt to yield across C-call boundary</code>. To avoid this, define a real Lua module in your <code>.lua</code> file and use Lua's <code>require</code> builtin instead.
2848
* Because the standard Lua 5.1 interpreter's VM is not fully resumable, the methods [[#ngx.location.capture|ngx.location.capture]], [[#ngx.location.capture_multi|ngx.location.capture_multi]], [[#ngx.redirect|ngx.redirect]], [[#ngx.exec|ngx.exec]], and [[#ngx.exit|ngx.exit]] cannot be used within the context of a Lua [http://www.lua.org/manual/5.1/manual.html#pdf-pcall pcall()] or [http://www.lua.org/manual/5.1/manual.html#pdf-xpcall xpcall()] when the standard Lua 5.1 interpreter is used; you'll get the error <code>attempt to yield across metamethod/C-call boundary</code>. To fix this, please use LuaJIT 2.0 instead, because LuaJIT 2.0 supports a fully resume-able VM.
2901
* Lua's <code>dofile</code> builtin is implemented as a C function in both Lua 5.1 and LuaJIT 2.0 and when [[#ngx.location.capture|ngx.location.capture]] is called, [[#ngx.exec|ngx.exec]], [[#ngx.exit|ngx.exit]] or [[#ngx.req.read_body|ngx.req.read_body]] or similar in the file to be loaded by <code>dofile</code>, a coroutine yield across the C function boundary will be initiated. This however is not allowed within ngx_lua and will usually result in error messages like <code>lua handler aborted: runtime error: attempt to yield across C-call boundary</code>. To avoid this, define a real Lua module and use the Lua <code>require</code> builtin instead.
2902
* Because the standard Lua 5.1 interpreter's VM is not fully resumable, the methods [[#ngx.location.capture|ngx.location.capture]], [[#ngx.location.capture_multi|ngx.location.capture_multi]], [[#ngx.redirect|ngx.redirect]], [[#ngx.exec|ngx.exec]], and [[#ngx.exit|ngx.exit]] cannot be used within the context of a Lua [http://www.lua.org/manual/5.1/manual.html#pdf-pcall pcall()] or [http://www.lua.org/manual/5.1/manual.html#pdf-xpcall xpcall()] when the standard Lua 5.1 interpreter is used and the <code>attempt to yield across metamethod/C-call boundary</code> error will be produced. Please use LuaJIT 2.0, which supports a fully resumable VM, to avoid this.
2850
2904
== Lua Variable Scope ==
2851
2905
Care should be taken when importing modules and this form should be used:
3021
3075
= Installation =
3023
You may wish to consider using the ngx_openresty bundle to install Nginx, ngx_lua, either one of the Standard Lua interpreter or LuaJIT, as well as a package of powerful companion Nginx modules:
3025
http://openresty.org
3027
The basic installation step is a simple <code>./configure --with-luajit && make && make install</code>.
3029
Alternatively, you can manually compile ngx_lua into Nginx:
3031
# Install Lua 5.1 or LuaJIT 2.0 (Recommended). Lua can be obtained free from the [http://www.lua.org/ Lua homepage]. Your distribution package manager may also distribute Lua.
3077
The [http://openresty.org ngx_openresty bundle] can be used to install Nginx, <code>ngx_lua</code>, either one of the standard Lua 5.1 interpreter or LuaJIT 2.0, as well as a package of powerful companion Nginx modules. The basic installation step is a simple <code>./configure --with-luajit && make && make install</code>.
3079
Alternatively, <code>ngx_lua</code> can be manually compiled into Nginx:
3081
# Install LuaJIT 2.0 (Recommended) or Lua 5.1. Lua can be obtained free from the [http://luajit.org/download.html the LuaJIT download page] or [http://www.lua.org/ the standard Lua homepage]. Some distribution package managers also distribute Lua and LuaJIT.
3032
3082
# Download the latest version of the ngx_devel_kit (NDK) module [http://github.com/simpl/ngx_devel_kit/tags HERE].
3033
3083
# Download the latest version of this module [http://github.com/chaoslawful/lua-nginx-module/tags HERE].
3034
3084
# Download the latest version of Nginx [http://nginx.org/ HERE] (See [[#Nginx Compatibility|Nginx Compatibility]])
3036
3086
Build the source with this module:
3038
3088
<geshi lang="bash">
3039
wget 'http://nginx.org/download/nginx-1.0.10.tar.gz'
3040
tar -xzvf nginx-1.0.10.tar.gz
3089
wget 'http://nginx.org/download/nginx-1.0.11.tar.gz'
3090
tar -xzvf nginx-1.0.11.tar.gz
3043
3093
# tell nginx's build system where to find lua:
3044
3094
export LUA_LIB=/path/to/lua/lib
3045
3095
export LUA_INC=/path/to/lua/include
3047
# or tell where to find LuaJIT when you want to use JIT instead
3097
# or tell where to find LuaJIT when if using JIT instead
3048
3098
# export LUAJIT_LIB=/path/to/luajit/lib
3049
3099
# export LUAJIT_INC=/path/to/luajit/include/luajit-2.0
3051
# Here we assume you would install you nginx under /opt/nginx/.
3101
# Here we assume Nginx is to be installed under /opt/nginx/.
3052
3102
./configure --prefix=/opt/nginx \
3053
3103
--add-module=/path/to/ngx_devel_kit \
3054
3104
--add-module=/path/to/lua-nginx-module
3078
3128
== Longer Term ==
3079
3129
* add the <code>lua_require</code> directive to load module into main thread's globals.
3080
* add the "cosocket" mechamism that will emulate a common set of Lua socket API that will give you totally transparently non-blocking capability out of the box by means of a completely new upstream layer atop the nginx event model and no nginx subrequest overheads.
3130
* add the "cosocket" mechamism to emulate a common Lua socket API set that will provide transparent nonblocking capability out of the box and that avoids Nginx subrequest overheads.
3081
3131
* add Lua code automatic time slicing support by yielding and resuming the Lua VM actively via Lua's debug hooks.
3082
* make set_by_lua using the same mechanism as content_by_lua.
3083
* add coroutine API back to the Lua land.
3132
* make set_by_lua use the same mechanism as content_by_lua.
3133
* add coroutine API back to Lua.
3134
* add <code>stat</code> mode similar to <code>mod_lua</code>.
3142
* bugfix: [[#ngx.exit|ngx.exit]], [[#ngx.redirect|ngx.redirect]], [[#ngx.exec|ngx.exec]], and [[#ngx.req.set_uri|ngx.req.set_uri(uri, true)]] could return (they should never return as per the documentation). this bug had appeared in ngx_lua v0.3.1rc4 and ngx_openresty 1.0.6.13. thanks [http://weibo.com/cyberty @cyberty] for reporting it.
3143
* bugfix: <code>ngx_http_lua_header_filter_init</code> was called with an argument which actually accepts none. this could cause compilation errors at least with gcc 4.3.4 as reported in [http://github.com/chaoslawful/lua-nginx-module/issues/80 github issue #80]. thanks bigplum (Simon).
3144
* bugfix: fixed all the warnings from the clang static analyzer.
3145
* feature: allow use of the <code>DDEBUG</code> macro from the outside (via the <code>-D DDEBUG=1</code> C compiler opton).
3151
* bugfix: fixed a bug when the both the main request and the subrequest are POST requests with a body: we should not forward the main request's <code>Content-Length</code> headers to the user subrequests. thanks 朱峰.
3152
* feature: implemented the API for reading response headers from within Lua: <code>value = ngx.header.HEADER</code>, see [[#ngx.header.HEADER|ngx.header.HEADER]].
3153
* bugfix: fixed a bug when setting a multi-value response header to a single value (via writing to [[#ngx.header.HEADER|ngx.header.HEADER]]): the single value will be repeated on each old value.
3154
* bugfix: fixed an issue in [[#ngx.redirect|ngx.redirect]], [[#ngx.exit|ngx.exit]], and [[#ngx.exec|ngx.exec]]: these function calls would be intercepted by Lua <code>pcall</code>/<code>xpcall</code> because they used Lua exceptions; now they use Lua yield just as [[#ngx.location.capture|ngx.location.capture]]. thanks @hugozhu for reporting this.
3155
* feature: now we also return the <code>Last-Modified</code> header (if any) for the subrequest response object. thanks @cyberty and sexybabes.
3156
* feature: now [[#ngx.exec|ngx.exec]] supports Lua table as the second args argument value. thanks sexybabes.
3157
* feature: implemented the [[#ngx.headers_sent|ngx.headers_sent]] API to check if response headers are sent (by ngx_lua). thanks @hugozhu.
3158
* feature: exposes the CRC-32 API of the Nginx core to the Lua land, in the form of the [[#ngx.crc32_short|ngx.crc32_short]] and [[#ngx.crc32_long|ngx.crc32_long]] methods. thanks @Lance.
3159
* feature: now for HTTP 1.0 requests, we disable the automatic full buffering mode if the user sets the <code>Content-Length</code> response header before sending out the headers. this allows streaming output for HTTP 1.0 requests if the content length can be calculated beforehand. thanks 李子义.
3160
* bugfix: now we properly support setting the <code>Cache-Control</code> response header via the [[#ngx.header.HEADER|ngx.header.HEADER]] interface.
3161
* bugfix: no longer set header hash to <code>1</code>. use the <code>ngx_hash_key_lc</code> instead.
3162
* bugfix: calling [[#ngx.exec|ngx.exec]] to jump to a named location did not clear the context object of LuaNginxModule properly and might cause evil problems. thanks Nginx User.
3163
* bugfix: now we explicitly clear all the modules' contexts before dump to named location with [[#ngx.exec|ngx.exec]].
3164
* feature: implemented [[#ngx.req.set_uri|ngx.req.set_uri]] and [[#ngx.req.set_uri_args|ngx.req.set_uri_args]] to emulate [[HttpRewriteModule]]'s [[HttpRewriteModule#rewrite|rewrite]] directive. thanks Vladimir Protasov (utros) and Nginx User.
3165
* bugfix: now we skip rewrite phase Lua handlers altogether if [[HttpRewriteModule]]'s [[HttpRewriteModule#rewrite|rewrite]] directive issue a location re-lookup by changing URIs (but not including <code>rewrite ... break</code>). thanks Nginx User.
3166
* feature: added constant <code>ngx.HTTP_METHOD_NOT_IMPLEMENTED (501)</code>. thanks Nginx User.
3167
* feature: added new Lua functions [[#ngx.req.read_body|ngx.req.read_body]], [[#ngx.req.discard_body|ngx.req.discard_body]], [[#ngx.req.get_body_data|ngx.req.get_body_data]], and [[#ngx.req.get_body_file|ngx.req.get_body_file]]. thanks Tzury Bar Yochay for funding the development work.
3168
* bugfix: fixed hanging issues when using [[#ngx.exec|ngx.exec]] within [[#rewrite_by_lua|rewrite_by_lua]] and [[#access_by_lua|access_by_lua]]. thanks Nginx User for reporting it.
3169
* feature: added new Lua API [[#ngx.req.set_body_file|ngx.req.set_body_file]]. thanks Tzury Bar Yochay for funding the development work.
3170
* feature: added new Lua API [[#ngx.req.set_body_data|ngx.req.set_body_data]]. thanks Tzury Bar Yochay for funding the development work.
3171
* bugfix: [[#lua_need_request_body|lua_need_request_body]] should not skip requests with methods other than <code>POST</code> and <code>PUT</code>. thanks Nginx User.
3172
* bugfix: no longer free request body buffers that are not allocated by ourselves.
3173
* bugfix: now we allow setting [[#ngx.var.VARIABLE|ngx.var.VARIABLE]] to nil.
3174
* feature: added new directive [[#lua_shared_dict|lua_shared_dict]].
3175
* feature: added Lua API for the shm-based dictionary, see [[#ngx.shared.DICT|ngx.shared.DICT]].
3176
* bugfix: fixed spots of -Werror=unused-but-set-variable warning issued by gcc 4.6.0.
3177
* bugfix: [[#ndk.set_var.DIRECTIVE|ndk.set_var.DIRECTIVE]] had a memory issue and might pass empty argument values to the directive being called. thanks dannynoonan.
3178
* feature: added the <code>ctx</code> option to [[#ngx.location.capture|ngx.location.capture]]: you can now specify a custom Lua table to pass to the subrequest as its [[#ngx.ctx|ngx.ctx]]. thanks @hugozhu.
3179
* feature: added the [[#ngx.encode_args|ngx.encode_args]] method to encode a Lua code to a URI query string. thanks 郭颖 (0597虾).
3180
* feature: [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.exec|ngx.exec]] now supports the same Lua args table format as in ngx.encode_args. thanks 郭颖 (0597虾).
3181
* bugfix: <code>Cache-Control</code> header modification might introduce empty value headers when using with the standard HttpHeadersModule.
3182
* feature: added [[#ngx.hmac_sha1|ngx.hmac_sha1]]. thanks drdrxp.
3183
* docs: documented the long-existent [[#ngx.md5|ngx.md5]] and [[#ngx.md5_bin|ngx.md5_bin]] APIs.
3184
* docs: massive documentation improvements. thanks Nginx User.
3185
* feature: added new regex options <code>j</code> and <code>d</code> to [[#ngx.re.match|ngx.re.match]], [[#ngx.re.gmatch|ngx.re.gmatch]], [[#ngx.re.sub|ngx.re.sub]], and [[#ngx.re.gsub|ngx.re.gsub]] so as to enable the PCRE JIT mode and DFA mode, respectively. thanks @姜大炮 for providing the patch.
3186
* feature: added options <code>copy_all_vars</code> and <code>vars</code> to [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]]. thanks Marcus Clyne for the patch.
3187
* feature: added new Lua API [[#ngx.now|ngx.now]] to return the current time (including the milliseconds part as the decimal part). thanks 林青.
3188
* feature: added new Lua API [[#ngx.update_time|ngx.update_time]] to forcibly updating Nginx's time cache.
3189
* feature: added <code>wait</code> boolean argument to [[#ngx.flush|ngx.flush]] to support synchronous flushing: <code>ngx.flush(true)</code> will not return until all the data has been flushed into the system send buffer or the send timeout has expired.
3190
* bugfix: now we check timed out downstream connections in our write event handler.
3191
* feature: added constant <code>ngx.HTTP_GATEWAY_TIMEOUT (504)</code> per Fry-kun in [https://github.com/chaoslawful/lua-nginx-module/issues/73 github issue #73].
3192
* bugfix: [[#ngx.var.VARIABLE|ngx.var.VARIABLE]] did not evaluate to <code>nil</code> when the Nginx variable's <code>valid</code> flag is <code>0</code>.
3193
* bugfix: there were various places where we did not check the pointer returned by the memory allocator.
3194
* bugfix: [[#ngx.req.set_header|ngx.req.set_header]] and [[#ngx.req.clear_header|ngx.req.clear_header]] did not handle the <code>Accept-Encoding</code> request headers properly. thanks 天街夜色.
3195
* bugfix: [[#ngx.req.set_header|ngx.req.set_header]] might cause invalid memory reads because Nginx request header values must be <code>NULL</code> terminated. thanks Maxim Dounin.
3196
* bugfix: removing builtin headers via [[#ngx.req.clear_header|ngx.req.clear_header]] and its equivalent in huge request headers with 20+ entries could result in data loss. thanks Chris Dumoulin.
3197
* bugfix: [[#ngx.req.get_uri_args|ngx.req.get_uri_args]] and [[#ngx.req.get_post_args|ngx.req.get_post_args]] now only parse up to <code>100</code> arguments by default. but one can specify the optional argument to these two methods to specify a custom maximum number of args. thanks Tzury Bar Yochay for reporting this.
3198
* bugfix: [[#ngx.req.get_headers|ngx.req.get_headers]] now only parse up to <code>100</code> request headers by default. but one can specify the optional argument to this method to specify a custom maximum number of headers.
3088
3204
'''New features'''
3090
3206
* added the [[#header_filter_by_lua|header_filter_by_lua]] and [[#header_filter_by_lua_file|header_filter_by_lua_file]] directives. thanks Liseen Wan (万珣新).
added
removed
debian/modules/nginx-lua/doc/HttpLuaModule.wiki
