doc: moved the "Directives" and "Nginx API for Lua" sections to the end because they are too long and kinda boring :) thanks Pierre-Yves Gérardy for the patch in #371.
This commit is contained in:
Yichun Zhang (agentzh)
Родитель
a9e0111fe9
Коммит
c91e1f5258
1133
README.markdown
1133
README.markdown
Разница между файлами не показана из-за своего большого размера
Загрузить разницу
|
|
@ -229,8 +229,6 @@ Other scripting language implementations typically struggle to match this perfor
|
|||
|
||||
The Lua state (Lua VM instance) is shared across all the requests handled by a single nginx worker process to minimize memory use.
|
||||
|
||||
On a ThinkPad T400 2.80 GHz laptop, the Hello World example readily achieves 28k req/sec using <code>http_load -p 10</code>. By contrast, Nginx + php-fpm 5.2.8 + Unix Domain Socket yields 6k req/sec and [http://nodejs.org/ Node.js] v0.6.1 yields 10.2k req/sec for their Hello World equivalents.
|
||||
|
||||
= Nginx Compatibility =
|
||||
The latest module is compatible with the following versions of Nginx:
|
||||
|
||||
|
|
@ -321,8 +319,469 @@ Please submit bug reports, wishlists, or patches by
|
|||
# creating a ticket on the [https://github.com/openresty/lua-nginx-module/issues GitHub Issue Tracker],
|
||||
# or posting to the [[#Community|OpenResty community]].
|
||||
|
||||
= Lua/LuaJIT bytecode support =
|
||||
|
||||
As from the <code>v0.5.0rc32</code> release, all <code>*_by_lua_file</code> configure directives (such as [[#content_by_lua_file|content_by_lua_file]]) support loading Lua 5.1 and LuaJIT 2.0/2.1 raw bytecode files directly.
|
||||
|
||||
Please note that the bytecode format used by LuaJIT 2.0/2.1 is not compatible with that used by the standard Lua 5.1 interpreter. So if using LuaJIT 2.0/2.1 with ngx_lua, LuaJIT compatible bytecode files must be generated as shown:
|
||||
|
||||
<geshi lang="bash">
|
||||
/path/to/luajit/bin/luajit -b /path/to/input_file.lua /path/to/output_file.luac
|
||||
</geshi>
|
||||
|
||||
The <code>-bg</code> option can be used to include debug information in the LuaJIT bytecode file:
|
||||
|
||||
<geshi lang="bash">
|
||||
/path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.luac
|
||||
</geshi>
|
||||
|
||||
Please refer to the official LuaJIT documentation on the <code>-b</code> option for more details:
|
||||
|
||||
http://luajit.org/running.html#opt_b
|
||||
|
||||
Also, the bytecode files generated by LuaJIT 2.1 is ''not'' compatible with LuaJIT 2.0, and vice versa. The support for LuaJIT 2.1 bytecode was first added in ngx_lua v0.9.3.
|
||||
|
||||
Similarly, if using the standard Lua 5.1 interpreter with ngx_lua, Lua compatible bytecode files must be generated using the <code>luac</code> commandline utility as shown:
|
||||
|
||||
<geshi lang="bash">
|
||||
luac -o /path/to/output_file.luac /path/to/input_file.lua
|
||||
</geshi>
|
||||
|
||||
Unlike as with LuaJIT, debug information is included in standard Lua 5.1 bytecode files by default. This can be striped out by specifying the <code>-s</code> option as shown:
|
||||
|
||||
<geshi lang="bash">
|
||||
luac -s -o /path/to/output_file.luac /path/to/input_file.lua
|
||||
</geshi>
|
||||
|
||||
Attempts to load standard Lua 5.1 bytecode files into ngx_lua instances linked to LuaJIT 2.0/2.1 or vice versa, will result in an error message, such as that below, being logged into the Nginx <code>error.log</code> file:
|
||||
|
||||
<geshi lang="text">
|
||||
[error] 13909#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test_file.luac
|
||||
</geshi>
|
||||
|
||||
Loading bytecode files via the Lua primitives like <code>require</code> and <code>dofile</code> should always work as expected.
|
||||
|
||||
= System Environment Variable Support =
|
||||
|
||||
If you want to access the system environment variable, say, <code>foo</code>, in Lua via the standard Lua API [http://www.lua.org/manual/5.1/manual.html#pdf-os.getenv os.getenv], then you should also list this environment variable name in your <code>nginx.conf</code> file via the [http://nginx.org/en/docs/ngx_core_module.html#env env directive]. For example,
|
||||
|
||||
<geshi lang="nginx">
|
||||
env foo;
|
||||
</geshi>
|
||||
|
||||
= HTTP 1.0 support =
|
||||
|
||||
The HTTP 1.0 protocol does not support chunked output and requires an explicit <code>Content-Length</code> header when the response body is not empty in order to support the HTTP 1.0 keep-alive.
|
||||
So when a HTTP 1.0 request is made and the [[#lua_http10_buffering|lua_http10_buffering]] directive is turned <code>on</code>, ngx_lua will buffer the
|
||||
output of [[#ngx.say|ngx.say]] and [[#ngx.print|ngx.print]] calls and also postpone sending response headers until all the response body output is received.
|
||||
At that time ngx_lua can calculate the total length of the body and construct a proper <code>Content-Length</code> header to return to the HTTP 1.0 client.
|
||||
If the <code>Content-Length</code> response header is set in the running Lua code, however, this buffering will be disabled even if the [[#lua_http10_buffering|lua_http10_buffering]] directive is turned <code>on</code>.
|
||||
|
||||
For large streaming output responses, it is important to disable the [[#lua_http10_buffering|lua_http10_buffering]] directive to minimise memory usage.
|
||||
|
||||
Note that common HTTP benchmark tools such as <code>ab</code> and <code>http_load</code> issue HTTP 1.0 requests by default.
|
||||
To force <code>curl</code> to send HTTP 1.0 requests, use the <code>-0</code> option.
|
||||
|
||||
= Statically Linking Pure Lua Modules =
|
||||
|
||||
When LuaJIT 2.x is used, it is possible to statically link the bytecode of pure Lua modules into the Nginx executable.
|
||||
|
||||
Basically you use the <code>luajit</code> executable to compile <code>.lua</code> Lua module files to <code>.o</code> object files containing the exported bytecode data, and then link the <code>.o</code> files directly in your Nginx build.
|
||||
|
||||
Below is a trivial example to demonstrate this. Consider that we have the following <code>.lua</code> file named <code>foo.lua</code>:
|
||||
|
||||
<geshi lang="lua">
|
||||
-- foo.lua
|
||||
local _M = {}
|
||||
|
||||
function _M.go()
|
||||
print("Hello from foo")
|
||||
end
|
||||
|
||||
return _M
|
||||
</geshi>
|
||||
|
||||
And then we compile this <code>.lua</code> file to <code>foo.o</code> file:
|
||||
|
||||
/path/to/luajit/bin/luajit -bg foo.lua foo.o
|
||||
|
||||
What matters here is the name of the <code>.lua</code> file, which determines how you use this module later on the Lua land. The file name <code>foo.o</code> does not matter at all except the <code>.o</code> file extension (which tells <code>luajit</code> what output format is used). If you want to strip the Lua debug information from the resulting bytecode, you can just specify the <code>-b</code> option above instead of <code>-bg</code>.
|
||||
|
||||
Then when building Nginx or OpenResty, pass the <code>--with-ld-opt="foo.o"</code> option to the <code>./configure</code> script:
|
||||
|
||||
<geshi lang="bash">
|
||||
./configure --with-ld-opt="/path/to/foo.o" ...
|
||||
</geshi>
|
||||
|
||||
Finally, you can just do the following in any Lua code run by ngx_lua:
|
||||
|
||||
<geshi lang="lua">
|
||||
local foo = require "foo"
|
||||
foo.go()
|
||||
</geshi>
|
||||
|
||||
And this piece of code no longer depends on the external <code>foo.lua</code> file any more because it has already been compiled into the <code>nginx</code> executable.
|
||||
|
||||
If you want to use dot in the Lua module name when calling <code>require</code>, as in
|
||||
|
||||
<geshi lang="lua">
|
||||
local foo = require "resty.foo"
|
||||
</geshi>
|
||||
|
||||
then you need to rename the <code>foo.lua</code> file to <code>resty_foo.lua</code> before compiling it down to a <code>.o</code> file with the <code>luajit</code> command-line utility.
|
||||
|
||||
It is important to use exactly the same version of LuaJIT when compiling <code>.lua</code> files to <code>.o</code> files as building nginx + ngx_lua. This is because the LuaJIT bytecode format may be incompatible between different LuaJIT versions. When the bytecode format is incompatible, you will see a Lua runtime error saying that the Lua module is not found.
|
||||
|
||||
When you have multiple <code>.lua</code> files to compile and link, then just specify their <code>.o</code> files at the same time in the value of the <code>--with-ld-opt</code> option. For instance,
|
||||
|
||||
<geshi lang="bash">
|
||||
./configure --with-ld-opt="/path/to/foo.o /path/to/bar.o" ...
|
||||
</geshi>
|
||||
|
||||
If you have just too many <code>.o</code> files, then it might not be feasible to name them all in a single command. In this case, you can build a static library (or archive) for your <code>.o</code> files, as in
|
||||
|
||||
<geshi lang="bash">
|
||||
ar rcus libmyluafiles.a *.o
|
||||
</geshi>
|
||||
|
||||
then you can link the <code>myluafiles</code> archive as a whole to your nginx executable:
|
||||
|
||||
<geshi lang="bash">
|
||||
./configure \
|
||||
--with-ld-opt="-L/path/to/lib -Wl,--whole-archive -lmyluafiles -Wl,--no-whole-archive"
|
||||
</geshi>
|
||||
|
||||
where <code>/path/to/lib</code> is the path of the directory containing the <code>libmyluafiles.a</code> file. It should be noted that the linker option <code>--whole-archive</code> is required here because otherwise our archive will be skipped because no symbols in our archive are mentioned in the main parts of the nginx executable.
|
||||
|
||||
= Data Sharing within an Nginx Worker =
|
||||
|
||||
To globally share data among all the requests handled by the same nginx worker process, encapsulate the shared data into a Lua module, use the Lua <code>require</code> builtin to import the module, and then manipulate the shared data in Lua. This works because required Lua modules are loaded only once and all coroutines will share the same copy of the module (both its code and data). Note however that Lua global variables (note, not module-level variables) WILL NOT persist between requests because of the one-coroutine-per-request isolation design.
|
||||
|
||||
Here is a complete small example:
|
||||
|
||||
<geshi lang="lua">
|
||||
-- mydata.lua
|
||||
local _M = {}
|
||||
|
||||
local data = {
|
||||
dog = 3,
|
||||
cat = 4,
|
||||
pig = 5,
|
||||
}
|
||||
|
||||
function _M.get_age(name)
|
||||
return data[name]
|
||||
end
|
||||
|
||||
return _M
|
||||
</geshi>
|
||||
|
||||
and then accessing it from <code>nginx.conf</code>:
|
||||
|
||||
<geshi lang="nginx">
|
||||
location /lua {
|
||||
content_by_lua '
|
||||
local mydata = require "mydata"
|
||||
ngx.say(mydata.get_age("dog"))
|
||||
';
|
||||
}
|
||||
</geshi>
|
||||
|
||||
The <code>mydata</code> module in this example will only be loaded and run on the first request to the location <code>/lua</code>,
|
||||
and all subsequent requests to the same nginx worker process will use the reloaded instance of the
|
||||
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.
|
||||
This data sharing technique is essential for high performance Lua applications based on this module.
|
||||
|
||||
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.
|
||||
|
||||
If server-wide data sharing is required, then use one or more of the following approaches:
|
||||
|
||||
# Use the [[#ngx.shared.DICT|ngx.shared.DICT]] API provided by this module.
|
||||
# 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).
|
||||
# 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 and Lua libraries that provide interfaces with these data storage mechanisms.
|
||||
|
||||
= Known Issues =
|
||||
|
||||
== TCP socket connect operation issues ==
|
||||
The [[#tcpsock:connect|tcpsock:connect]] method may indicate <code>success</code> despite connection failures such as with <code>Connection Refused</code> errors.
|
||||
|
||||
However, later attempts to manipulate the cosocket object will fail and return the actual error status message generated by the failed connect operation.
|
||||
|
||||
This issue is due to limitations in the Nginx event model and only appears to affect Mac OS X.
|
||||
|
||||
== Lua Coroutine Yielding/Resuming ==
|
||||
* Lua's <code>dofile</code> builtin is implemented as a C function in both Lua 5.1 and LuaJIT 2.0/2.1 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 normally 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.
|
||||
* As 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()] or even the first line of the <code>for ... in ...</code> statement 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.x, which supports a fully resumable VM, to avoid this.
|
||||
|
||||
== Lua Variable Scope ==
|
||||
Care must be taken when importing modules and this form should be used:
|
||||
|
||||
<geshi lang="lua">
|
||||
local xxx = require('xxx')
|
||||
</geshi>
|
||||
|
||||
instead of the old deprecated form:
|
||||
|
||||
<geshi lang="lua">
|
||||
require('xxx')
|
||||
</geshi>
|
||||
|
||||
Here is the reason: by design, the global environment has exactly the same lifetime as the Nginx request handler associated with it. Each request handler has its own set of Lua global variables and that is the idea of request isolation. The Lua module is actually loaded by the first Nginx request handler and is cached by the <code>require()</code> built-in in the package.loaded table for later reference, and <code>require()</code> has the side effect of setting a global variable to the loaded module table. But this global variable will be cleared at the end of the request handler, and every subsequent request handler all has its own (clean) global environment. So one will get Lua exception for accessing the <code>nil</code> value.
|
||||
|
||||
Generally, use of Lua global variables is a really really bad idea in the context of ngx_lua because
|
||||
|
||||
# misuse of Lua globals has very bad side effects for concurrent requests when these variables are actually supposed to be local only,
|
||||
# Lua global variables require Lua table look-up in the global environment (which is just a Lua table), which is kinda expensive, and
|
||||
# some Lua global variable references are just typos, which are hard to debug.
|
||||
|
||||
It's *highly* recommended to always declare them via "local" in the scope that is reasonable.
|
||||
|
||||
To find out all the uses of Lua global variables in your Lua code, you can run the [https://github.com/openresty/nginx-devel-utils/blob/master/lua-releng lua-releng tool] across all your .lua source files:
|
||||
<geshi lang="text">
|
||||
$ lua-releng
|
||||
Checking use of Lua global variables in file lib/foo/bar.lua ...
|
||||
1 [1489] SETGLOBAL 7 -1 ; contains
|
||||
55 [1506] GETGLOBAL 7 -3 ; setvar
|
||||
3 [1545] GETGLOBAL 3 -4 ; varexpand
|
||||
</geshi>
|
||||
The output says that the line 1489 of file <code>lib/foo/bar.lua</code> writes to a global variable named <code>contains</code>, the line 1506 reads from the global variable <code>setvar</code>, and line 1545 reads the global <code>varexpand</code>.
|
||||
|
||||
This tool will guarantee that local variables in the Lua module functions are all declared with the <code>local</code> keyword, otherwise a runtime exception will be thrown. It prevents undesirable race conditions while accessing such variables. See [[#Data_Sharing_within_an_Nginx_Worker|Data Sharing within an Nginx Worker]] for the reasons behind this.
|
||||
|
||||
== Locations Configured by Subrequest Directives of Other Modules ==
|
||||
The [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]] directives cannot capture locations that include the [[HttpEchoModule#echo_location|echo_location]], [[HttpEchoModule#echo_location_async|echo_location_async]], [[HttpEchoModule#echo_subrequest|echo_subrequest]], or [[HttpEchoModule#echo_subrequest_async|echo_subrequest_async]] directives.
|
||||
|
||||
<geshi lang="nginx">
|
||||
location /foo {
|
||||
content_by_lua '
|
||||
res = ngx.location.capture("/bar")
|
||||
';
|
||||
}
|
||||
location /bar {
|
||||
echo_location /blah;
|
||||
}
|
||||
location /blah {
|
||||
echo "Success!";
|
||||
}
|
||||
</geshi>
|
||||
|
||||
<geshi lang="nginx">
|
||||
$ curl -i http://example.com/foo
|
||||
</geshi>
|
||||
|
||||
will not work as expected.
|
||||
|
||||
== Special PCRE Sequences ==
|
||||
PCRE sequences such as <code>\d</code>, <code>\s</code>, or <code>\w</code>, require special attention because in string literals, the backslash character, <code>\</code>, is stripped out by both the Lua language parser and by the Nginx config file parser before processing. So the following snippet will not work as expected:
|
||||
|
||||
<geshi lang="nginx">
|
||||
# nginx.conf
|
||||
? location /test {
|
||||
? content_by_lua '
|
||||
? local regex = "\d+" -- THIS IS WRONG!!
|
||||
? local m = ngx.re.match("hello, 1234", regex)
|
||||
? if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
? ';
|
||||
? }
|
||||
# evaluates to "not matched!"
|
||||
</geshi>
|
||||
|
||||
To avoid this, ''double'' escape the backslash:
|
||||
|
||||
<geshi lang="nginx">
|
||||
# nginx.conf
|
||||
location /test {
|
||||
content_by_lua '
|
||||
local regex = "\\\\d+"
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
';
|
||||
}
|
||||
# evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
Here, <code>\\\\d+</code> is stripped down to <code>\\d+</code> by the Nginx config file parser and this is further stripped down to <code>\d+</code> by the Lua language parser before running.
|
||||
|
||||
Alternatively, the regex pattern can be presented as a long-bracketed Lua string literal by encasing it in "long brackets", <code>[[...]]</code>, in which case backslashes have to only be escaped once for the Nginx config file parser.
|
||||
|
||||
<geshi lang="nginx">
|
||||
# nginx.conf
|
||||
location /test {
|
||||
content_by_lua '
|
||||
local regex = [[\\d+]]
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
';
|
||||
}
|
||||
# evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
Here, <code>[[\\d+]]</code> is stripped down to <code>[[\d+]]</code> by the Nginx config file parser and this is processed correctly.
|
||||
|
||||
Note that a longer from of the long bracket, <code>[=[...]=]</code>, may be required if the regex pattern contains <code>[...]</code> sequences.
|
||||
The <code>[=[...]=]</code> form may be used as the default form if desired.
|
||||
|
||||
<geshi lang="nginx">
|
||||
# nginx.conf
|
||||
location /test {
|
||||
content_by_lua '
|
||||
local regex = [=[[0-9]+]=]
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
';
|
||||
}
|
||||
# evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
An alternative approach to escaping PCRE sequences is to ensure that Lua code is placed in external script files and executed using the various <code>*_by_lua_file</code> directives.
|
||||
With this approach, the backslashes are only stripped by the Lua language parser and therefore only need to be escaped once each.
|
||||
|
||||
<geshi lang="lua">
|
||||
-- test.lua
|
||||
local regex = "\\d+"
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
-- evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
Within external script files, PCRE sequences presented as long-bracketed Lua string literals do not require modification.
|
||||
|
||||
<geshi lang="lua">
|
||||
-- test.lua
|
||||
local regex = [[\d+]]
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
-- evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
== Mixing with SSI Not Supported ==
|
||||
|
||||
Mixing SSI with ngx_lua in the same Nginx request is not supported at all. Just use ngx_lua exclusively. Everything you can do with SSI can be done atop ngx_lua anyway and it can be more efficient when using ngx_lua.
|
||||
|
||||
== SPDY Mode Not Fully Supported ==
|
||||
|
||||
Certain Lua APIs provided by ngx_lua do not work in Nginx's SPDY mode yet: [[#ngx.location.capture|ngx.location.capture]], [[#ngx.location.capture_multi|ngx.location.capture_multi]], and [[#ngx.req.socket|ngx.req.socket]].
|
||||
|
||||
= TODO =
|
||||
|
||||
== Short Term ==
|
||||
* implement the SSL cosocket API.
|
||||
* review and apply Jader H. Silva's patch for <code>ngx.re.split()</code>.
|
||||
* review and apply vadim-pavlov's patch for [[#ngx.location.capture|ngx.location.capture]]'s <code>extra_headers</code> option
|
||||
* 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.
|
||||
* add configure options for different strategies of handling the cosocket connection exceeding in the pools.
|
||||
* add directives to run Lua codes when nginx stops.
|
||||
* 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.
|
||||
|
||||
== Longer Term ==
|
||||
* add automatic Lua code time slicing support by yielding and resuming the Lua VM actively via Lua's debug hooks.
|
||||
* add <code>stat</code> mode similar to [https://httpd.apache.org/docs/trunk/mod/mod_lua.html mod_lua].
|
||||
|
||||
= Changes =
|
||||
|
||||
The changes of every release of this module can be obtained from the ngx_openresty bundle's change logs:
|
||||
|
||||
http://openresty.org/#Changes
|
||||
|
||||
= Test Suite =
|
||||
|
||||
The following dependencies are required to run the test suite:
|
||||
|
||||
* Nginx version >= 1.4.2
|
||||
|
||||
* Perl modules:
|
||||
** Test::Nginx: http://github.com/openresty/test-nginx
|
||||
|
||||
* Nginx modules:
|
||||
** [https://github.com/simpl/ngx_devel_kit ngx_devel_kit]
|
||||
** [http://github.com/openresty/set-misc-nginx-module ngx_set_misc]
|
||||
** [http://mdounin.ru/files/ngx_http_auth_request_module-0.2.tar.gz ngx_auth_request] (this is not needed if you're using Nginx 1.5.4+.
|
||||
** [http://github.com/openresty/echo-nginx-module ngx_echo]
|
||||
** [http://github.com/openresty/memc-nginx-module ngx_memc]
|
||||
** [http://github.com/openresty/srcache-nginx-module ngx_srcache]
|
||||
** ngx_lua (i.e., this module)
|
||||
** [http://github.com/openresty/lua-upstream-nginx-module ngx_lua_upstream]
|
||||
** [http://github.com/openresty/headers-more-nginx-module ngx_headers_more]
|
||||
** [http://github.com/openresty/drizzle-nginx-module ngx_drizzle]
|
||||
** [http://github.com/openresty/rds-json-nginx-module ngx_rds_json]
|
||||
** [https://github.com/FRiCKLE/ngx_coolkit ngx_coolkit]
|
||||
** [http://github.com/openresty/redis2-nginx-module ngx_redis2]
|
||||
|
||||
The order in which these modules are added during configuration is important because the position of any filter module in the
|
||||
filtering chain determines the final output, for example. The correct adding order is shown above.
|
||||
|
||||
* 3rd-party Lua libraries:
|
||||
** [http://www.kyne.com.au/~mark/software/lua-cjson.php lua-cjson]
|
||||
|
||||
* Applications:
|
||||
** mysql: create database 'ngx_test', grant all privileges to user 'ngx_test', password is 'ngx_test'
|
||||
** memcached: listening on the default port, 11211.
|
||||
** redis: listening on the default port, 6379.
|
||||
|
||||
See also the [https://github.com/openresty/lua-nginx-module/blob/master/util/build2.sh developer build script] for more details on setting up the testing environment.
|
||||
|
||||
To run the whole test suite in the default testing mode:
|
||||
<geshi lang="text">
|
||||
cd /path/to/lua-nginx-module
|
||||
export PATH=/path/to/your/nginx/sbin:$PATH
|
||||
prove -I/path/to/test-nginx/lib -r t
|
||||
</geshi>
|
||||
|
||||
To run specific test files:
|
||||
<geshi lang="text">
|
||||
cd /path/to/lua-nginx-module
|
||||
export PATH=/path/to/your/nginx/sbin:$PATH
|
||||
prove -I/path/to/test-nginx/lib t/002-content.t t/003-errors.t
|
||||
</geshi>
|
||||
|
||||
To run a specific test block in a particular test file, add the line <code>--- ONLY</code> to the test block you want to run, and then use the `prove` utility to run that <code>.t</code> file.
|
||||
|
||||
There are also various testing modes based on mockeagain, valgrind, and etc. Refer to the [http://search.cpan.org/perldoc?Test::Nginx Test::Nginx documentation] for more details for various advanced testing modes. See also the test reports for the Nginx test cluster running on Amazon EC2: http://qa.openresty.org.
|
||||
|
||||
= Copyright and License =
|
||||
|
||||
This module is licensed under the BSD license.
|
||||
|
||||
Copyright (C) 2009-2014, by Xiaozhe Wang (chaoslawful) <chaoslawful@gmail.com>.
|
||||
|
||||
Copyright (C) 2009-2014, by Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>, CloudFlare Inc.
|
||||
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
|
||||
|
||||
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
|
||||
|
||||
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
= See Also =
|
||||
|
||||
* [http://github.com/openresty/lua-resty-memcached lua-resty-memcached] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-redis lua-resty-redis] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-mysql lua-resty-mysql] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-upload lua-resty-upload] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-dns lua-resty-dns] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-websocket lua-resty-websocket] library for both WebSocket server and client, based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-string lua-resty-string] library based on [http://luajit.org/ext_ffi.html LuaJIT FFI].
|
||||
* [http://github.com/openresty/lua-resty-lock lua-resty-lock] library for a nonblocking simple lock API.
|
||||
* [http://openresty.org/#RoutingMySQLQueriesBasedOnURIArgs Routing requests to different MySQL queries based on URI arguments]
|
||||
* [http://openresty.org/#DynamicRoutingBasedOnRedis Dynamic Routing Based on Redis and Lua]
|
||||
* [http://openresty.org/#UsingLuaRocks Using LuaRocks with ngx_lua]
|
||||
* [https://github.com/openresty/lua-nginx-module/wiki/Introduction Introduction to ngx_lua]
|
||||
* [http://github.com/simpl/ngx_devel_kit ngx_devel_kit]
|
||||
* [[HttpEchoModule]]
|
||||
* [[HttpDrizzleModule]]
|
||||
* [http://github.com/FRiCKLE/ngx_postgres postgres-nginx-module]
|
||||
* [[HttpMemcModule]]
|
||||
* [http://openresty.org The ngx_openresty bundle]
|
||||
* [https://github.com/openresty/nginx-systemtap-toolkit Nginx Systemtap Toolkit]
|
||||
|
||||
= Directives =
|
||||
|
||||
<!-- inline-toc -->
|
||||
|
||||
== lua_use_default_type ==
|
||||
'''syntax:''' ''lua_use_default_type on | off''
|
||||
|
||||
|
|
@ -1371,6 +1830,9 @@ When exceeding this limit, Nginx will stop running the callbacks of newly expire
|
|||
This directive was first introduced in the <code>v0.8.0</code> release.
|
||||
|
||||
= Nginx API for Lua =
|
||||
|
||||
<!-- inline-toc -->
|
||||
|
||||
== 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.
|
||||
|
||||
|
|
@ -5184,462 +5646,3 @@ Identical to the standard Lua [http://www.lua.org/manual/5.1/manual.html#pdf-cor
|
|||
This API was first usable in the context of [[#init_by_lua|init_by_lua*]] since the <code>0.9.2</code>.
|
||||
|
||||
This API was first enabled in the <code>v0.6.0</code> release.
|
||||
|
||||
= Lua/LuaJIT bytecode support =
|
||||
|
||||
As from the <code>v0.5.0rc32</code> release, all <code>*_by_lua_file</code> configure directives (such as [[#content_by_lua_file|content_by_lua_file]]) support loading Lua 5.1 and LuaJIT 2.0/2.1 raw bytecode files directly.
|
||||
|
||||
Please note that the bytecode format used by LuaJIT 2.0/2.1 is not compatible with that used by the standard Lua 5.1 interpreter. So if using LuaJIT 2.0/2.1 with ngx_lua, LuaJIT compatible bytecode files must be generated as shown:
|
||||
|
||||
<geshi lang="bash">
|
||||
/path/to/luajit/bin/luajit -b /path/to/input_file.lua /path/to/output_file.luac
|
||||
</geshi>
|
||||
|
||||
The <code>-bg</code> option can be used to include debug information in the LuaJIT bytecode file:
|
||||
|
||||
<geshi lang="bash">
|
||||
/path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.luac
|
||||
</geshi>
|
||||
|
||||
Please refer to the official LuaJIT documentation on the <code>-b</code> option for more details:
|
||||
|
||||
http://luajit.org/running.html#opt_b
|
||||
|
||||
Also, the bytecode files generated by LuaJIT 2.1 is ''not'' compatible with LuaJIT 2.0, and vice versa. The support for LuaJIT 2.1 bytecode was first added in ngx_lua v0.9.3.
|
||||
|
||||
Similarly, if using the standard Lua 5.1 interpreter with ngx_lua, Lua compatible bytecode files must be generated using the <code>luac</code> commandline utility as shown:
|
||||
|
||||
<geshi lang="bash">
|
||||
luac -o /path/to/output_file.luac /path/to/input_file.lua
|
||||
</geshi>
|
||||
|
||||
Unlike as with LuaJIT, debug information is included in standard Lua 5.1 bytecode files by default. This can be striped out by specifying the <code>-s</code> option as shown:
|
||||
|
||||
<geshi lang="bash">
|
||||
luac -s -o /path/to/output_file.luac /path/to/input_file.lua
|
||||
</geshi>
|
||||
|
||||
Attempts to load standard Lua 5.1 bytecode files into ngx_lua instances linked to LuaJIT 2.0/2.1 or vice versa, will result in an error message, such as that below, being logged into the Nginx <code>error.log</code> file:
|
||||
|
||||
<geshi lang="text">
|
||||
[error] 13909#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test_file.luac
|
||||
</geshi>
|
||||
|
||||
Loading bytecode files via the Lua primitives like <code>require</code> and <code>dofile</code> should always work as expected.
|
||||
|
||||
= System Environment Variable Support =
|
||||
|
||||
If you want to access the system environment variable, say, <code>foo</code>, in Lua via the standard Lua API [http://www.lua.org/manual/5.1/manual.html#pdf-os.getenv os.getenv], then you should also list this environment variable name in your <code>nginx.conf</code> file via the [http://nginx.org/en/docs/ngx_core_module.html#env env directive]. For example,
|
||||
|
||||
<geshi lang="nginx">
|
||||
env foo;
|
||||
</geshi>
|
||||
|
||||
= HTTP 1.0 support =
|
||||
|
||||
The HTTP 1.0 protocol does not support chunked output and requires an explicit <code>Content-Length</code> header when the response body is not empty in order to support the HTTP 1.0 keep-alive.
|
||||
So when a HTTP 1.0 request is made and the [[#lua_http10_buffering|lua_http10_buffering]] directive is turned <code>on</code>, ngx_lua will buffer the
|
||||
output of [[#ngx.say|ngx.say]] and [[#ngx.print|ngx.print]] calls and also postpone sending response headers until all the response body output is received.
|
||||
At that time ngx_lua can calculate the total length of the body and construct a proper <code>Content-Length</code> header to return to the HTTP 1.0 client.
|
||||
If the <code>Content-Length</code> response header is set in the running Lua code, however, this buffering will be disabled even if the [[#lua_http10_buffering|lua_http10_buffering]] directive is turned <code>on</code>.
|
||||
|
||||
For large streaming output responses, it is important to disable the [[#lua_http10_buffering|lua_http10_buffering]] directive to minimise memory usage.
|
||||
|
||||
Note that common HTTP benchmark tools such as <code>ab</code> and <code>http_load</code> issue HTTP 1.0 requests by default.
|
||||
To force <code>curl</code> to send HTTP 1.0 requests, use the <code>-0</code> option.
|
||||
|
||||
= Statically Linking Pure Lua Modules =
|
||||
|
||||
When LuaJIT 2.x is used, it is possible to statically link the bytecode of pure Lua modules into the Nginx executable.
|
||||
|
||||
Basically you use the <code>luajit</code> executable to compile <code>.lua</code> Lua module files to <code>.o</code> object files containing the exported bytecode data, and then link the <code>.o</code> files directly in your Nginx build.
|
||||
|
||||
Below is a trivial example to demonstrate this. Consider that we have the following <code>.lua</code> file named <code>foo.lua</code>:
|
||||
|
||||
<geshi lang="lua">
|
||||
-- foo.lua
|
||||
local _M = {}
|
||||
|
||||
function _M.go()
|
||||
print("Hello from foo")
|
||||
end
|
||||
|
||||
return _M
|
||||
</geshi>
|
||||
|
||||
And then we compile this <code>.lua</code> file to <code>foo.o</code> file:
|
||||
|
||||
/path/to/luajit/bin/luajit -bg foo.lua foo.o
|
||||
|
||||
What matters here is the name of the <code>.lua</code> file, which determines how you use this module later on the Lua land. The file name <code>foo.o</code> does not matter at all except the <code>.o</code> file extension (which tells <code>luajit</code> what output format is used). If you want to strip the Lua debug information from the resulting bytecode, you can just specify the <code>-b</code> option above instead of <code>-bg</code>.
|
||||
|
||||
Then when building Nginx or OpenResty, pass the <code>--with-ld-opt="foo.o"</code> option to the <code>./configure</code> script:
|
||||
|
||||
<geshi lang="bash">
|
||||
./configure --with-ld-opt="/path/to/foo.o" ...
|
||||
</geshi>
|
||||
|
||||
Finally, you can just do the following in any Lua code run by ngx_lua:
|
||||
|
||||
<geshi lang="lua">
|
||||
local foo = require "foo"
|
||||
foo.go()
|
||||
</geshi>
|
||||
|
||||
And this piece of code no longer depends on the external <code>foo.lua</code> file any more because it has already been compiled into the <code>nginx</code> executable.
|
||||
|
||||
If you want to use dot in the Lua module name when calling <code>require</code>, as in
|
||||
|
||||
<geshi lang="lua">
|
||||
local foo = require "resty.foo"
|
||||
</geshi>
|
||||
|
||||
then you need to rename the <code>foo.lua</code> file to <code>resty_foo.lua</code> before compiling it down to a <code>.o</code> file with the <code>luajit</code> command-line utility.
|
||||
|
||||
It is important to use exactly the same version of LuaJIT when compiling <code>.lua</code> files to <code>.o</code> files as building nginx + ngx_lua. This is because the LuaJIT bytecode format may be incompatible between different LuaJIT versions. When the bytecode format is incompatible, you will see a Lua runtime error saying that the Lua module is not found.
|
||||
|
||||
When you have multiple <code>.lua</code> files to compile and link, then just specify their <code>.o</code> files at the same time in the value of the <code>--with-ld-opt</code> option. For instance,
|
||||
|
||||
<geshi lang="bash">
|
||||
./configure --with-ld-opt="/path/to/foo.o /path/to/bar.o" ...
|
||||
</geshi>
|
||||
|
||||
If you have just too many <code>.o</code> files, then it might not be feasible to name them all in a single command. In this case, you can build a static library (or archive) for your <code>.o</code> files, as in
|
||||
|
||||
<geshi lang="bash">
|
||||
ar rcus libmyluafiles.a *.o
|
||||
</geshi>
|
||||
|
||||
then you can link the <code>myluafiles</code> archive as a whole to your nginx executable:
|
||||
|
||||
<geshi lang="bash">
|
||||
./configure \
|
||||
--with-ld-opt="-L/path/to/lib -Wl,--whole-archive -lmyluafiles -Wl,--no-whole-archive"
|
||||
</geshi>
|
||||
|
||||
where <code>/path/to/lib</code> is the path of the directory containing the <code>libmyluafiles.a</code> file. It should be noted that the linker option <code>--whole-archive</code> is required here because otherwise our archive will be skipped because no symbols in our archive are mentioned in the main parts of the nginx executable.
|
||||
|
||||
= Data Sharing within an Nginx Worker =
|
||||
|
||||
To globally share data among all the requests handled by the same nginx worker process, encapsulate the shared data into a Lua module, use the Lua <code>require</code> builtin to import the module, and then manipulate the shared data in Lua. This works because required Lua modules are loaded only once and all coroutines will share the same copy of the module (both its code and data). Note however that Lua global variables (note, not module-level variables) WILL NOT persist between requests because of the one-coroutine-per-request isolation design.
|
||||
|
||||
Here is a complete small example:
|
||||
|
||||
<geshi lang="lua">
|
||||
-- mydata.lua
|
||||
local _M = {}
|
||||
|
||||
local data = {
|
||||
dog = 3,
|
||||
cat = 4,
|
||||
pig = 5,
|
||||
}
|
||||
|
||||
function _M.get_age(name)
|
||||
return data[name]
|
||||
end
|
||||
|
||||
return _M
|
||||
</geshi>
|
||||
|
||||
and then accessing it from <code>nginx.conf</code>:
|
||||
|
||||
<geshi lang="nginx">
|
||||
location /lua {
|
||||
content_by_lua '
|
||||
local mydata = require "mydata"
|
||||
ngx.say(mydata.get_age("dog"))
|
||||
';
|
||||
}
|
||||
</geshi>
|
||||
|
||||
The <code>mydata</code> module in this example will only be loaded and run on the first request to the location <code>/lua</code>,
|
||||
and all subsequent requests to the same nginx worker process will use the reloaded instance of the
|
||||
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.
|
||||
This data sharing technique is essential for high performance Lua applications based on this module.
|
||||
|
||||
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.
|
||||
|
||||
If server-wide data sharing is required, then use one or more of the following approaches:
|
||||
|
||||
# Use the [[#ngx.shared.DICT|ngx.shared.DICT]] API provided by this module.
|
||||
# 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).
|
||||
# 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 and Lua libraries that provide interfaces with these data storage mechanisms.
|
||||
|
||||
= Known Issues =
|
||||
|
||||
== TCP socket connect operation issues ==
|
||||
The [[#tcpsock:connect|tcpsock:connect]] method may indicate <code>success</code> despite connection failures such as with <code>Connection Refused</code> errors.
|
||||
|
||||
However, later attempts to manipulate the cosocket object will fail and return the actual error status message generated by the failed connect operation.
|
||||
|
||||
This issue is due to limitations in the Nginx event model and only appears to affect Mac OS X.
|
||||
|
||||
== Lua Coroutine Yielding/Resuming ==
|
||||
* Lua's <code>dofile</code> builtin is implemented as a C function in both Lua 5.1 and LuaJIT 2.0/2.1 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 normally 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.
|
||||
* As 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()] or even the first line of the <code>for ... in ...</code> statement 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.x, which supports a fully resumable VM, to avoid this.
|
||||
|
||||
== Lua Variable Scope ==
|
||||
Care must be taken when importing modules and this form should be used:
|
||||
|
||||
<geshi lang="lua">
|
||||
local xxx = require('xxx')
|
||||
</geshi>
|
||||
|
||||
instead of the old deprecated form:
|
||||
|
||||
<geshi lang="lua">
|
||||
require('xxx')
|
||||
</geshi>
|
||||
|
||||
Here is the reason: by design, the global environment has exactly the same lifetime as the Nginx request handler associated with it. Each request handler has its own set of Lua global variables and that is the idea of request isolation. The Lua module is actually loaded by the first Nginx request handler and is cached by the <code>require()</code> built-in in the package.loaded table for later reference, and <code>require()</code> has the side effect of setting a global variable to the loaded module table. But this global variable will be cleared at the end of the request handler, and every subsequent request handler all has its own (clean) global environment. So one will get Lua exception for accessing the <code>nil</code> value.
|
||||
|
||||
Generally, use of Lua global variables is a really really bad idea in the context of ngx_lua because
|
||||
|
||||
# misuse of Lua globals has very bad side effects for concurrent requests when these variables are actually supposed to be local only,
|
||||
# Lua global variables require Lua table look-up in the global environment (which is just a Lua table), which is kinda expensive, and
|
||||
# some Lua global variable references are just typos, which are hard to debug.
|
||||
|
||||
It's *highly* recommended to always declare them via "local" in the scope that is reasonable.
|
||||
|
||||
To find out all the uses of Lua global variables in your Lua code, you can run the [https://github.com/openresty/nginx-devel-utils/blob/master/lua-releng lua-releng tool] across all your .lua source files:
|
||||
<geshi lang="text">
|
||||
$ lua-releng
|
||||
Checking use of Lua global variables in file lib/foo/bar.lua ...
|
||||
1 [1489] SETGLOBAL 7 -1 ; contains
|
||||
55 [1506] GETGLOBAL 7 -3 ; setvar
|
||||
3 [1545] GETGLOBAL 3 -4 ; varexpand
|
||||
</geshi>
|
||||
The output says that the line 1489 of file <code>lib/foo/bar.lua</code> writes to a global variable named <code>contains</code>, the line 1506 reads from the global variable <code>setvar</code>, and line 1545 reads the global <code>varexpand</code>.
|
||||
|
||||
This tool will guarantee that local variables in the Lua module functions are all declared with the <code>local</code> keyword, otherwise a runtime exception will be thrown. It prevents undesirable race conditions while accessing such variables. See [[#Data_Sharing_within_an_Nginx_Worker|Data Sharing within an Nginx Worker]] for the reasons behind this.
|
||||
|
||||
== Locations Configured by Subrequest Directives of Other Modules ==
|
||||
The [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]] directives cannot capture locations that include the [[HttpEchoModule#echo_location|echo_location]], [[HttpEchoModule#echo_location_async|echo_location_async]], [[HttpEchoModule#echo_subrequest|echo_subrequest]], or [[HttpEchoModule#echo_subrequest_async|echo_subrequest_async]] directives.
|
||||
|
||||
<geshi lang="nginx">
|
||||
location /foo {
|
||||
content_by_lua '
|
||||
res = ngx.location.capture("/bar")
|
||||
';
|
||||
}
|
||||
location /bar {
|
||||
echo_location /blah;
|
||||
}
|
||||
location /blah {
|
||||
echo "Success!";
|
||||
}
|
||||
</geshi>
|
||||
|
||||
<geshi lang="nginx">
|
||||
$ curl -i http://example.com/foo
|
||||
</geshi>
|
||||
|
||||
will not work as expected.
|
||||
|
||||
== Special PCRE Sequences ==
|
||||
PCRE sequences such as <code>\d</code>, <code>\s</code>, or <code>\w</code>, require special attention because in string literals, the backslash character, <code>\</code>, is stripped out by both the Lua language parser and by the Nginx config file parser before processing. So the following snippet will not work as expected:
|
||||
|
||||
<geshi lang="nginx">
|
||||
# nginx.conf
|
||||
? location /test {
|
||||
? content_by_lua '
|
||||
? local regex = "\d+" -- THIS IS WRONG!!
|
||||
? local m = ngx.re.match("hello, 1234", regex)
|
||||
? if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
? ';
|
||||
? }
|
||||
# evaluates to "not matched!"
|
||||
</geshi>
|
||||
|
||||
To avoid this, ''double'' escape the backslash:
|
||||
|
||||
<geshi lang="nginx">
|
||||
# nginx.conf
|
||||
location /test {
|
||||
content_by_lua '
|
||||
local regex = "\\\\d+"
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
';
|
||||
}
|
||||
# evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
Here, <code>\\\\d+</code> is stripped down to <code>\\d+</code> by the Nginx config file parser and this is further stripped down to <code>\d+</code> by the Lua language parser before running.
|
||||
|
||||
Alternatively, the regex pattern can be presented as a long-bracketed Lua string literal by encasing it in "long brackets", <code>[[...]]</code>, in which case backslashes have to only be escaped once for the Nginx config file parser.
|
||||
|
||||
<geshi lang="nginx">
|
||||
# nginx.conf
|
||||
location /test {
|
||||
content_by_lua '
|
||||
local regex = [[\\d+]]
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
';
|
||||
}
|
||||
# evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
Here, <code>[[\\d+]]</code> is stripped down to <code>[[\d+]]</code> by the Nginx config file parser and this is processed correctly.
|
||||
|
||||
Note that a longer from of the long bracket, <code>[=[...]=]</code>, may be required if the regex pattern contains <code>[...]</code> sequences.
|
||||
The <code>[=[...]=]</code> form may be used as the default form if desired.
|
||||
|
||||
<geshi lang="nginx">
|
||||
# nginx.conf
|
||||
location /test {
|
||||
content_by_lua '
|
||||
local regex = [=[[0-9]+]=]
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
';
|
||||
}
|
||||
# evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
An alternative approach to escaping PCRE sequences is to ensure that Lua code is placed in external script files and executed using the various <code>*_by_lua_file</code> directives.
|
||||
With this approach, the backslashes are only stripped by the Lua language parser and therefore only need to be escaped once each.
|
||||
|
||||
<geshi lang="lua">
|
||||
-- test.lua
|
||||
local regex = "\\d+"
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
-- evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
Within external script files, PCRE sequences presented as long-bracketed Lua string literals do not require modification.
|
||||
|
||||
<geshi lang="lua">
|
||||
-- test.lua
|
||||
local regex = [[\d+]]
|
||||
local m = ngx.re.match("hello, 1234", regex)
|
||||
if m then ngx.say(m[0]) else ngx.say("not matched!") end
|
||||
-- evaluates to "1234"
|
||||
</geshi>
|
||||
|
||||
== Mixing with SSI Not Supported ==
|
||||
|
||||
Mixing SSI with ngx_lua in the same Nginx request is not supported at all. Just use ngx_lua exclusively. Everything you can do with SSI can be done atop ngx_lua anyway and it can be more efficient when using ngx_lua.
|
||||
|
||||
== SPDY Mode Not Fully Supported ==
|
||||
|
||||
Certain Lua APIs provided by ngx_lua do not work in Nginx's SPDY mode yet: [[#ngx.location.capture|ngx.location.capture]], [[#ngx.location.capture_multi|ngx.location.capture_multi]], and [[#ngx.req.socket|ngx.req.socket]].
|
||||
|
||||
= TODO =
|
||||
|
||||
== Short Term ==
|
||||
* implement the SSL cosocket API.
|
||||
* review and apply Jader H. Silva's patch for <code>ngx.re.split()</code>.
|
||||
* review and apply vadim-pavlov's patch for [[#ngx.location.capture|ngx.location.capture]]'s <code>extra_headers</code> option
|
||||
* 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.
|
||||
* add configure options for different strategies of handling the cosocket connection exceeding in the pools.
|
||||
* add directives to run Lua codes when nginx stops.
|
||||
* 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.
|
||||
|
||||
== Longer Term ==
|
||||
* add automatic Lua code time slicing support by yielding and resuming the Lua VM actively via Lua's debug hooks.
|
||||
* add <code>stat</code> mode similar to [https://httpd.apache.org/docs/trunk/mod/mod_lua.html mod_lua].
|
||||
|
||||
= Changes =
|
||||
|
||||
The changes of every release of this module can be obtained from the ngx_openresty bundle's change logs:
|
||||
|
||||
http://openresty.org/#Changes
|
||||
|
||||
= Test Suite =
|
||||
|
||||
The following dependencies are required to run the test suite:
|
||||
|
||||
* Nginx version >= 1.4.2
|
||||
|
||||
* Perl modules:
|
||||
** Test::Nginx: http://github.com/openresty/test-nginx
|
||||
|
||||
* Nginx modules:
|
||||
** [https://github.com/simpl/ngx_devel_kit ngx_devel_kit]
|
||||
** [http://github.com/openresty/set-misc-nginx-module ngx_set_misc]
|
||||
** [http://mdounin.ru/files/ngx_http_auth_request_module-0.2.tar.gz ngx_auth_request] (this is not needed if you're using Nginx 1.5.4+.
|
||||
** [http://github.com/openresty/echo-nginx-module ngx_echo]
|
||||
** [http://github.com/openresty/memc-nginx-module ngx_memc]
|
||||
** [http://github.com/openresty/srcache-nginx-module ngx_srcache]
|
||||
** ngx_lua (i.e., this module)
|
||||
** [http://github.com/openresty/lua-upstream-nginx-module ngx_lua_upstream]
|
||||
** [http://github.com/openresty/headers-more-nginx-module ngx_headers_more]
|
||||
** [http://github.com/openresty/drizzle-nginx-module ngx_drizzle]
|
||||
** [http://github.com/openresty/rds-json-nginx-module ngx_rds_json]
|
||||
** [https://github.com/FRiCKLE/ngx_coolkit ngx_coolkit]
|
||||
** [http://github.com/openresty/redis2-nginx-module ngx_redis2]
|
||||
|
||||
The order in which these modules are added during configuration is important because the position of any filter module in the
|
||||
filtering chain determines the final output, for example. The correct adding order is shown above.
|
||||
|
||||
* 3rd-party Lua libraries:
|
||||
** [http://www.kyne.com.au/~mark/software/lua-cjson.php lua-cjson]
|
||||
|
||||
* Applications:
|
||||
** mysql: create database 'ngx_test', grant all privileges to user 'ngx_test', password is 'ngx_test'
|
||||
** memcached: listening on the default port, 11211.
|
||||
** redis: listening on the default port, 6379.
|
||||
|
||||
See also the [https://github.com/openresty/lua-nginx-module/blob/master/util/build2.sh developer build script] for more details on setting up the testing environment.
|
||||
|
||||
To run the whole test suite in the default testing mode:
|
||||
<geshi lang="text">
|
||||
cd /path/to/lua-nginx-module
|
||||
export PATH=/path/to/your/nginx/sbin:$PATH
|
||||
prove -I/path/to/test-nginx/lib -r t
|
||||
</geshi>
|
||||
|
||||
To run specific test files:
|
||||
<geshi lang="text">
|
||||
cd /path/to/lua-nginx-module
|
||||
export PATH=/path/to/your/nginx/sbin:$PATH
|
||||
prove -I/path/to/test-nginx/lib t/002-content.t t/003-errors.t
|
||||
</geshi>
|
||||
|
||||
To run a specific test block in a particular test file, add the line <code>--- ONLY</code> to the test block you want to run, and then use the `prove` utility to run that <code>.t</code> file.
|
||||
|
||||
There are also various testing modes based on mockeagain, valgrind, and etc. Refer to the [http://search.cpan.org/perldoc?Test::Nginx Test::Nginx documentation] for more details for various advanced testing modes. See also the test reports for the Nginx test cluster running on Amazon EC2: http://qa.openresty.org.
|
||||
|
||||
= Copyright and License =
|
||||
|
||||
This module is licensed under the BSD license.
|
||||
|
||||
Copyright (C) 2009-2014, by Xiaozhe Wang (chaoslawful) <chaoslawful@gmail.com>.
|
||||
|
||||
Copyright (C) 2009-2014, by Yichun "agentzh" Zhang (章亦春) <agentzh@gmail.com>, CloudFlare Inc.
|
||||
|
||||
All rights reserved.
|
||||
|
||||
Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:
|
||||
|
||||
* Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
|
||||
|
||||
* Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
|
||||
|
||||
THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
|
||||
|
||||
= See Also =
|
||||
|
||||
* [http://github.com/openresty/lua-resty-memcached lua-resty-memcached] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-redis lua-resty-redis] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-mysql lua-resty-mysql] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-upload lua-resty-upload] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-dns lua-resty-dns] library based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-websocket lua-resty-websocket] library for both WebSocket server and client, based on ngx_lua cosocket.
|
||||
* [http://github.com/openresty/lua-resty-string lua-resty-string] library based on [http://luajit.org/ext_ffi.html LuaJIT FFI].
|
||||
* [http://github.com/openresty/lua-resty-lock lua-resty-lock] library for a nonblocking simple lock API.
|
||||
* [http://openresty.org/#RoutingMySQLQueriesBasedOnURIArgs Routing requests to different MySQL queries based on URI arguments]
|
||||
* [http://openresty.org/#DynamicRoutingBasedOnRedis Dynamic Routing Based on Redis and Lua]
|
||||
* [http://openresty.org/#UsingLuaRocks Using LuaRocks with ngx_lua]
|
||||
* [https://github.com/openresty/lua-nginx-module/wiki/Introduction Introduction to ngx_lua]
|
||||
* [http://github.com/simpl/ngx_devel_kit ngx_devel_kit]
|
||||
* [[HttpEchoModule]]
|
||||
* [[HttpDrizzleModule]]
|
||||
* [http://github.com/FRiCKLE/ngx_postgres postgres-nginx-module]
|
||||
* [[HttpMemcModule]]
|
||||
* [http://openresty.org The ngx_openresty bundle]
|
||||
* [https://github.com/openresty/nginx-systemtap-toolkit Nginx Systemtap Toolkit]
|
||||
|
|
|
|||
Загрузка…
Ссылка в новой задаче