github
/
lua-nginx-module
зеркало из https://github.com/github/lua-nginx-module.git
1
0
Форкнуть 0
Код Задачи Пакеты Проекты Релизы Вики Активность

updated docs to reflect recent changes.

This commit is contained in:
agentzh (章亦春) 2012-06-22 14:48:34 +08:00
Родитель 09f063024b
Коммит f73785c643
3 изменённых файлов: 153 добавлений и 92 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

123
README
Просмотреть файл

@ -8,8 +8,8 @@ Status
This module is under active development and is production ready. This module is under active development and is production ready.
Version Version
This document describes ngx_lua v0.5.1 This document describes ngx_lua v0.5.2
(<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 16 (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 18
June 2012. June 2012.
Synopsis Synopsis
@ -227,9 +227,9 @@ Directives
to to reload the config file are to send a "HUP" signal or to restart to to reload the config file are to send a "HUP" signal or to restart
Nginx. Nginx.
The ngx_lua module does not currently support the "stat" mode available The "ngx_lua" module does not currently support the "stat" mode
with the Apache "mod_lua" module but this is planned for implementation available with the Apache "mod_lua" module but this is planned for
in the future. implementation in the future.
Disabling the Lua code cache is strongly discouraged for production use Disabling the Lua code cache is strongly discouraged for production use
and should only be used during development as it has a significant and should only be used during development as it has a significant
@ -385,6 +385,10 @@ Directives
can be temporarily disabled during development by switching can be temporarily disabled during development by switching
lua_code_cache "off" in "nginx.conf" to avoid reloading Nginx. lua_code_cache "off" in "nginx.conf" to avoid reloading Nginx.
Since the "v0.5.0rc32" release, the file specified by
"<path-to-lua-script-file>" can be a pre-compiled Lua/LuaJIT bytecode
file.
This directive requires the ngx_devel_kit This directive requires the ngx_devel_kit
(<https://github.com/simpl/ngx_devel_kit>) module. (<https://github.com/simpl/ngx_devel_kit>) module.
@ -428,6 +432,10 @@ Directives
can be temporarily disabled during development by switching can be temporarily disabled during development by switching
lua_code_cache "off" in "nginx.conf" to avoid reloading Nginx. lua_code_cache "off" in "nginx.conf" to avoid reloading Nginx.
Since the "v0.5.0rc32" release, the file specified by
"<path-to-lua-script-file>" can be a pre-compiled Lua/LuaJIT bytecode
file.
rewrite_by_lua rewrite_by_lua
syntax: *rewrite_by_lua <lua-script-str>* syntax: *rewrite_by_lua <lua-script-str>*
@ -578,6 +586,10 @@ Directives
"rewrite" request-processing phase unless rewrite_by_lua_no_postpone is "rewrite" request-processing phase unless rewrite_by_lua_no_postpone is
turned on. turned on.
Since the "v0.5.0rc32" release, the file specified by
"<path-to-lua-script-file>" can be a pre-compiled Lua/LuaJIT bytecode
file.
access_by_lua access_by_lua
syntax: *access_by_lua <lua-script-str>* syntax: *access_by_lua <lua-script-str>*
@ -677,6 +689,10 @@ Directives
lua_code_cache "off" in "nginx.conf" to avoid repeatedly reloading lua_code_cache "off" in "nginx.conf" to avoid repeatedly reloading
Nginx. Nginx.
Since the "v0.5.0rc32" release, the file specified by
"<path-to-lua-script-file>" can be a pre-compiled Lua/LuaJIT bytecode
file.
header_filter_by_lua header_filter_by_lua
syntax: *header_filter_by_lua <lua-script-str>* syntax: *header_filter_by_lua <lua-script-str>*
@ -723,6 +739,10 @@ Directives
into the absolute path relative to the "server prefix" path determined into the absolute path relative to the "server prefix" path determined
by the "-p PATH" command-line option while starting the Nginx server. by the "-p PATH" command-line option while starting the Nginx server.
Since the "v0.5.0rc32" release, the file specified by
"<path-to-lua-script-file>" can be a pre-compiled Lua/LuaJIT bytecode
file.
This directive was first introduced in the "v0.2.1rc20" release. This directive was first introduced in the "v0.2.1rc20" release.
body_filter_by_lua body_filter_by_lua
@ -831,6 +851,10 @@ Directives
into the absolute path relative to the "server prefix" path determined into the absolute path relative to the "server prefix" path determined
by the "-p PATH" command-line option while starting the Nginx server. by the "-p PATH" command-line option while starting the Nginx server.
Since the "v0.5.0rc32" release, the file specified by
"<path-to-lua-script-file>" can be a pre-compiled Lua/LuaJIT bytecode
file.
This directive was first introduced in the "v0.5.0rc32" release. This directive was first introduced in the "v0.5.0rc32" release.
log_by_lua log_by_lua
@ -913,6 +937,10 @@ Directives
into the absolute path relative to the "server prefix" path determined into the absolute path relative to the "server prefix" path determined
by the "-p PATH" command-line option while starting the Nginx server. by the "-p PATH" command-line option while starting the Nginx server.
Since the "v0.5.0rc32" release, the file specified by
"<path-to-lua-script-file>" can be a pre-compiled Lua/LuaJIT bytecode
file.
This directive was first introduced in the "v0.5.0rc31" release. This directive was first introduced in the "v0.5.0rc31" release.
lua_need_request_body lua_need_request_body
@ -2502,7 +2530,7 @@ Nginx API for Lua
ngx.exec("/foo", "a=3&b=hello%20world") ngx.exec("/foo", "a=3&b=hello%20world")
Alternatively, a Lua table can be passed for the "args" argument for Alternatively, a Lua table can be passed for the "args" argument for
ngx_lua to carry out URI escaping and string concatenation "ngx_lua" to carry out URI escaping and string concatenation
automatically. automatically.
ngx.exec("/foo", { a = 3, b = "hello world" }) ngx.exec("/foo", { a = 3, b = "hello world" })
@ -2596,10 +2624,10 @@ Nginx API for Lua
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua** context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
Returns "true" if the response headers have been sent (by ngx_lua), and Returns "true" if the response headers have been sent (by "ngx_lua"),
"false" otherwise. and "false" otherwise.
This API was first introduced in ngx_lua v0.3.1rc6. This API was first introduced in "ngx_lua" v0.3.1rc6.
ngx.print ngx.print
syntax: *ngx.print(...)* syntax: *ngx.print(...)*
@ -4101,44 +4129,44 @@ Nginx API for Lua
(<https://github.com/simpl/ngx_devel_kit>) module. (<https://github.com/simpl/ngx_devel_kit>) module.
Lua/LuaJIT bytecode support Lua/LuaJIT bytecode support
Since the "v0.5.0rc32" release, all the *_by_lua_file configure All *_by_lua_file configure directives (such as content_by_lua_file)
directives (like content_by_lua_file) support loading Lua 5.1 and LuaJIT support directly loading Lua 5.1 and LuaJIT 2.0 raw bytecode files since
2.0 raw bytecode files automatically. the "v0.5.0rc32" release.
Please note that the bytecode format used by LuaJIT 2.0 is completely Please note that the bytecode format used by LuaJIT 2.0 is not
different from the standard Lua 5.1 interpreter's. So if you're using compatible with that for the standard Lua 5.1 interpreter. So if using
LuaJIT 2.0 with this Nginx module, you need to use LuaJIT 2.0 to LuaJIT 2.0 with "ngx_lua", LuaJIT-compatible bytecode files must be
generate LuaJIT-compatible bytecode files, like this: generated as shown:
/path/to/luajit/bin/luajit-2.0.0-beta10 -b /path/to/your.lua /path/to/your.luac /path/to/luajit/bin/luajit -b /path/to/input_file.lua /path/to/output_file.luac
You can use the "-bg" option instead to include debug information in the The "-bg" option can be used to include debug information in the LuaJIT
LuaJIT bytecode file: bytecode file:
/path/to/luajit/bin/luajit-2.0.0-beta10 -bg /path/to/your.lua /path/to/your.luac /path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.luac
Check out the official documentation for "luajit"'s "-b" option for more Please refer to the official LuaJIT documentation for the "-b" option
details: for more details:
http://luajit.org/running.html#opt_b http://luajit.org/running.html#opt_b
Similarly, if you're using the standard Lua 5.1 interpreter with this Similarly, if using the standard Lua 5.1 interpreter with "ngx_lua",
Nginx module, then you need to use the "luac" command-line utility to Lua-compatible bytecode files must be generated using the "luac"
generate the Lua-compatible bytecode files, like this: command-line utility as shown:
luac -o /path/to/your.luac /path/to/your.lua luac -o /path/to/output_file.luac /path/to/input_file.lua
Unlike LuaJIT, the debug information in included in standard Lua 5.1's Unlike as with LuaJIT, debug information is included in standard Lua 5.1
bytecode by default. You can strip the debug information by specifying bytecode files by default. This can be striped out by specifying the
the "-s" option, as in "-s" option as shown:
luac -s -o /path/to/your.luac /path/to/your.lua luac -s -o /path/to/output_file.luac /path/to/input_file.lua
If you're trying to load a standard Lua 5.1 bytecode file into an nginx Attempts to load standard Lua 5.1 bytecode files into "ngx_lua"
linked with LuaJIT 2.0 or in the other way around, you will get an error instances linked to LuaJIT 2.0 or vice versa, an error message such as
message like below in your Nginx's "error.log" file: that below will be logged in the Nginx "error.log" file:
[error] 13909\#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test.luac [error] 13909#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test_file.luac
Loading bytecode files via the Lua primitives like "require" and Loading bytecode files via the Lua primitives like "require" and
"dofile" should always work as expected. "dofile" should always work as expected.
@ -4250,16 +4278,16 @@ Known Issues
5.1 and LuaJIT 2.0 and when ngx.location.capture is called, 5.1 and LuaJIT 2.0 and when ngx.location.capture is called,
ngx.exec, ngx.exit or ngx.req.read_body or similar in the file to be ngx.exec, ngx.exit or ngx.req.read_body or similar in the file to be
loaded by "dofile", a coroutine yield across the C function boundary loaded by "dofile", a coroutine yield across the C function boundary
will be initiated. This however is not allowed within ngx_lua and will be initiated. This however is not normally allowed within
will usually result in error messages like "lua handler aborted: "ngx_lua" and will usually result in error messages like "lua
runtime error: attempt to yield across C-call boundary". To avoid handler aborted: runtime error: attempt to yield across C-call
this, define a real Lua module and use the Lua "require" builtin boundary". To avoid this, define a real Lua module and use the Lua
instead. "require" builtin instead.
* Because the standard Lua 5.1 interpreter's VM is not fully * As the standard Lua 5.1 interpreter's VM is not fully resumable, the
resumable, the methods ngx.location.capture, methods ngx.location.capture, ngx.location.capture_multi,
ngx.location.capture_multi, ngx.redirect, ngx.exec, and ngx.exit ngx.redirect, ngx.exec, and ngx.exit cannot be used within the
cannot be used within the context of a Lua pcall() context of a Lua pcall()
(<http://www.lua.org/manual/5.1/manual.html#pdf-pcall>) or xpcall() (<http://www.lua.org/manual/5.1/manual.html#pdf-pcall>) or xpcall()
(<http://www.lua.org/manual/5.1/manual.html#pdf-xpcall>) when the (<http://www.lua.org/manual/5.1/manual.html#pdf-xpcall>) when the
standard Lua 5.1 interpreter is used and the "attempt to yield standard Lua 5.1 interpreter is used and the "attempt to yield
@ -4460,6 +4488,9 @@ Typical Uses
Nginx Compatibility Nginx Compatibility
The module is compatible with the following versions of Nginx: The module is compatible with the following versions of Nginx:
*
1.2.x (last tested: 1.2.1)
* *
1.1.x (last tested: 1.1.5) 1.1.x (last tested: 1.1.5)
@ -4495,7 +4526,7 @@ Installation
2. Download the latest version of the ngx_devel_kit (NDK) module HERE 2. Download the latest version of the ngx_devel_kit (NDK) module HERE
(<http://github.com/simpl/ngx_devel_kit/tags>). (<http://github.com/simpl/ngx_devel_kit/tags>).
3. Download the latest version of this module HERE 3. Download the latest version of "ngx_lua" HERE
(<http://github.com/chaoslawful/lua-nginx-module/tags>). (<http://github.com/chaoslawful/lua-nginx-module/tags>).
4. Download the latest version of Nginx HERE (<http://nginx.org/>) (See 4. Download the latest version of Nginx HERE (<http://nginx.org/>) (See
@ -4595,7 +4626,7 @@ Changes
* bugfix: ngx.exit, ngx.redirect, ngx.exec, and ngx.req.set_uri(uri, * bugfix: ngx.exit, ngx.redirect, ngx.exec, and ngx.req.set_uri(uri,
true) could return (they should never return as per the true) could return (they should never return as per the
documentation). this bug had appeared in ngx_lua v0.3.1rc4 and documentation). this bug had appeared in "ngx_lua" v0.3.1rc4 and
ngx_openresty 1.0.6.13. thanks @cyberty (<http://weibo.com/cyberty>) ngx_openresty 1.0.6.13. thanks @cyberty (<http://weibo.com/cyberty>)
for reporting it. for reporting it.
@ -4637,7 +4668,7 @@ Changes
value. thanks sexybabes. value. thanks sexybabes.
* feature: implemented the ngx.headers_sent API to check if response * feature: implemented the ngx.headers_sent API to check if response
headers are sent (by ngx_lua). thanks @hugozhu. headers are sent (by "ngx_lua"). thanks @hugozhu.
* feature: exposes the CRC-32 API of the Nginx core to the Lua land, * feature: exposes the CRC-32 API of the Nginx core to the Lua land,
in the form of the ngx.crc32_short and ngx.crc32_long methods. in the form of the ngx.crc32_short and ngx.crc32_long methods.

61
README.markdown
Просмотреть файл

@ -18,7 +18,7 @@ This module is under active development and is production ready.
Version Version
======= =======
This document describes ngx_lua [v0.5.1](https://github.com/chaoslawful/lua-nginx-module/tags) released on 16 June 2012. This document describes ngx_lua [v0.5.2](https://github.com/chaoslawful/lua-nginx-module/tags) released on 18 June 2012.
Synopsis Synopsis
======== ========
@ -230,7 +230,7 @@ cached because only the Nginx config file parser can correctly parse the `nginx.
file and the only ways to to reload the config file file and the only ways to to reload the config file
are to send a `HUP` signal or to restart Nginx. are to send a `HUP` signal or to restart Nginx.
The ngx_lua module does not currently support the `stat` mode available with the The `ngx_lua` module does not currently support the `stat` mode available with the
Apache `mod_lua` module but this is planned for implementation in the future. Apache `mod_lua` module but this is planned for implementation in the future.
Disabling the Lua code cache is strongly Disabling the Lua code cache is strongly
@ -349,7 +349,7 @@ set_by_lua_file
**phase:** *server-rewrite, rewrite* **phase:** *server-rewrite, rewrite*
Equivalent to [set_by_lua](http://wiki.nginx.org/HttpLuaModule#set_by_lua), except that the file specified by `<path-to-lua-script-file>` contains the Lua code to be executed. Equivalent to [set_by_lua](http://wiki.nginx.org/HttpLuaModule#set_by_lua), except that the file specified by `<path-to-lua-script-file>` contains the Lua code to be executed.
Nginx variable interpolation is supported in the `<path-to-lua-script-file>` argument string of this directive. But special care must be taken for injection attacks. Nginx variable interpolation is supported in the `<path-to-lua-script-file>` argument string of this directive. But special care must be taken for injection attacks.
@ -360,6 +360,8 @@ and the Nginx config must be reloaded each time the Lua source file is modified.
The Lua code cache can be temporarily disabled during development by The Lua code cache can be temporarily disabled during development by
switching [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache) `off` in `nginx.conf` to avoid reloading Nginx. switching [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache) `off` in `nginx.conf` to avoid reloading Nginx.
Since the `v0.5.0rc32` release, the file specified by `<path-to-lua-script-file>` can be a pre-compiled [Lua/LuaJIT bytecode file](http://wiki.nginx.org/HttpLuaModule#Lua/LuaJIT_bytecode_support).
This directive requires the [ngx_devel_kit](https://github.com/simpl/ngx_devel_kit) module. This directive requires the [ngx_devel_kit](https://github.com/simpl/ngx_devel_kit) module.
content_by_lua content_by_lua
@ -396,6 +398,8 @@ and the Nginx config must be reloaded each time the Lua source file is modified.
The Lua code cache can be temporarily disabled during development by The Lua code cache can be temporarily disabled during development by
switching [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache) `off` in `nginx.conf` to avoid reloading Nginx. switching [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache) `off` in `nginx.conf` to avoid reloading Nginx.
Since the `v0.5.0rc32` release, the file specified by `<path-to-lua-script-file>` can be a pre-compiled [Lua/LuaJIT bytecode file](http://wiki.nginx.org/HttpLuaModule#Lua/LuaJIT_bytecode_support).
rewrite_by_lua rewrite_by_lua
-------------- --------------
@ -531,6 +535,8 @@ When the Lua code cache is turned on (by default), the user code is loaded once
The `rewrite_by_lua_file` code will always run at the end of the `rewrite` request-processing phase unless [rewrite_by_lua_no_postpone](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua_no_postpone) is turned on. The `rewrite_by_lua_file` code will always run at the end of the `rewrite` request-processing phase unless [rewrite_by_lua_no_postpone](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua_no_postpone) is turned on.
Since the `v0.5.0rc32` release, the file specified by `<path-to-lua-script-file>` can be a pre-compiled [Lua/LuaJIT bytecode file](http://wiki.nginx.org/HttpLuaModule#Lua/LuaJIT_bytecode_support).
access_by_lua access_by_lua
------------- -------------
@ -618,6 +624,8 @@ When the Lua code cache is turned on (by default), the user code is loaded once
and the Nginx config must be reloaded each time the Lua source file is modified. and the Nginx config must be reloaded each time the Lua source file is modified.
The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache) `off` in `nginx.conf` to avoid repeatedly reloading Nginx. The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](http://wiki.nginx.org/HttpLuaModule#lua_code_cache) `off` in `nginx.conf` to avoid repeatedly reloading Nginx.
Since the `v0.5.0rc32` release, the file specified by `<path-to-lua-script-file>` can be a pre-compiled [Lua/LuaJIT bytecode file](http://wiki.nginx.org/HttpLuaModule#Lua/LuaJIT_bytecode_support).
header_filter_by_lua header_filter_by_lua
-------------------- --------------------
@ -660,6 +668,8 @@ Equivalent to [header_filter_by_lua](http://wiki.nginx.org/HttpLuaModule#header_
When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
Since the `v0.5.0rc32` release, the file specified by `<path-to-lua-script-file>` can be a pre-compiled [Lua/LuaJIT bytecode file](http://wiki.nginx.org/HttpLuaModule#Lua/LuaJIT_bytecode_support).
This directive was first introduced in the `v0.2.1rc20` release. This directive was first introduced in the `v0.2.1rc20` release.
body_filter_by_lua body_filter_by_lua
@ -757,6 +767,8 @@ Equivalent to [body_filter_by_lua](http://wiki.nginx.org/HttpLuaModule#body_filt
When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
Since the `v0.5.0rc32` release, the file specified by `<path-to-lua-script-file>` can be a pre-compiled [Lua/LuaJIT bytecode file](http://wiki.nginx.org/HttpLuaModule#Lua/LuaJIT_bytecode_support).
This directive was first introduced in the `v0.5.0rc32` release. This directive was first introduced in the `v0.5.0rc32` release.
log_by_lua log_by_lua
@ -834,6 +846,8 @@ Equivalent to [log_by_lua](http://wiki.nginx.org/HttpLuaModule#log_by_lua), exce
When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server.
Since the `v0.5.0rc32` release, the file specified by `<path-to-lua-script-file>` can be a pre-compiled [Lua/LuaJIT bytecode file](http://wiki.nginx.org/HttpLuaModule#Lua/LuaJIT_bytecode_support).
This directive was first introduced in the `v0.5.0rc31` release. This directive was first introduced in the `v0.5.0rc31` release.
lua_need_request_body lua_need_request_body
@ -2357,7 +2371,7 @@ The optional second `args` can be used to specify extra URI query arguments, for
ngx.exec("/foo", "a=3&b=hello%20world") ngx.exec("/foo", "a=3&b=hello%20world")
Alternatively, a Lua table can be passed for the `args` argument for ngx_lua to carry out URI escaping and string concatenation automatically. Alternatively, a Lua table can be passed for the `args` argument for `ngx_lua` to carry out URI escaping and string concatenation automatically.
ngx.exec("/foo", { a = 3, b = "hello world" }) ngx.exec("/foo", { a = 3, b = "hello world" })
@ -2460,9 +2474,9 @@ ngx.headers_sent
**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua** **context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
Returns `true` if the response headers have been sent (by ngx_lua), and `false` otherwise. Returns `true` if the response headers have been sent (by `ngx_lua`), and `false` otherwise.
This API was first introduced in ngx_lua v0.3.1rc6. This API was first introduced in `ngx_lua` v0.3.1rc6.
ngx.print ngx.print
--------- ---------
@ -3747,40 +3761,40 @@ This feature requires the [ngx_devel_kit](https://github.com/simpl/ngx_devel_kit
Lua/LuaJIT bytecode support Lua/LuaJIT bytecode support
=========================== ===========================
Since the `v0.5.0rc32` release, all the `*_by_lua_file` configure directives (like [content_by_lua_file](http://wiki.nginx.org/HttpLuaModule#content_by_lua_file)) support loading Lua 5.1 and LuaJIT 2.0 raw bytecode files automatically. All `*_by_lua_file` configure directives (such as [content_by_lua_file](http://wiki.nginx.org/HttpLuaModule#content_by_lua_file)) support directly loading Lua 5.1 and LuaJIT 2.0 raw bytecode files since the `v0.5.0rc32` release.
Please note that the bytecode format used by LuaJIT 2.0 is completely different from the standard Lua 5.1 interpreter's. So if you're using LuaJIT 2.0 with this Nginx module, you need to use LuaJIT 2.0 to generate LuaJIT-compatible bytecode files, like this: Please note that the bytecode format used by LuaJIT 2.0 is not compatible with that for the standard Lua 5.1 interpreter. So if using LuaJIT 2.0 with `ngx_lua`, LuaJIT-compatible bytecode files must be generated as shown:
/path/to/luajit/bin/luajit-2.0.0-beta10 -b /path/to/your.lua /path/to/your.luac /path/to/luajit/bin/luajit -b /path/to/input_file.lua /path/to/output_file.luac
You can use the `-bg` option instead to include debug information in the LuaJIT bytecode file: The `-bg` option can be used to include debug information in the LuaJIT bytecode file:
/path/to/luajit/bin/luajit-2.0.0-beta10 -bg /path/to/your.lua /path/to/your.luac /path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.luac
Check out the official documentation for `luajit`'s `-b` option for more details: Please refer to the official LuaJIT documentation for the `-b` option for more details:
<http://luajit.org/running.html#opt_b> <http://luajit.org/running.html#opt_b>
Similarly, if you're using the standard Lua 5.1 interpreter with this Nginx module, then you need to use the `luac` command-line utility to generate the Lua-compatible bytecode files, like this: Similarly, if using the standard Lua 5.1 interpreter with `ngx_lua`, Lua-compatible bytecode files must be generated using the `luac` command-line utility as shown:
luac -o /path/to/your.luac /path/to/your.lua luac -o /path/to/output_file.luac /path/to/input_file.lua
Unlike LuaJIT, the debug information in included in standard Lua 5.1's bytecode by default. You can strip the debug information by specifying the `-s` option, as in 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 `-s` option as shown:
luac -s -o /path/to/your.luac /path/to/your.lua luac -s -o /path/to/output_file.luac /path/to/input_file.lua
If you're trying to load a standard Lua 5.1 bytecode file into an nginx linked with LuaJIT 2.0 or in the other way around, you will get an error message like below in your Nginx's `error.log` file: Attempts to load standard Lua 5.1 bytecode files into `ngx_lua` instances linked to LuaJIT 2.0 or vice versa, an error message such as that below will be logged in the Nginx `error.log` file:
[error] 13909\#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test.luac [error] 13909#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test_file.luac
Loading bytecode files via the Lua primitives like `require` and `dofile` should always work as expected. Loading bytecode files via the Lua primitives like `require` and `dofile` should always work as expected.
@ -3857,8 +3871,8 @@ Known Issues
Lua Coroutine Yielding/Resuming Lua Coroutine Yielding/Resuming
------------------------------- -------------------------------
* 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](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) (Actually, coroutine modules have been masked off in [content_by_lua](http://wiki.nginx.org/HttpLuaModule#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. * 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](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) (Actually, coroutine modules have been masked off in [content_by_lua](http://wiki.nginx.org/HttpLuaModule#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.
* Lua's `dofile` builtin is implemented as a C function in both Lua 5.1 and LuaJIT 2.0 and when [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) is called, [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec), [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit) or [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) or similar in the file to be loaded by `dofile`, 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 `lua handler aborted: runtime error: attempt to yield across C-call boundary`. To avoid this, define a real Lua module and use the Lua `require` builtin instead. * Lua's `dofile` builtin is implemented as a C function in both Lua 5.1 and LuaJIT 2.0 and when [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) is called, [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec), [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit) or [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) or similar in the file to be loaded by `dofile`, 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 `lua handler aborted: runtime error: attempt to yield across C-call boundary`. To avoid this, define a real Lua module and use the Lua `require` builtin instead.
* Because the standard Lua 5.1 interpreter's VM is not fully resumable, the methods [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture), [ngx.location.capture_multi](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture_multi), [ngx.redirect](http://wiki.nginx.org/HttpLuaModule#ngx.redirect), [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec), and [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit) cannot be used within the context of a Lua [pcall()](http://www.lua.org/manual/5.1/manual.html#pdf-pcall) or [xpcall()](http://www.lua.org/manual/5.1/manual.html#pdf-xpcall) when the standard Lua 5.1 interpreter is used and the `attempt to yield across metamethod/C-call boundary` error will be produced. Please use LuaJIT 2.0, which supports a fully resumable VM, to avoid this. * As the standard Lua 5.1 interpreter's VM is not fully resumable, the methods [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture), [ngx.location.capture_multi](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture_multi), [ngx.redirect](http://wiki.nginx.org/HttpLuaModule#ngx.redirect), [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec), and [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit) cannot be used within the context of a Lua [pcall()](http://www.lua.org/manual/5.1/manual.html#pdf-pcall) or [xpcall()](http://www.lua.org/manual/5.1/manual.html#pdf-xpcall) when the standard Lua 5.1 interpreter is used and the `attempt to yield across metamethod/C-call boundary` error will be produced. Please use LuaJIT 2.0, which supports a fully resumable VM, to avoid this.
Lua Variable Scope Lua Variable Scope
------------------ ------------------
@ -4031,6 +4045,7 @@ Nginx Compatibility
=================== ===================
The module is compatible with the following versions of Nginx: The module is compatible with the following versions of Nginx:
* 1.2.x (last tested: 1.2.1)
* 1.1.x (last tested: 1.1.5) * 1.1.x (last tested: 1.1.5)
* 1.0.x (last tested: 1.0.15) * 1.0.x (last tested: 1.0.15)
* 0.9.x (last tested: 0.9.4) * 0.9.x (last tested: 0.9.4)
@ -4050,7 +4065,7 @@ Alternatively, `ngx_lua` can be manually compiled into Nginx:
1. Install LuaJIT 2.0 (Recommended) or Lua 5.1 (Lua 5.2 is *not* supported yet). Lua can be obtained free from the [the LuaJIT download page](http://luajit.org/download.html) or [the standard Lua homepage](http://www.lua.org/). Some distribution package managers also distribute Lua and LuaJIT. 1. Install LuaJIT 2.0 (Recommended) or Lua 5.1 (Lua 5.2 is *not* supported yet). Lua can be obtained free from the [the LuaJIT download page](http://luajit.org/download.html) or [the standard Lua homepage](http://www.lua.org/). Some distribution package managers also distribute Lua and LuaJIT.
1. Download the latest version of the ngx_devel_kit (NDK) module [HERE](http://github.com/simpl/ngx_devel_kit/tags). 1. Download the latest version of the ngx_devel_kit (NDK) module [HERE](http://github.com/simpl/ngx_devel_kit/tags).
1. Download the latest version of this module [HERE](http://github.com/chaoslawful/lua-nginx-module/tags). 1. Download the latest version of `ngx_lua` [HERE](http://github.com/chaoslawful/lua-nginx-module/tags).
1. Download the latest version of Nginx [HERE](http://nginx.org/) (See [Nginx Compatibility](http://wiki.nginx.org/HttpLuaModule#Nginx_Compatibility)) 1. Download the latest version of Nginx [HERE](http://nginx.org/) (See [Nginx Compatibility](http://wiki.nginx.org/HttpLuaModule#Nginx_Compatibility))
Build the source with this module: Build the source with this module:
@ -4133,7 +4148,7 @@ v0.4.1
1 February, 2012 1 February, 2012
* bugfix: [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit), [ngx.redirect](http://wiki.nginx.org/HttpLuaModule#ngx.redirect), [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec), and [ngx.req.set_uri(uri, true)](http://wiki.nginx.org/HttpLuaModule#ngx.req.set_uri) 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 [@cyberty](http://weibo.com/cyberty) for reporting it. * bugfix: [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit), [ngx.redirect](http://wiki.nginx.org/HttpLuaModule#ngx.redirect), [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec), and [ngx.req.set_uri(uri, true)](http://wiki.nginx.org/HttpLuaModule#ngx.req.set_uri) 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 [@cyberty](http://weibo.com/cyberty) for reporting it.
* bugfix: `ngx_http_lua_header_filter_init` was called with an argument which actually accepts none. this could cause compilation errors at least with gcc 4.3.4 as reported in [github issue #80](http://github.com/chaoslawful/lua-nginx-module/issues/80). thanks bigplum (Simon). * bugfix: `ngx_http_lua_header_filter_init` was called with an argument which actually accepts none. this could cause compilation errors at least with gcc 4.3.4 as reported in [github issue #80](http://github.com/chaoslawful/lua-nginx-module/issues/80). thanks bigplum (Simon).
* bugfix: fixed all the warnings from the clang static analyzer. * bugfix: fixed all the warnings from the clang static analyzer.
* feature: allow use of the `DDEBUG` macro from the outside (via the `-D DDEBUG=1` C compiler opton). * feature: allow use of the `DDEBUG` macro from the outside (via the `-D DDEBUG=1` C compiler opton).
@ -4149,7 +4164,7 @@ v0.4.0
* bugfix: fixed an issue in [ngx.redirect](http://wiki.nginx.org/HttpLuaModule#ngx.redirect), [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit), and [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec): these function calls would be intercepted by Lua `pcall`/`xpcall` because they used Lua exceptions; now they use Lua yield just as [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture). thanks @hugozhu for reporting this. * bugfix: fixed an issue in [ngx.redirect](http://wiki.nginx.org/HttpLuaModule#ngx.redirect), [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit), and [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec): these function calls would be intercepted by Lua `pcall`/`xpcall` because they used Lua exceptions; now they use Lua yield just as [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture). thanks @hugozhu for reporting this.
* feature: now we also return the `Last-Modified` header (if any) for the subrequest response object. thanks @cyberty and sexybabes. * feature: now we also return the `Last-Modified` header (if any) for the subrequest response object. thanks @cyberty and sexybabes.
* feature: now [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec) supports Lua table as the second args argument value. thanks sexybabes. * feature: now [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec) supports Lua table as the second args argument value. thanks sexybabes.
* feature: implemented the [ngx.headers_sent](http://wiki.nginx.org/HttpLuaModule#ngx.headers_sent) API to check if response headers are sent (by ngx_lua). thanks @hugozhu. * feature: implemented the [ngx.headers_sent](http://wiki.nginx.org/HttpLuaModule#ngx.headers_sent) API to check if response headers are sent (by `ngx_lua`). thanks @hugozhu.
* feature: exposes the CRC-32 API of the Nginx core to the Lua land, in the form of the [ngx.crc32_short](http://wiki.nginx.org/HttpLuaModule#ngx.crc32_short) and [ngx.crc32_long](http://wiki.nginx.org/HttpLuaModule#ngx.crc32_long) methods. thanks @Lance. * feature: exposes the CRC-32 API of the Nginx core to the Lua land, in the form of the [ngx.crc32_short](http://wiki.nginx.org/HttpLuaModule#ngx.crc32_short) and [ngx.crc32_long](http://wiki.nginx.org/HttpLuaModule#ngx.crc32_long) methods. thanks @Lance.
* feature: now for HTTP 1.0 requests, we disable the automatic full buffering mode if the user sets the `Content-Length` 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 李子义. * feature: now for HTTP 1.0 requests, we disable the automatic full buffering mode if the user sets the `Content-Length` 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 李子义.
* bugfix: now we properly support setting the `Cache-Control` response header via the [ngx.header.HEADER](http://wiki.nginx.org/HttpLuaModule#ngx.header.HEADER) interface. * bugfix: now we properly support setting the `Cache-Control` response header via the [ngx.header.HEADER](http://wiki.nginx.org/HttpLuaModule#ngx.header.HEADER) interface.

61
doc/HttpLuaModule.wiki
Просмотреть файл

@ -10,7 +10,7 @@ This module is under active development and is production ready.
= Version = = Version =
This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.1] released on 16 June 2012. This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.2] released on 18 June 2012.
= Synopsis = = Synopsis =
<geshi lang="nginx"> <geshi lang="nginx">
@ -218,7 +218,7 @@ cached because only the Nginx config file parser can correctly parse the <code>n
file and the only ways to to reload the config file file and the only ways to to reload the config file
are to send a <code>HUP</code> signal or to restart Nginx. are to send a <code>HUP</code> signal or to restart Nginx.
The ngx_lua module does not currently support the <code>stat</code> mode available with the The <code>ngx_lua</code> module does not currently support the <code>stat</code> mode available with the
Apache <code>mod_lua</code> module but this is planned for implementation in the future. Apache <code>mod_lua</code> module but this is planned for implementation in the future.
Disabling the Lua code cache is strongly Disabling the Lua code cache is strongly
@ -332,7 +332,7 @@ This directive requires the [https://github.com/simpl/ngx_devel_kit ngx_devel_ki
'''phase:''' ''server-rewrite, rewrite'' '''phase:''' ''server-rewrite, rewrite''
Equivalent to [[#set_by_lua|set_by_lua]], except that the file specified by <code><path-to-lua-script-file></code> contains the Lua code to be executed. Equivalent to [[#set_by_lua|set_by_lua]], except that the file specified by <code><path-to-lua-script-file></code> contains the Lua code to be executed.
Nginx variable interpolation is supported in the <code><path-to-lua-script-file></code> argument string of this directive. But special care must be taken for injection attacks. Nginx variable interpolation is supported in the <code><path-to-lua-script-file></code> argument string of this directive. But special care must be taken for injection attacks.
@ -343,6 +343,8 @@ and the Nginx config must be reloaded each time the Lua source file is modified.
The Lua code cache can be temporarily disabled during development by 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 reloading Nginx. switching [[#lua_code_cache|lua_code_cache]] <code>off</code> in <code>nginx.conf</code> to avoid reloading Nginx.
Since the <code>v0.5.0rc32</code> release, the file specified by <code><path-to-lua-script-file></code> can be a pre-compiled [[#Lua/LuaJIT bytecode support|Lua/LuaJIT bytecode file]].
This directive requires the [https://github.com/simpl/ngx_devel_kit ngx_devel_kit] module. This directive requires the [https://github.com/simpl/ngx_devel_kit ngx_devel_kit] module.
== content_by_lua == == content_by_lua ==
@ -377,6 +379,8 @@ and the Nginx config must be reloaded each time the Lua source file is modified.
The Lua code cache can be temporarily disabled during development by 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 reloading Nginx. switching [[#lua_code_cache|lua_code_cache]] <code>off</code> in <code>nginx.conf</code> to avoid reloading Nginx.
Since the <code>v0.5.0rc32</code> release, the file specified by <code><path-to-lua-script-file></code> can be a pre-compiled [[#Lua/LuaJIT bytecode support|Lua/LuaJIT bytecode file]].
== rewrite_by_lua == == rewrite_by_lua ==
'''syntax:''' ''rewrite_by_lua <lua-script-str>'' '''syntax:''' ''rewrite_by_lua <lua-script-str>''
@ -510,6 +514,8 @@ When the Lua code cache is turned on (by default), the user code is loaded once
The <code>rewrite_by_lua_file</code> code will always run at the end of the <code>rewrite</code> request-processing phase unless [[#rewrite_by_lua_no_postpone|rewrite_by_lua_no_postpone]] is turned on. The <code>rewrite_by_lua_file</code> code will always run at the end of the <code>rewrite</code> request-processing phase unless [[#rewrite_by_lua_no_postpone|rewrite_by_lua_no_postpone]] is turned on.
Since the <code>v0.5.0rc32</code> release, the file specified by <code><path-to-lua-script-file></code> can be a pre-compiled [[#Lua/LuaJIT bytecode support|Lua/LuaJIT bytecode file]].
== access_by_lua == == access_by_lua ==
'''syntax:''' ''access_by_lua <lua-script-str>'' '''syntax:''' ''access_by_lua <lua-script-str>''
@ -595,6 +601,8 @@ When the Lua code cache is turned on (by default), the user code is loaded once
and the Nginx config must be reloaded each time the Lua source file is modified. and the Nginx config must be reloaded each time the Lua source file is modified.
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. 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.
Since the <code>v0.5.0rc32</code> release, the file specified by <code><path-to-lua-script-file></code> can be a pre-compiled [[#Lua/LuaJIT bytecode support|Lua/LuaJIT bytecode file]].
== header_filter_by_lua == == header_filter_by_lua ==
'''syntax:''' ''header_filter_by_lua <lua-script-str>'' '''syntax:''' ''header_filter_by_lua <lua-script-str>''
@ -635,6 +643,8 @@ Equivalent to [[#header_filter_by_lua|header_filter_by_lua]], except that the fi
When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server. When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
Since the <code>v0.5.0rc32</code> release, the file specified by <code><path-to-lua-script-file></code> can be a pre-compiled [[#Lua/LuaJIT bytecode support|Lua/LuaJIT bytecode file]].
This directive was first introduced in the <code>v0.2.1rc20</code> release. This directive was first introduced in the <code>v0.2.1rc20</code> release.
== body_filter_by_lua == == body_filter_by_lua ==
@ -730,6 +740,8 @@ Equivalent to [[#body_filter_by_lua|body_filter_by_lua]], except that the file s
When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server. When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
Since the <code>v0.5.0rc32</code> release, the file specified by <code><path-to-lua-script-file></code> can be a pre-compiled [[#Lua/LuaJIT bytecode support|Lua/LuaJIT bytecode file]].
This directive was first introduced in the <code>v0.5.0rc32</code> release. This directive was first introduced in the <code>v0.5.0rc32</code> release.
== log_by_lua == == log_by_lua ==
@ -805,6 +817,8 @@ Equivalent to [[#log_by_lua|log_by_lua]], except that the file specified by <cod
When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server. When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
Since the <code>v0.5.0rc32</code> release, the file specified by <code><path-to-lua-script-file></code> can be a pre-compiled [[#Lua/LuaJIT bytecode support|Lua/LuaJIT bytecode file]].
This directive was first introduced in the <code>v0.5.0rc31</code> release. This directive was first introduced in the <code>v0.5.0rc31</code> release.
== lua_need_request_body == == lua_need_request_body ==
@ -2287,7 +2301,7 @@ The optional second <code>args</code> can be used to specify extra URI query arg
ngx.exec("/foo", "a=3&b=hello%20world") ngx.exec("/foo", "a=3&b=hello%20world")
</geshi> </geshi>
Alternatively, a Lua table can be passed for the <code>args</code> argument for ngx_lua to carry out URI escaping and string concatenation automatically. Alternatively, a Lua table can be passed for the <code>args</code> argument for <code>ngx_lua</code> to carry out URI escaping and string concatenation automatically.
<geshi lang="lua"> <geshi lang="lua">
ngx.exec("/foo", { a = 3, b = "hello world" }) ngx.exec("/foo", { a = 3, b = "hello world" })
@ -2387,9 +2401,9 @@ before content is output with [[#ngx.say|ngx.say]] or [[#ngx.print|ngx.print]] o
'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*'' '''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*''
Returns <code>true</code> if the response headers have been sent (by ngx_lua), and <code>false</code> otherwise. Returns <code>true</code> if the response headers have been sent (by <code>ngx_lua</code>), and <code>false</code> otherwise.
This API was first introduced in ngx_lua v0.3.1rc6. This API was first introduced in <code>ngx_lua</code> v0.3.1rc6.
== ngx.print == == ngx.print ==
'''syntax:''' ''ngx.print(...)'' '''syntax:''' ''ngx.print(...)''
@ -3620,40 +3634,40 @@ This feature requires the [https://github.com/simpl/ngx_devel_kit ngx_devel_kit]
= Lua/LuaJIT bytecode support = = Lua/LuaJIT bytecode support =
Since the <code>v0.5.0rc32</code> release, all the <code>*_by_lua_file</code> configure directives (like [[#content_by_lua_file|content_by_lua_file]]) support loading Lua 5.1 and LuaJIT 2.0 raw bytecode files automatically. All <code>*_by_lua_file</code> configure directives (such as [[#content_by_lua_file|content_by_lua_file]]) support directly loading Lua 5.1 and LuaJIT 2.0 raw bytecode files since the <code>v0.5.0rc32</code> release.
Please note that the bytecode format used by LuaJIT 2.0 is completely different from the standard Lua 5.1 interpreter's. So if you're using LuaJIT 2.0 with this Nginx module, you need to use LuaJIT 2.0 to generate LuaJIT-compatible bytecode files, like this: Please note that the bytecode format used by LuaJIT 2.0 is not compatible with that for the standard Lua 5.1 interpreter. So if using LuaJIT 2.0 with <code>ngx_lua</code>, LuaJIT-compatible bytecode files must be generated as shown:
<geshi lang="bash"> <geshi lang="bash">
/path/to/luajit/bin/luajit-2.0.0-beta10 -b /path/to/your.lua /path/to/your.luac /path/to/luajit/bin/luajit -b /path/to/input_file.lua /path/to/output_file.luac
</geshi> </geshi>
You can use the <code>-bg</code> option instead to include debug information in the LuaJIT bytecode file: The <code>-bg</code> option can be used to include debug information in the LuaJIT bytecode file:
<geshi lang="bash"> <geshi lang="bash">
/path/to/luajit/bin/luajit-2.0.0-beta10 -bg /path/to/your.lua /path/to/your.luac /path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.luac
</geshi> </geshi>
Check out the official documentation for <code>luajit</code>'s <code>-b</code> option for more details: Please refer to the official LuaJIT documentation for the <code>-b</code> option for more details:
http://luajit.org/running.html#opt_b http://luajit.org/running.html#opt_b
Similarly, if you're using the standard Lua 5.1 interpreter with this Nginx module, then you need to use the <code>luac</code> command-line utility to generate the Lua-compatible bytecode files, like this: Similarly, if using the standard Lua 5.1 interpreter with <code>ngx_lua</code>, Lua-compatible bytecode files must be generated using the <code>luac</code> command-line utility as shown:
<geshi lang="bash"> <geshi lang="bash">
luac -o /path/to/your.luac /path/to/your.lua luac -o /path/to/output_file.luac /path/to/input_file.lua
</geshi> </geshi>
Unlike LuaJIT, the debug information in included in standard Lua 5.1's bytecode by default. You can strip the debug information by specifying the <code>-s</code> option, as in 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"> <geshi lang="bash">
luac -s -o /path/to/your.luac /path/to/your.lua luac -s -o /path/to/output_file.luac /path/to/input_file.lua
</geshi> </geshi>
If you're trying to load a standard Lua 5.1 bytecode file into an nginx linked with LuaJIT 2.0 or in the other way around, you will get an error message like below in your Nginx's <code>error.log</code> file: Attempts to load standard Lua 5.1 bytecode files into <code>ngx_lua</code> instances linked to LuaJIT 2.0 or vice versa, an error message such as that below will be logged in the Nginx <code>error.log</code> file:
<geshi lang="text"> <geshi lang="text">
[error] 13909\#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test.luac [error] 13909#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test_file.luac
</geshi> </geshi>
Loading bytecode files via the Lua primitives like <code>require</code> and <code>dofile</code> should always work as expected. Loading bytecode files via the Lua primitives like <code>require</code> and <code>dofile</code> should always work as expected.
@ -3726,8 +3740,8 @@ If server wide data sharing is required:
== Lua Coroutine Yielding/Resuming == == Lua Coroutine Yielding/Resuming ==
* 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. * 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.
* 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. * 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 normally allowed within <code>ngx_lua</code> 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.
* 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. * 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()] 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.
== Lua Variable Scope == == Lua Variable Scope ==
Care should be taken when importing modules and this form should be used: Care should be taken when importing modules and this form should be used:
@ -3894,6 +3908,7 @@ This module performs best when built with [http://luajit.org/luajit.html LuaJIT
= Nginx Compatibility = = Nginx Compatibility =
The module is compatible with the following versions of Nginx: The module is compatible with the following versions of Nginx:
* 1.2.x (last tested: 1.2.1)
* 1.1.x (last tested: 1.1.5) * 1.1.x (last tested: 1.1.5)
* 1.0.x (last tested: 1.0.15) * 1.0.x (last tested: 1.0.15)
* 0.9.x (last tested: 0.9.4) * 0.9.x (last tested: 0.9.4)
@ -3911,7 +3926,7 @@ Alternatively, <code>ngx_lua</code> can be manually compiled into Nginx:
# Install LuaJIT 2.0 (Recommended) or Lua 5.1 (Lua 5.2 is ''not'' supported yet). 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. # Install LuaJIT 2.0 (Recommended) or Lua 5.1 (Lua 5.2 is ''not'' supported yet). 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.
# Download the latest version of the ngx_devel_kit (NDK) module [http://github.com/simpl/ngx_devel_kit/tags HERE]. # Download the latest version of the ngx_devel_kit (NDK) module [http://github.com/simpl/ngx_devel_kit/tags HERE].
# Download the latest version of this module [http://github.com/chaoslawful/lua-nginx-module/tags HERE]. # Download the latest version of <code>ngx_lua</code> [http://github.com/chaoslawful/lua-nginx-module/tags HERE].
# Download the latest version of Nginx [http://nginx.org/ HERE] (See [[#Nginx Compatibility|Nginx Compatibility]]) # Download the latest version of Nginx [http://nginx.org/ HERE] (See [[#Nginx Compatibility|Nginx Compatibility]])
Build the source with this module: Build the source with this module:
@ -3987,7 +4002,7 @@ Please report bugs or submit patches by:
1 February, 2012 1 February, 2012
* 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. * 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 <code>ngx_lua</code> v0.3.1rc4 and ngx_openresty 1.0.6.13. thanks [http://weibo.com/cyberty @cyberty] for reporting it.
* 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). * 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).
* bugfix: fixed all the warnings from the clang static analyzer. * bugfix: fixed all the warnings from the clang static analyzer.
* feature: allow use of the <code>DDEBUG</code> macro from the outside (via the <code>-D DDEBUG=1</code> C compiler opton). * feature: allow use of the <code>DDEBUG</code> macro from the outside (via the <code>-D DDEBUG=1</code> C compiler opton).
@ -4002,7 +4017,7 @@ Please report bugs or submit patches by:
* 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. * 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.
* feature: now we also return the <code>Last-Modified</code> header (if any) for the subrequest response object. thanks @cyberty and sexybabes. * feature: now we also return the <code>Last-Modified</code> header (if any) for the subrequest response object. thanks @cyberty and sexybabes.
* feature: now [[#ngx.exec|ngx.exec]] supports Lua table as the second args argument value. thanks sexybabes. * feature: now [[#ngx.exec|ngx.exec]] supports Lua table as the second args argument value. thanks sexybabes.
* feature: implemented the [[#ngx.headers_sent|ngx.headers_sent]] API to check if response headers are sent (by ngx_lua). thanks @hugozhu. * feature: implemented the [[#ngx.headers_sent|ngx.headers_sent]] API to check if response headers are sent (by <code>ngx_lua</code>). thanks @hugozhu.
* 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. * 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.
* 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 李子义. * 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 李子义.
* bugfix: now we properly support setting the <code>Cache-Control</code> response header via the [[#ngx.header.HEADER|ngx.header.HEADER]] interface. * bugfix: now we properly support setting the <code>Cache-Control</code> response header via the [[#ngx.header.HEADER|ngx.header.HEADER]] interface.