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

docs: massive wording improvements from Dayo. also bumped version to 0.7.1.

This commit is contained in:
agentzh (Yichun Zhang) 2012-10-13 20:02:59 -07:00
Родитель 3875a33976
Коммит db2d5310b3
3 изменённых файлов: 284 добавлений и 309 удалений
Показать статистику Скачать Patch файл Скачать Diff файл Показать все файлы Свернуть все файлы

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

@ -8,8 +8,8 @@ Status
This module is under active development and is production ready.
Version
This document describes ngx_lua v0.7.0
(<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 10
This document describes ngx_lua v0.7.1
(<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 13
October 2012.
Synopsis
@ -257,9 +257,9 @@ Directives
to to reload the config file are to send a "HUP" signal or to restart
Nginx.
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.
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.
Disabling the Lua code cache is strongly discouraged for production use
and should only be used during development as it has a significant
@ -628,7 +628,7 @@ Directives
fastcgi_pass ...;
}
can be implemented in "ngx_lua" as:
can be implemented in ngx_lua as:
location = /check-spam {
internal;
@ -751,7 +751,7 @@ Directives
# proxy_pass/fastcgi_pass/postgres_pass/...
}
can be implemented in "ngx_lua" as:
can be implemented in ngx_lua as:
location / {
access_by_lua '
@ -1073,8 +1073,8 @@ Directives
client_body_buffer_size must have the same value as
client_max_body_size. Because when the content length exceeds
client_body_buffer_size but less than client_max_body_size, Nginx will
automatically buffer the data into a temporary file on the disk, which
will lead to empty value in the $request_body variable.
buffer the data into a temporary file on the disk, which will lead to
empty value in the $request_body variable.
If the current location includes rewrite_by_lua or rewrite_by_lua_file
directives, then the request body will be read just before the
@ -1205,9 +1205,9 @@ Directives
Default to 30 connections for every pool.
When the connection pool is exceeding the size limit, the least recently
used (idle) connection already in the pool will be closed automatically
to make room for the current connection.
When the connection pool exceeds the available size limit, the least
recently used (idle) connection already in the pool will be closed to
make room for the current connection.
Note that the cosocket connection pool is per nginx worker process
rather than per nginx server instance, so so size limit specified here
@ -1224,8 +1224,8 @@ Directives
This directive controls the default maximal idle time of the connections
in the cosocket built-in connection pool. When this timeout reaches,
idle connections will be closed automatically and removed from the pool.
This setting can be overridden by cosocket objects' setkeepalive method.
idle connections will be closed and removed from the pool. This setting
can be overridden by cosocket objects' setkeepalive method.
The "<time>" argument can be an integer, with an optional time unit,
like "s" (second), "ms" (millisecond), "m" (minute). The default time
@ -1240,11 +1240,11 @@ Directives
context: *http, server, location*
This directive can be used to toggle the automatic error logging when a
failure occurs for the TCP or UDP cosockets. If you are already doing
proper error handling and logging in your Lua code, then it is
recommended to turn this directive off to prevent data flushing in your
nginx error log files (which is usually rather expensive).
This directive can be used to toggle error logging when a failure occurs
for the TCP or UDP cosockets. If you are already doing proper error
handling and logging in your Lua code, then it is recommended to turn
this directive off to prevent data flushing in your nginx error log
files (which is usually rather expensive).
This directive was first introduced in the "v0.5.13" release.
@ -1255,9 +1255,9 @@ Directives
context: *http, server, location, location-if*
Enables or disables the automatic response caching for HTTP 1.0 (or
older) requests. This buffering mechanism is mainly used for HTTP 1.0
keep-alive which replies on a proper "Content-Length" response header.
Enables or disables response caching for HTTP 1.0 (or older) requests.
This buffering mechanism is mainly used for HTTP 1.0 keep-alive which
replies on a proper "Content-Length" response header.
If the Lua code explicitly sets a "Content-Length" response header
before sending the headers (either explicitly via ngx.send_headers or
@ -1305,8 +1305,8 @@ Nginx API for Lua
context of these configuration directives.
The API is exposed to Lua in the form of two standard packages "ngx" and
"ndk". These packages are in the default global scope within "ngx_lua"
and are always available within "ngx_lua" directives.
"ndk". These packages are in the default global scope within ngx_lua and
are always available within ngx_lua directives.
The packages can be introduced into external Lua modules by using the
package.seeall
@ -1636,8 +1636,7 @@ Nginx API for Lua
Nginx's subrequests provide a powerful way to make non-blocking internal
requests to other locations configured with disk file directory or *any*
other nginx C modules like "ngx_proxy", "ngx_fastcgi", "ngx_memc",
"ngx_postgres", "ngx_drizzle", and even "ngx_lua" itself and etc etc
etc.
"ngx_postgres", "ngx_drizzle", and even ngx_lua itself and etc etc etc.
Also note that subrequests just mimic the HTTP interface but there is
*no* extra HTTP/TCP traffic *nor* IPC involved. Everything works
@ -1727,10 +1726,10 @@ Nginx API for Lua
ngx.location.capture('/foo?a=1&b=3&c=%3a')
that is, this method will automatically escape argument keys and values
according to URI rules and concatenating them together into a complete
query string. The format for the Lua table passed as the "args" argument
is identical to the format used in the ngx.encode_args method.
that is, this method will escape argument keys and values according to
URI rules and concatenate them together into a complete query string.
The format for the Lua table passed as the "args" argument is identical
to the format used in the ngx.encode_args method.
The "args" option can also take plain query strings:
@ -2196,8 +2195,8 @@ Nginx API for Lua
ngx.req.set_uri_args({ a = 3, b = "hello world" })
where in the latter case, this method will automatically escape argument
keys and values according to the URI escaping rule.
where in the latter case, this method will escape argument keys and
values according to the URI escaping rule.
Multi-value arguments are also supported:
@ -2238,8 +2237,8 @@ Nginx API for Lua
Multiple occurrences of an argument key will result in a table value
holding all the values for that key in order.
Keys and values are automatically unescaped according to URI escaping
rules. In the settings above, "GET /test?a%20b=1%61+2" will yield:
Keys and values are unescaped according to URI escaping rules. In the
settings above, "GET /test?a%20b=1%61+2" will yield:
a b: 1a 2
@ -2326,8 +2325,7 @@ Nginx API for Lua
Multiple occurrences of an argument key will result in a table value
holding all of the values for that key in order.
Keys and values will be automatically unescaped according to URI
escaping rules.
Keys and values will be unescaped according to URI escaping rules.
With the settings above,
@ -2424,12 +2422,11 @@ Nginx API for Lua
are converted to the pure lower-case form by default, unless the "raw"
argument is set to "true" (default to "false").
Also, by default, an "__index" metamethod is added automatically to the
resulting Lua table that will normalize the keys to the pure lower-case
form with all underscores converted to dashes in case of a lookup miss.
For example, if a request header "My-Foo-Header" is present, then the
following invocations will all pick up the value of this header
correctly:
Also, by default, an "__index" metamethod is added to the resulting Lua
table and will normalize the keys to a pure lowercase form with all
underscores converted to dashes in case of a lookup miss. For example,
if a request header "My-Foo-Header" is present, then the following
invocations will all pick up the value of this header correctly:
ngx.say(headers.my_foo_header)
ngx.say(headers["My-Foo-Header"])
@ -2448,8 +2445,8 @@ Nginx API for Lua
"header_value", overriding any existing ones.
By default, all the subrequests subsequently initiated by
ngx.location.capture and ngx.location.capture_multi will automatically
inherit the new header.
ngx.location.capture and ngx.location.capture_multi will inherit the new
header.
Here is an example of setting the "Content-Length" header:
@ -2554,7 +2551,7 @@ Nginx API for Lua
If the request body has not been read yet, call ngx.req.read_body first
(or turned on lua_need_request_body to force this module to read the
request body automatically, but this is not recommended).
request body. This is not recommended however).
If the request body has been read into disk files, try calling the
ngx.req.get_body_file function instead.
@ -2578,13 +2575,13 @@ Nginx API for Lua
Retrieves the file name for the in-file request body data. Returns "nil"
if the request body has not been read or has been read into memory.
The returned file is read only and is usually cleaned up automatically
by Nginx's memory pool. It should not be manually modified, renamed, or
removed in Lua code.
The returned file is read only and is usually cleaned up by Nginx's
memory pool. It should not be manually modified, renamed, or removed in
Lua code.
If the request body has not been read yet, call ngx.req.read_body first
(or turned on lua_need_request_body to force this module to read the
request body automatically, but this is not recommended).
request body. This is not recommended however).
If the request body has been read into memory, try calling the
ngx.req.get_body_data function instead.
@ -2634,9 +2631,9 @@ Nginx API for Lua
by the "file_name" argument.
If the optional "auto_clean" argument is given a "true" value, then this
file will be automatically removed at request completion or the next
time this function or ngx.req.set_body_data are called in the same
request. The "auto_clean" is default to "false".
file will be removed at request completion or the next time this
function or ngx.req.set_body_data are called in the same request. The
"auto_clean" is default to "false".
Please ensure that the file specified by the "file_name" argument exists
and is readable by an Nginx worker process by setting its permission
@ -2677,8 +2674,8 @@ Nginx API for Lua
instead.
When the data can no longer be hold in the memory buffer for the request
body, then the data will automatically be flushed onto a temporary file
just like the standard request body reader in the Nginx core.
body, then the data will be flushed onto a temporary file just like the
standard request body reader in the Nginx core.
It is important to always call the ngx.req.finish_body after all the
data has been appended onto the current request body. Also, when this
@ -2711,8 +2708,8 @@ Nginx API for Lua
existing request body created by the ngx.req.init_body call.
When the data can no longer be hold in the memory buffer for the request
body, then the data will automatically be flushed onto a temporary file
just like the standard request body reader in the Nginx core.
body, then the data will be flushed onto a temporary file just like the
standard request body reader in the Nginx core.
It is important to always call the ngx.req.finish_body after all the
data has been appended onto the current request body.
@ -2762,10 +2759,9 @@ Nginx API for Lua
lua_need_request_body directive, and do not mix this call with
ngx.req.read_body and ngx.req.discard_body.
If there is any request body data that has been pre-read into the Nginx
core's request header buffer, the resulting cosocket object will take
care of that automatically. So there will not be any data loss due to
potential body data pre-reading.
If any request body data has been pre-read into the Nginx core request
header buffer, the resulting cosocket object will take care of this to
avoid potential data loss resulting from such pre-reading.
This function was first introduced in the "v0.5.0rc1" release.
@ -2808,8 +2804,7 @@ Nginx API for Lua
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.
ngx_lua to carry out URI escaping and string concatenation.
ngx.exec("/foo", { a = 3, b = "hello world" })
@ -2893,19 +2888,18 @@ Nginx API for Lua
Explicitly send out the response headers.
Note that there is normally no need to manually send out response
headers as "ngx_lua" will automatically send headers out before content
is output with ngx.say or ngx.print or when content_by_lua exits
normally.
headers as ngx_lua will automatically send headers out before content is
output with ngx.say or ngx.print or when content_by_lua exits normally.
ngx.headers_sent
syntax: *value = ngx.headers_sent*
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
syntax: *ngx.print(...)*
@ -3443,7 +3437,7 @@ Nginx API for Lua
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
Matches the "subject" string using the Perl-compatible regular
Matches the "subject" string using the Perl compatible regular
expression "regex" with the optional "options".
Only the first occurrence of the match is returned, or "nil" if no match
@ -3594,7 +3588,7 @@ Nginx API for Lua
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
Substitutes the first match of the Perl-compatible regular expression
Substitutes the first match of the Perl compatible regular expression
"regex" on the "subject" argument string with the string or function
argument "replace". The optional "options" argument has exactly the same
meaning as in ngx.re.match.
@ -4062,9 +4056,9 @@ Nginx API for Lua
The input argument "data" can either be a Lua string or a (nested) Lua
table holding string fragments. In case of table arguments, this method
will automatically copy all the string elements piece by piece to the
underlying Nginx socket send buffers, which is usually optimal than
doing string concatenation operations on the Lua land.
will copy all the string elements piece by piece to the underlying Nginx
socket send buffers, which is usually optimal than doing string
concatenation operations on the Lua land.
This feature was first introduced in the "v0.5.7" release.
@ -4114,10 +4108,10 @@ Nginx API for Lua
in case of success and returns "nil" with a string describing the error
otherwise.
For socket objects that have not invoked this method, they (and their
connections) will be automatically closed when the socket object is
released by the Lua GC (Garbage Collector) or the current client HTTP
request finishes processing.
Socket objects that have not invoked this method (and associated
connections) will be closed when the socket object is released by the
Lua GC (Garbage Collector) or the current client HTTP request finishes
processing.
This feature was first introduced in the "v0.5.7" release.
@ -4247,9 +4241,8 @@ Nginx API for Lua
method to specify various connect options:
* "pool" specify a custom name for the connection pool being used. If
omitted, then the connection pool name will be automatically
generated from the string template "<host>:<port>" or
"<unix-socket-path>".
omitted, then the connection pool name will be generated from the
string template "<host>:<port>" or "<unix-socket-path>".
The support for the options table argument was first introduced in the
"v0.5.7" release.
@ -4273,9 +4266,9 @@ Nginx API for Lua
The input argument "data" can either be a Lua string or a (nested) Lua
table holding string fragments. In case of table arguments, this method
will automatically copy all the string elements piece by piece to the
underlying Nginx socket send buffers, which is usually optimal than
doing string concatenation operations on the Lua land.
will copy all the string elements piece by piece to the underlying Nginx
socket send buffers, which is usually optimal than doing string
concatenation operations on the Lua land.
Timeout for the sending operation is controlled by the
lua_socket_send_timeout config directive and the settimeout method. And
@ -4379,9 +4372,9 @@ Nginx API for Lua
"size" of data on each invocation and will return "nil" at the last
invocation (either sees the boundary pattern or meets an error). For the
last successful invocation of the iterator function, the "err" return
value will be "nil" too. The iterator function will automatically reset
after its last successful invocation that returns "nil" data and "nil"
error. Consider the following example:
value will be "nil" too. The iterator function will be reset after the
last successful invocation that returns "nil" data and "nil" error.
Consider the following example:
local reader = sock:receiveuntil("\r\n--abcedhb")
@ -4464,15 +4457,15 @@ Nginx API for Lua
case of success and returns "nil" with a string describing the error
otherwise.
For socket objects that have invoked the setkeepalive method, there is
no need to call this method on it because the socket object is already
closed (and the current connection is saved into the built-in connection
pool).
Note that there is no need to call this method on socket objects that
have invoked the setkeepalive method because the socket object is
already closed (and the current connection is saved into the built-in
connection pool).
For socket objects that have not invoked setkeepalive nor this method,
they (and their connections) will be automatically closed when the
socket object is released by the Lua GC (Garbage Collector) or the
current client HTTP request finishes processing.
Socket objects that have not invoked this method (and associated
connections) will be closed when the socket object is released by the
Lua GC (Garbage Collector) or the current client HTTP request finishes
processing.
This feature was first introduced in the "v0.5.0rc1" release.
@ -4528,9 +4521,9 @@ Nginx API for Lua
the pool is created. When this argument is omitted, the default setting
in the lua_socket_pool_size config directive will be used.
When the connection pool is exceeding the size limit, the least recently
used (idle) connection already in the pool will be closed automatically
to make room for the current connection.
When the connection pool exceeds the available size limit, the least
recently used (idle) connection already in the pool will be closed to
make room for the current connection.
Note that the cosocket connection pool is per Nginx worker process
rather than per Nginx server instance, so the size limit specified here
@ -4632,10 +4625,9 @@ Nginx API for Lua
Creates a user Lua coroutines with a Lua function, and returns a
coroutine object.
Just behaves like the standard Lua coroutine.create
Similar to the standard Lua coroutine.create
(<http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.create>) API,
but works in the context of the Lua coroutines created automatically by
this Nginx module.
but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the "v0.6.0" release.
@ -4647,10 +4639,9 @@ Nginx API for Lua
Resumes the executation of a user Lua coroutine object previously
yielded or just created.
Just behaves like the standard Lua coroutine.resume
Similar to the standard Lua coroutine.resume
(<http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.resume>) API,
but works in the context of the Lua coroutines created automatically by
this Nginx module.
but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the "v0.6.0" release.
@ -4661,10 +4652,9 @@ Nginx API for Lua
Yields the executation of the current user Lua coroutine.
Just behaves like the standard Lua coroutine.yield
Similar to the standard Lua coroutine.yield
(<http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.yield>) API,
but works in the context of the Lua coroutines created automatically by
this Nginx module.
but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the "v0.6.0" release.
@ -4673,10 +4663,9 @@ Nginx API for Lua
context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
Just behaves like the standard Lua coroutine.wrap
Similar to the standard Lua coroutine.wrap
(<http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.wrap>) API,
but works in the context of the Lua coroutines created automatically by
this Nginx module.
but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the "v0.6.0" release.
@ -4710,19 +4699,19 @@ Nginx API for Lua
(or Lua coroutine) object represents this "light thread".
"Light threads" are just a special kind of Lua coroutines that are
scheduled automatically by the "ngx_lua" module.
scheduled by the ngx_lua module.
Before "ngx.thread.spawn" returns, the "func" will be called with those
optional arguments until it returns, aborts with an error, or gets
yielded automatically due to I/O operations via the Nginx API for Lua
(like <tcpsock:receive|/"tcpsock:receive">).
yielded due to I/O operations via the Nginx API for Lua (like
<tcpsock:receive|/"tcpsock:receive">).
After "ngx.thread.spawn" returns, the newly-created "light thread" will
keep running asynchronously usually at various I/O events.
All the Lua code chunks running by rewrite_by_lua, access_by_lua, and
content_by_lua are in a boilerplate "light thread" created automatically
by "ngx_lua". Such boilerplate "light thread" are also called "entry
by ngx_lua. Such boilerplate "light thread" are also called "entry
threads".
By default, the corresponding Nginx handler (e.g., rewrite_by_lua
@ -4747,7 +4736,7 @@ Nginx API for Lua
thread" to terminate before quitting the "world".
The "light threads" are not scheduled in a pre-emptive way. In other
words, no automatic time-slicing is performed. A "light thread" will
words, no time-slicing is performed automatically. A "light thread" will
keep running exclusively on the CPU until
1. a (nonblocking) I/O operation cannot be completed in a single run,
@ -4758,8 +4747,7 @@ Nginx API for Lua
ngx.redirect, or ngx.req.set_uri(uri, true).
For the first two cases, the "light thread" will usually be resumed
later by the "ngx_lua" scheduler unless a "stop-the-world" event
happens.
later by the ngx_lua scheduler unless a "stop-the-world" event happens.
User "light threads" can create "light threads" themselves and normal
user coroutiens created by coroutine.create can also create "light
@ -5033,8 +5021,8 @@ Lua/LuaJIT bytecode support
bytecode files directly.
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
compatible with that used by 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 -b /path/to/input_file.lua /path/to/output_file.luac
@ -5044,14 +5032,14 @@ Lua/LuaJIT bytecode support
/path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.luac
Please refer to the official LuaJIT documentation for the "-b" option
for more details:
Please refer to the official LuaJIT documentation on the "-b" option for
more details:
http://luajit.org/running.html#opt_b
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:
Similarly, if using the standard Lua 5.1 interpreter with ngx_lua, Lua
compatible bytecode files must be generated using the "luac" commandline
utility as shown:
luac -o /path/to/output_file.luac /path/to/input_file.lua
@ -5061,9 +5049,9 @@ Lua/LuaJIT bytecode support
luac -s -o /path/to/output_file.luac /path/to/input_file.lua
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:
Attempts to load standard Lua 5.1 bytecode files into ngx_lua instances
linked to LuaJIT 2.0 or vice versa, will result in an error message,
such as that below, being logged into the Nginx "error.log" file:
[error] 13909#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test_file.luac
@ -5071,27 +5059,24 @@ Lua/LuaJIT bytecode support
"dofile" should always work as expected.
HTTP 1.0 support
The HTTP 1.0 protocol does not support chunked outputs and always
requires an explicit "Content-Length" header when the response body is
non-empty in order to support the HTTP 1.0 keep-alive (as required by
the ApacheBench (ab) tool). So when an HTTP 1.0 request is present and
the lua_http10_buffering directive is turned "on", this module will
automatically buffer all the outputs of user calls of ngx.say and
ngx.print and postpone sending response headers until it sees all the
outputs in the response body, and at that time ngx_lua can calculate the
total length of the body and construct a proper "Content-Length" header
for the HTTP 1.0 client.
If the user Lua code sets the "Content-Length" response header itself,
then the automatic buffering will be disabled even if the
The HTTP 1.0 protocol does not support chunked output and requires an
explicit "Content-Length" 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 directive is turned "on", ngx_lua will
buffer the output of ngx.say and 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 "Content-Length" header to return to the HTTP 1.0
client. If the "Content-Length" response header is set in the running
Lua code, however, this buffering will be disabled even if the
lua_http10_buffering directive is turned "on".
For large streaming output responses, it is important to disable the
lua_http10_buffering directive to minimise memory usage.
Note that, common HTTP benchmark tools like "ab" and "http_load" always
issue HTTP 1.0 requests by default. To force "curl" to send HTTP 1.0
requests, use the -0 option.
Note that common HTTP benchmark tools such as "ab" and "http_load" issue
HTTP 1.0 requests by default. To force "curl" to send HTTP 1.0 requests,
use the -0 option.
Data Sharing within an Nginx Worker
To globally share data among all the requests handled by the same nginx
@ -5135,7 +5120,7 @@ Data Sharing within an Nginx Worker
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
*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.
@ -5183,10 +5168,10 @@ Known Issues
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
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.
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.
* As the standard Lua 5.1 interpreter's VM is not fully resumable, the
methods ngx.location.capture, ngx.location.capture_multi,
@ -5377,9 +5362,9 @@ Typical Uses
Nginx Compatibility
The module is compatible with the following versions of Nginx:
* 1.3.x (last tested: 1.3.6)
* 1.3.x (last tested: 1.3.7)
* 1.2.x (last tested: 1.2.3)
* 1.2.x (last tested: 1.2.4)
* 1.1.x (last tested: 1.1.5)
@ -5396,12 +5381,12 @@ Code Repository
Installation
The ngx_openresty bundle (<http://openresty.org>) can be used to install
Nginx, "ngx_lua", either one of the standard Lua 5.1 interpreter or
LuaJIT 2.0, as well as a package of powerful companion Nginx modules.
The basic installation step is a simple "./configure --with-luajit &&
make && make install".
Nginx, ngx_lua, either one of the standard Lua 5.1 interpreter or LuaJIT
2.0, as well as a package of powerful companion Nginx modules. The basic
installation step is a simple "./configure --with-luajit && make && make
install".
Alternatively, "ngx_lua" can be manually compiled into Nginx:
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). LuajIT can be downloaded from the the LuaJIT project
@ -5412,7 +5397,7 @@ Installation
2. Download the latest version of the ngx_devel_kit (NDK) module HERE
(<http://github.com/simpl/ngx_devel_kit/tags>).
3. Download the latest version of "ngx_lua" HERE
3. Download the latest version of ngx_lua HERE
(<http://github.com/chaoslawful/lua-nginx-module/tags>).
4. Download the latest version of Nginx HERE (<http://nginx.org/>) (See
@ -5420,9 +5405,9 @@ Installation
Build the source with this module:
wget 'http://nginx.org/download/nginx-1.2.3.tar.gz'
tar -xzvf nginx-1.2.3.tar.gz
cd nginx-1.2.3/
wget 'http://nginx.org/download/nginx-1.2.4.tar.gz'
tar -xzvf nginx-1.2.4.tar.gz
cd nginx-1.2.4/
# tell nginx's build system where to find LuaJIT:
export LUAJIT_LIB=/path/to/luajit/lib
@ -5510,7 +5495,7 @@ TODO
demonstrated in this sample code
(<http://agentzh.org/misc/nginx/lua-thread2.lua>).
* add Lua code automatic time slicing support by yielding and resuming
* add automatic Lua code time slicing support by yielding and resuming
the Lua VM actively via Lua's debug hooks.
* add "stat" mode similar to mod_lua

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

@ -18,7 +18,7 @@ This module is under active development and is production ready.
Version
=======
This document describes ngx_lua [v0.7.0](https://github.com/chaoslawful/lua-nginx-module/tags) released on 10 October 2012.
This document describes ngx_lua [v0.7.1](https://github.com/chaoslawful/lua-nginx-module/tags) released on 13 October 2012.
Synopsis
========
@ -247,7 +247,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
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.
Disabling the Lua code cache is strongly
@ -568,7 +568,7 @@ Note that the [ngx_eval](http://www.grid.net.ru/nginx/eval.en.html) module can b
}
can be implemented in `ngx_lua` as:
can be implemented in ngx_lua as:
location = /check-spam {
@ -669,7 +669,7 @@ Note that the [ngx_auth_request](http://mdounin.ru/hg/ngx_http_auth_request_modu
}
can be implemented in `ngx_lua` as:
can be implemented in ngx_lua as:
location / {
@ -948,7 +948,7 @@ lua_need_request_body
Determines whether to force the request body data to be read before running rewrite/access/access_by_lua* or not. The Nginx core does not read the client request body by default and if request body data is required, then this directive should be turned `on` or the [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) function should be called within the Lua code.
To read the request body data within the [$request_body](http://wiki.nginx.org/HttpCoreModule#.24request_body) variable,
[client_body_buffer_size](http://wiki.nginx.org/HttpCoreModule#client_body_buffer_size) must have the same value as [client_max_body_size](http://wiki.nginx.org/HttpCoreModule#client_max_body_size). Because when the content length exceeds [client_body_buffer_size](http://wiki.nginx.org/HttpCoreModule#client_body_buffer_size) but less than [client_max_body_size](http://wiki.nginx.org/HttpCoreModule#client_max_body_size), Nginx will automatically buffer the data into a temporary file on the disk, which will lead to empty value in the [$request_body](http://wiki.nginx.org/HttpCoreModule#.24request_body) variable.
[client_body_buffer_size](http://wiki.nginx.org/HttpCoreModule#client_body_buffer_size) must have the same value as [client_max_body_size](http://wiki.nginx.org/HttpCoreModule#client_max_body_size). Because when the content length exceeds [client_body_buffer_size](http://wiki.nginx.org/HttpCoreModule#client_body_buffer_size) but less than [client_max_body_size](http://wiki.nginx.org/HttpCoreModule#client_max_body_size), Nginx will buffer the data into a temporary file on the disk, which will lead to empty value in the [$request_body](http://wiki.nginx.org/HttpCoreModule#.24request_body) variable.
If the current location includes [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua) or [rewrite_by_lua_file](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua_file) directives,
then the request body will be read just before the [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua) or [rewrite_by_lua_file](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua_file) code is run (and also at the
@ -1072,7 +1072,7 @@ Specifies the size limit (in terms of connection count) for every cosocket conne
Default to 30 connections for every pool.
When the connection pool is exceeding the size limit, the least recently used (idle) connection already in the pool will be closed automatically to make room for the current connection.
When the connection pool exceeds the available size limit, the least recently used (idle) connection already in the pool will be closed to make room for the current connection.
Note that the cosocket connection pool is per nginx worker process rather than per nginx server instance, so so size limit specified here also applies to every single nginx worker process.
@ -1087,7 +1087,7 @@ lua_socket_keepalive_timeout
**context:** *http, server, location*
This directive controls the default maximal idle time of the connections in the cosocket built-in connection pool. When this timeout reaches, idle connections will be closed automatically and removed from the pool. This setting can be overridden by cosocket objects' [setkeepalive](http://wiki.nginx.org/HttpLuaModule#tcpsock:setkeepalive) method.
This directive controls the default maximal idle time of the connections in the cosocket built-in connection pool. When this timeout reaches, idle connections will be closed and removed from the pool. This setting can be overridden by cosocket objects' [setkeepalive](http://wiki.nginx.org/HttpLuaModule#tcpsock:setkeepalive) method.
The `<time>` argument can be an integer, with an optional time unit, like `s` (second), `ms` (millisecond), `m` (minute). The default time unit is `s`, i.e., "second". The default setting is `60s`.
@ -1102,7 +1102,7 @@ lua_socket_log_errors
**context:** *http, server, location*
This directive can be used to toggle the automatic error logging when a failure occurs for the TCP or UDP cosockets. If you are already doing proper error handling and logging in your Lua code, then it is recommended to turn this directive off to prevent data flushing in your nginx error log files (which is usually rather expensive).
This directive can be used to toggle error logging when a failure occurs for the TCP or UDP cosockets. If you are already doing proper error handling and logging in your Lua code, then it is recommended to turn this directive off to prevent data flushing in your nginx error log files (which is usually rather expensive).
This directive was first introduced in the `v0.5.13` release.
@ -1115,7 +1115,7 @@ lua_http10_buffering
**context:** *http, server, location, location-if*
Enables or disables the automatic response caching for HTTP 1.0 (or older) requests. This buffering mechanism is mainly used for HTTP 1.0 keep-alive which replies on a proper `Content-Length` response header.
Enables or disables response caching for HTTP 1.0 (or older) requests. This buffering mechanism is mainly used for HTTP 1.0 keep-alive which replies on a proper `Content-Length` response header.
If the Lua code explicitly sets a `Content-Length` response header before sending the headers (either explicitly via [ngx.send_headers](http://wiki.nginx.org/HttpLuaModule#ngx.send_headers) or implicitly via the first [ngx.say](http://wiki.nginx.org/HttpLuaModule#ngx.say) or [ngx.print](http://wiki.nginx.org/HttpLuaModule#ngx.print) call).
@ -1157,7 +1157,7 @@ Introduction
------------
The various `*_by_lua` and `*_by_lua_file` configuration directives serve as gateways to the Lua API within the `nginx.conf` file. The Nginx Lua API described below can only be called within the user Lua code run in the context of these configuration directives.
The API is exposed to Lua in the form of two standard packages `ngx` and `ndk`. These packages are in the default global scope within `ngx_lua` and are always available within `ngx_lua` directives.
The API is exposed to Lua in the form of two standard packages `ngx` and `ndk`. These packages are in the default global scope within ngx_lua and are always available within ngx_lua directives.
The packages can be introduced into external Lua modules by using the [package.seeall](http://www.lua.org/manual/5.1/manual.html#pdf-package.seeall) option:
@ -1473,7 +1473,7 @@ ngx.location.capture
Issue a synchronous but still non-blocking *Nginx Subrequest* using `uri`.
Nginx's subrequests provide a powerful way to make non-blocking internal requests to other locations configured with disk file directory or *any* other nginx C modules like `ngx_proxy`, `ngx_fastcgi`, `ngx_memc`,
`ngx_postgres`, `ngx_drizzle`, and even `ngx_lua` itself and etc etc etc.
`ngx_postgres`, `ngx_drizzle`, and even ngx_lua itself and etc etc etc.
Also note that subrequests just mimic the HTTP interface but there is *no* extra HTTP/TCP traffic *nor* IPC involved. Everything works internally, efficiently, on the C level.
@ -1556,8 +1556,8 @@ is equivalent to
ngx.location.capture('/foo?a=1&b=3&c=%3a')
that is, this method will automatically escape argument keys and values according to URI rules and
concatenating them together into a complete query string. The format for the Lua table passed as the `args` argument is identical to the format used in the [ngx.encode_args](http://wiki.nginx.org/HttpLuaModule#ngx.encode_args) method.
that is, this method will escape argument keys and values according to URI rules and
concatenate them together into a complete query string. The format for the Lua table passed as the `args` argument is identical to the format used in the [ngx.encode_args](http://wiki.nginx.org/HttpLuaModule#ngx.encode_args) method.
The `args` option can also take plain query strings:
@ -2037,7 +2037,7 @@ or a Lua table holding the query arguments' key-value pairs, as in
ngx.req.set_uri_args({ a = 3, b = "hello world" })
where in the latter case, this method will automatically escape argument keys and values according to the URI escaping rule.
where in the latter case, this method will escape argument keys and values according to the URI escaping rule.
Multi-value arguments are also supported:
@ -2083,7 +2083,7 @@ Then `GET /test?foo=bar&bar=baz&bar=blah` will yield the response body
Multiple occurrences of an argument key will result in a table value holding all the values for that key in order.
Keys and values are automatically unescaped according to URI escaping rules. In the settings above, `GET /test?a%20b=1%61+2` will yield:
Keys and values are unescaped according to URI escaping rules. In the settings above, `GET /test?a%20b=1%61+2` will yield:
a b: 1a 2
@ -2176,7 +2176,7 @@ will yield the response body like
Multiple occurrences of an argument key will result in a table value holding all of the values for that key in order.
Keys and values will be automatically unescaped according to URI escaping rules.
Keys and values will be unescaped according to URI escaping rules.
With the settings above,
@ -2278,7 +2278,7 @@ Removing the `max_headers` cap is strongly discouraged.
Since the `0.6.9` release, all the header names in the Lua table returned are converted to the pure lower-case form by default, unless the `raw` argument is set to `true` (default to `false`).
Also, by default, an `__index` metamethod is added automatically to the resulting Lua table that will normalize the keys to the pure lower-case form with all underscores converted to dashes in case of a lookup miss. For example, if a request header `My-Foo-Header` is present, then the following invocations will all pick up the value of this header correctly:
Also, by default, an `__index` metamethod is added to the resulting Lua table and will normalize the keys to a pure lowercase form with all underscores converted to dashes in case of a lookup miss. For example, if a request header `My-Foo-Header` is present, then the following invocations will all pick up the value of this header correctly:
ngx.say(headers.my_foo_header)
@ -2296,7 +2296,7 @@ ngx.req.set_header
Set the current request's request header named `header_name` to value `header_value`, overriding any existing ones.
By default, all the subrequests subsequently initiated by [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) and [ngx.location.capture_multi](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture_multi) will automatically inherit the new header.
By default, all the subrequests subsequently initiated by [ngx.location.capture](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture) and [ngx.location.capture_multi](http://wiki.nginx.org/HttpLuaModule#ngx.location.capture_multi) will inherit the new header.
Here is an example of setting the `Content-Length` header:
@ -2389,7 +2389,7 @@ This function returns `nil` if
1. the request body has been read into disk temporary files,
1. or the request body has zero size.
If the request body has not been read yet, call [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) first (or turned on [lua_need_request_body](http://wiki.nginx.org/HttpLuaModule#lua_need_request_body) to force this module to read the request body automatically, but this is not recommended).
If the request body has not been read yet, call [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) first (or turned on [lua_need_request_body](http://wiki.nginx.org/HttpLuaModule#lua_need_request_body) to force this module to read the request body. This is not recommended however).
If the request body has been read into disk files, try calling the [ngx.req.get_body_file](http://wiki.nginx.org/HttpLuaModule#ngx.req.get_body_file) function instead.
@ -2409,9 +2409,9 @@ ngx.req.get_body_file
Retrieves the file name for the in-file request body data. Returns `nil` if the request body has not been read or has been read into memory.
The returned file is read only and is usually cleaned up automatically by Nginx's memory pool. It should not be manually modified, renamed, or removed in Lua code.
The returned file is read only and is usually cleaned up by Nginx's memory pool. It should not be manually modified, renamed, or removed in Lua code.
If the request body has not been read yet, call [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) first (or turned on [lua_need_request_body](http://wiki.nginx.org/HttpLuaModule#lua_need_request_body) to force this module to read the request body automatically, but this is not recommended).
If the request body has not been read yet, call [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) first (or turned on [lua_need_request_body](http://wiki.nginx.org/HttpLuaModule#lua_need_request_body) to force this module to read the request body. This is not recommended however).
If the request body has been read into memory, try calling the [ngx.req.get_body_data](http://wiki.nginx.org/HttpLuaModule#ngx.req.get_body_data) function instead.
@ -2447,7 +2447,7 @@ ngx.req.set_body_file
Set the current request's request body using the in-file data specified by the `file_name` argument.
If the optional `auto_clean` argument is given a `true` value, then this file will be automatically removed at request completion or the next time this function or [ngx.req.set_body_data](http://wiki.nginx.org/HttpLuaModule#ngx.req.set_body_data) are called in the same request. The `auto_clean` is default to `false`.
If the optional `auto_clean` argument is given a `true` value, then this file will be removed at request completion or the next time this function or [ngx.req.set_body_data](http://wiki.nginx.org/HttpLuaModule#ngx.req.set_body_data) are called in the same request. The `auto_clean` is default to `false`.
Please ensure that the file specified by the `file_name` argument exists and is readable by an Nginx worker process by setting its permission properly to avoid Lua exception errors.
@ -2470,7 +2470,7 @@ Creates a new blank request body for the current request and inializes the buffe
If the `buffer_size` argument is specified, then its value will be used for the size of the memory buffer for body writing with [ngx.req.append_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.append_body). If the argument is omitted, then the value specified by the standard [client_body_buffer_size](http://wiki.nginx.org/HttpCoreModule#client_body_buffer_size) directive will be used instead.
When the data can no longer be hold in the memory buffer for the request body, then the data will automatically be flushed onto a temporary file just like the standard request body reader in the Nginx core.
When the data can no longer be hold in the memory buffer for the request body, then the data will be flushed onto a temporary file just like the standard request body reader in the Nginx core.
It is important to always call the [ngx.req.finish_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.finish_body) after all the data has been appended onto the current request body. Also, when this function is used together with [ngx.req.socket](http://wiki.nginx.org/HttpLuaModule#ngx.req.socket), it is required to call [ngx.req.socket](http://wiki.nginx.org/HttpLuaModule#ngx.req.socket) *before* this function, or you will get the "request body already exists" error message.
@ -2496,7 +2496,7 @@ ngx.req.append_body
Append new data chunk specified by the `data_chunk` argument onto the existing request body created by the [ngx.req.init_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.init_body) call.
When the data can no longer be hold in the memory buffer for the request body, then the data will automatically be flushed onto a temporary file just like the standard request body reader in the Nginx core.
When the data can no longer be hold in the memory buffer for the request body, then the data will be flushed onto a temporary file just like the standard request body reader in the Nginx core.
It is important to always call the [ngx.req.finish_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.finish_body) after all the data has been appended onto the current request body.
@ -2532,7 +2532,7 @@ In case of error, `nil` will be returned as well as a string describing the erro
The socket object returned by this method is usually used to read the current request's body in a streaming fashion. Do not turn on the [lua_need_request_body](http://wiki.nginx.org/HttpLuaModule#lua_need_request_body) directive, and do not mix this call with [ngx.req.read_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.read_body) and [ngx.req.discard_body](http://wiki.nginx.org/HttpLuaModule#ngx.req.discard_body).
If there is any request body data that has been pre-read into the Nginx core's request header buffer, the resulting cosocket object will take care of that automatically. So there will not be any data loss due to potential body data pre-reading.
If any request body data has been pre-read into the Nginx core request header buffer, the resulting cosocket object will take care of this to avoid potential data loss resulting from such pre-reading.
This function was first introduced in the `v0.5.0rc1` release.
@ -2578,7 +2578,7 @@ The optional second `args` can be used to specify extra URI query arguments, for
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.
ngx.exec("/foo", { a = 3, b = "hello world" })
@ -2672,7 +2672,7 @@ ngx.send_headers
Explicitly send out the response headers.
Note that there is normally no need to manually send out response headers as `ngx_lua` will automatically send headers out
Note that there is normally no need to manually send out response headers as ngx_lua will automatically send headers out
before content is output with [ngx.say](http://wiki.nginx.org/HttpLuaModule#ngx.say) or [ngx.print](http://wiki.nginx.org/HttpLuaModule#ngx.print) or when [content_by_lua](http://wiki.nginx.org/HttpLuaModule#content_by_lua) exits normally.
ngx.headers_sent
@ -2681,9 +2681,9 @@ ngx.headers_sent
**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
---------
@ -3177,7 +3177,7 @@ ngx.re.match
**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
Matches the `subject` string using the Perl-compatible regular expression `regex` with the optional `options`.
Matches the `subject` string using the Perl compatible regular expression `regex` with the optional `options`.
Only the first occurrence of the match is returned, or `nil` if no match is found. In case of fatal errors, like seeing bad `UTF-8` sequences in `UTF-8` mode, a Lua exception will be raised.
@ -3318,7 +3318,7 @@ ngx.re.sub
**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
Substitutes the first match of the Perl-compatible regular expression `regex` on the `subject` argument string with the string or function argument `replace`. The optional `options` argument has exactly the same meaning as in [ngx.re.match](http://wiki.nginx.org/HttpLuaModule#ngx.re.match).
Substitutes the first match of the Perl compatible regular expression `regex` on the `subject` argument string with the string or function argument `replace`. The optional `options` argument has exactly the same meaning as in [ngx.re.match](http://wiki.nginx.org/HttpLuaModule#ngx.re.match).
This method returns the resulting new string as well as the number of successful substitutions, or throw out a Lua exception when an error occurred (syntax errors in the `<replace>` string argument, for example).
@ -3703,7 +3703,7 @@ Sends data on the current UDP or datagram unix domain socket object.
In case of success, it returns `1`. Otherwise, it returns `nil` and a string describing the error.
The input argument `data` can either be a Lua string or a (nested) Lua table holding string fragments. In case of table arguments, this method will automatically copy all the string elements piece by piece to the underlying Nginx socket send buffers, which is usually optimal than doing string concatenation operations on the Lua land.
The input argument `data` can either be a Lua string or a (nested) Lua table holding string fragments. In case of table arguments, this method will copy all the string elements piece by piece to the underlying Nginx socket send buffers, which is usually optimal than doing string concatenation operations on the Lua land.
This feature was first introduced in the `v0.5.7` release.
@ -3747,7 +3747,7 @@ udpsock:close
Closes the current UDP or datagram unix domain socket. It returns the `1` in case of success and returns `nil` with a string describing the error otherwise.
For socket objects that have not invoked this method, they (and their connections) will be automatically closed when the socket object is released by the Lua GC (Garbage Collector) or the current client HTTP request finishes processing.
Socket objects that have not invoked this method (and associated connections) will be closed when the socket object is released by the Lua GC (Garbage Collector) or the current client HTTP request finishes processing.
This feature was first introduced in the `v0.5.7` release.
@ -3856,7 +3856,7 @@ Calling this method on an already connected socket object will cause the origina
An optional Lua table can be specified as the last argument to this method to specify various connect options:
* `pool`
specify a custom name for the connection pool being used. If omitted, then the connection pool name will be automatically generated from the string template `"<host>:<port>"` or `"<unix-socket-path>"`.
specify a custom name for the connection pool being used. If omitted, then the connection pool name will be generated from the string template `"<host>:<port>"` or `"<unix-socket-path>"`.
The support for the options table argument was first introduced in the `v0.5.7` release.
@ -3874,7 +3874,7 @@ This method is a synchronous operation that will not return until *all* the data
In case of success, it returns the total number of bytes that have been sent. Otherwise, it returns `nil` and a string describing the error.
The input argument `data` can either be a Lua string or a (nested) Lua table holding string fragments. In case of table arguments, this method will automatically copy all the string elements piece by piece to the underlying Nginx socket send buffers, which is usually optimal than doing string concatenation operations on the Lua land.
The input argument `data` can either be a Lua string or a (nested) Lua table holding string fragments. In case of table arguments, this method will copy all the string elements piece by piece to the underlying Nginx socket send buffers, which is usually optimal than doing string concatenation operations on the Lua land.
Timeout for the sending operation is controlled by the [lua_socket_send_timeout](http://wiki.nginx.org/HttpLuaModule#lua_socket_send_timeout) config directive and the [settimeout](http://wiki.nginx.org/HttpLuaModule#tcpsock:settimeout) method. And the latter takes priority. For example:
@ -3951,7 +3951,7 @@ In case of error, the iterator function will return `nil` along with a string de
The iterator function can be called multiple times and can be mixed safely with other cosocket method calls or other iterator function calls.
The iterator function behaves differently (i.e., like a real iterator) when it is called with a `size` argument. That is, it will read that `size` of data on each invocation and will return `nil` at the last invocation (either sees the boundary pattern or meets an error). For the last successful invocation of the iterator function, the `err` return value will be `nil` too. The iterator function will automatically reset after its last successful invocation that returns `nil` data and `nil` error. Consider the following example:
The iterator function behaves differently (i.e., like a real iterator) when it is called with a `size` argument. That is, it will read that `size` of data on each invocation and will return `nil` at the last invocation (either sees the boundary pattern or meets an error). For the last successful invocation of the iterator function, the `err` return value will be `nil` too. The iterator function will be reset after the last successful invocation that returns `nil` data and `nil` error. Consider the following example:
local reader = sock:receiveuntil("\r\n--abcedhb")
@ -4025,9 +4025,9 @@ tcpsock:close
Closes the current TCP or stream unix domain socket. It returns the `1` in case of success and returns `nil` with a string describing the error otherwise.
For socket objects that have invoked the [setkeepalive](http://wiki.nginx.org/HttpLuaModule#tcpsock:setkeepalive) method, there is no need to call this method on it because the socket object is already closed (and the current connection is saved into the built-in connection pool).
Note that there is no need to call this method on socket objects that have invoked the [setkeepalive](http://wiki.nginx.org/HttpLuaModule#tcpsock:setkeepalive) method because the socket object is already closed (and the current connection is saved into the built-in connection pool).
For socket objects that have not invoked [setkeepalive](http://wiki.nginx.org/HttpLuaModule#tcpsock:setkeepalive) nor this method, they (and their connections) will be automatically closed when the socket object is released by the Lua GC (Garbage Collector) or the current client HTTP request finishes processing.
Socket objects that have not invoked this method (and associated connections) will be closed when the socket object is released by the Lua GC (Garbage Collector) or the current client HTTP request finishes processing.
This feature was first introduced in the `v0.5.0rc1` release.
@ -4067,7 +4067,7 @@ The first optional argument, `timeout`, can be used to specify the maximal idle
The second optional argument, `size`, can be used to specify the maximal number of connections allowed in the connection pool for the current server (i.e., the current host-port pair or the unix domain socket file path). Note that the size of the connection pool cannot be changed once the pool is created. When this argument is omitted, the default setting in the [lua_socket_pool_size](http://wiki.nginx.org/HttpLuaModule#lua_socket_pool_size) config directive will be used.
When the connection pool is exceeding the size limit, the least recently used (idle) connection already in the pool will be closed automatically to make room for the current connection.
When the connection pool exceeds the available size limit, the least recently used (idle) connection already in the pool will be closed to make room for the current connection.
Note that the cosocket connection pool is per Nginx worker process rather than per Nginx server instance, so the size limit specified here also applies to every single Nginx worker process.
@ -4149,7 +4149,7 @@ coroutine.create
Creates a user Lua coroutines with a Lua function, and returns a coroutine object.
Just behaves like the standard Lua [coroutine.create](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.create) API, but works in the context of the Lua coroutines created automatically by this Nginx module.
Similar to the standard Lua [coroutine.create](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.create) API, but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the `v0.6.0` release.
@ -4161,7 +4161,7 @@ coroutine.resume
Resumes the executation of a user Lua coroutine object previously yielded or just created.
Just behaves like the standard Lua [coroutine.resume](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.resume) API, but works in the context of the Lua coroutines created automatically by this Nginx module.
Similar to the standard Lua [coroutine.resume](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.resume) API, but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the `v0.6.0` release.
@ -4173,7 +4173,7 @@ coroutine.yield
Yields the executation of the current user Lua coroutine.
Just behaves like the standard Lua [coroutine.yield](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.yield) API, but works in the context of the Lua coroutines created automatically by this Nginx module.
Similar to the standard Lua [coroutine.yield](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.yield) API, but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the `v0.6.0` release.
@ -4183,7 +4183,7 @@ coroutine.wrap
**context:** *rewrite_by_lua*, access_by_lua*, content_by_lua**
Just behaves like the standard Lua [coroutine.wrap](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.wrap) API, but works in the context of the Lua coroutines created automatically by this Nginx module.
Similar to the standard Lua [coroutine.wrap](http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.wrap) API, but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the `v0.6.0` release.
@ -4215,13 +4215,13 @@ ngx.thread.spawn
Spawns a new user "light thread" with the Lua function `func` as well as those optional arguments `arg1`, `arg2`, and etc. Returns a Lua thread (or Lua coroutine) object represents this "light thread".
"Light threads" are just a special kind of Lua coroutines that are scheduled automatically by the `ngx_lua` module.
"Light threads" are just a special kind of Lua coroutines that are scheduled by the ngx_lua module.
Before `ngx.thread.spawn` returns, the `func` will be called with those optional arguments until it returns, aborts with an error, or gets yielded automatically due to I/O operations via the [Nginx API for Lua](http://wiki.nginx.org/HttpLuaModule#Nginx_API_for_Lua) (like [tcpsock:receive](http://wiki.nginx.org/HttpLuaModule#tcpsock:receive)).
Before `ngx.thread.spawn` returns, the `func` will be called with those optional arguments until it returns, aborts with an error, or gets yielded due to I/O operations via the [Nginx API for Lua](http://wiki.nginx.org/HttpLuaModule#Nginx_API_for_Lua) (like [tcpsock:receive](http://wiki.nginx.org/HttpLuaModule#tcpsock:receive)).
After `ngx.thread.spawn` returns, the newly-created "light thread" will keep running asynchronously usually at various I/O events.
All the Lua code chunks running by [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua), [access_by_lua](http://wiki.nginx.org/HttpLuaModule#access_by_lua), and [content_by_lua](http://wiki.nginx.org/HttpLuaModule#content_by_lua) are in a boilerplate "light thread" created automatically by `ngx_lua`. Such boilerplate "light thread" are also called "entry threads".
All the Lua code chunks running by [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua), [access_by_lua](http://wiki.nginx.org/HttpLuaModule#access_by_lua), and [content_by_lua](http://wiki.nginx.org/HttpLuaModule#content_by_lua) are in a boilerplate "light thread" created automatically by ngx_lua. Such boilerplate "light thread" are also called "entry threads".
By default, the corresponding Nginx handler (e.g., [rewrite_by_lua](http://wiki.nginx.org/HttpLuaModule#rewrite_by_lua) handler) will not terminate until
1. both the "entry thread" and all the user "light threads" terminates,
@ -4232,12 +4232,12 @@ When the user "light thread" terminates with a Lua error, however, it will not a
Due to the limitation in the Nginx subrequest model, it is not allowed to abort a running Nginx subrequest in general. So it is also prohibited to abort a running "light thread" that is pending on one ore more Nginx subrequests. You must call [ngx.thread.wait](http://wiki.nginx.org/HttpLuaModule#ngx.thread.wait) to wait for those "light thread" to terminate before quitting the "world".
The "light threads" are not scheduled in a pre-emptive way. In other words, no automatic time-slicing is performed. A "light thread" will keep running exclusively on the CPU until
The "light threads" are not scheduled in a pre-emptive way. In other words, no time-slicing is performed automatically. A "light thread" will keep running exclusively on the CPU until
1. a (nonblocking) I/O operation cannot be completed in a single run,
1. it calls [coroutine.yield](http://wiki.nginx.org/HttpLuaModule#coroutine.yield) to actively give up execution, or
1. it is aborted by a Lua error or an invocation of [ngx.exit](http://wiki.nginx.org/HttpLuaModule#ngx.exit), [ngx.exec](http://wiki.nginx.org/HttpLuaModule#ngx.exec), [ngx.redirect](http://wiki.nginx.org/HttpLuaModule#ngx.redirect), or [ngx.req.set_uri(uri, true)](http://wiki.nginx.org/HttpLuaModule#ngx.req.set_uri).
For the first two cases, the "light thread" will usually be resumed later by the `ngx_lua` scheduler unless a "stop-the-world" event happens.
For the first two cases, the "light thread" will usually be resumed later by the ngx_lua scheduler unless a "stop-the-world" event happens.
User "light threads" can create "light threads" themselves and normal user coroutiens created by [coroutine.create](http://wiki.nginx.org/HttpLuaModule#coroutine.create) can also create "light threads". The coroutine (be it a normal Lua coroutine or a "light thread") that directly spawns the "light thread" is called the "parent coroutine" for the "light thread" newly spawned.
@ -4480,7 +4480,7 @@ Lua/LuaJIT bytecode support
As from the `v0.5.0rc32` release, all `*_by_lua_file` configure directives (such as [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 directly.
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:
Please note that the bytecode format used by LuaJIT 2.0 is not compatible with that used by 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 -b /path/to/input_file.lua /path/to/output_file.luac
@ -4492,11 +4492,11 @@ The `-bg` option can be used to include debug information in the LuaJIT bytecode
/path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.luac
Please refer to the official LuaJIT documentation for the `-b` option for more details:
Please refer to the official LuaJIT documentation on the `-b` option for more details:
<http://luajit.org/running.html#opt_b>
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:
Similarly, if using the standard Lua 5.1 interpreter with ngx_lua, Lua compatible bytecode files must be generated using the `luac` commandline utility as shown:
luac -o /path/to/output_file.luac /path/to/input_file.lua
@ -4508,7 +4508,7 @@ Unlike as with LuaJIT, debug information is included in standard Lua 5.1 bytecod
luac -s -o /path/to/output_file.luac /path/to/input_file.lua
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:
Attempts to load standard Lua 5.1 bytecode files into ngx_lua instances linked to LuaJIT 2.0 or vice versa, will result in an error message, such as that below, being logged into the Nginx `error.log` file:
[error] 13909#0: *1 failed to load Lua inlined code: bad byte-code header in /path/to/test_file.luac
@ -4519,21 +4519,16 @@ Loading bytecode files via the Lua primitives like `require` and `dofile` should
HTTP 1.0 support
================
The HTTP 1.0 protocol does not support chunked outputs and always requires an
explicit `Content-Length` header when the response body is non-empty in order to support the HTTP 1.0 keep-alive (as required by the ApacheBench (ab) tool). So when
an HTTP 1.0 request is present and the [lua_http10_buffering](http://wiki.nginx.org/HttpLuaModule#lua_http10_buffering) directive is turned `on`, this module will automatically buffer all the
outputs of user calls of [ngx.say](http://wiki.nginx.org/HttpLuaModule#ngx.say) and [ngx.print](http://wiki.nginx.org/HttpLuaModule#ngx.print) and
postpone sending response headers until it sees all the outputs in the response
body, and at that time ngx_lua can calculate the total length of the body and
construct a proper `Content-Length` header for the HTTP 1.0 client.
If the user Lua code sets the `Content-Length` response header itself, then the automatic buffering will be disabled even if the [lua_http10_buffering](http://wiki.nginx.org/HttpLuaModule#lua_http10_buffering) directive is turned `on`.
The HTTP 1.0 protocol does not support chunked output and requires an explicit `Content-Length` 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](http://wiki.nginx.org/HttpLuaModule#lua_http10_buffering) directive is turned `on`, ngx_lua will buffer the
output of [ngx.say](http://wiki.nginx.org/HttpLuaModule#ngx.say) and [ngx.print](http://wiki.nginx.org/HttpLuaModule#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 `Content-Length` header to return to the HTTP 1.0 client.
If the `Content-Length` response header is set in the running Lua code, however, this buffering will be disabled even if the [lua_http10_buffering](http://wiki.nginx.org/HttpLuaModule#lua_http10_buffering) directive is turned `on`.
For large streaming output responses, it is important to disable the [lua_http10_buffering](http://wiki.nginx.org/HttpLuaModule#lua_http10_buffering) directive to minimise memory usage.
Note that, common HTTP benchmark tools like `ab` and `http_load` always issue
HTTP 1.0 requests by default. To force `curl` to send HTTP 1.0 requests, use
the `-0` option.
Note that common HTTP benchmark tools such as `ab` and `http_load` issue HTTP 1.0 requests by default.
To force `curl` to send HTTP 1.0 requests, use the `-0` option.
Data Sharing within an Nginx Worker
===================================
@ -4573,7 +4568,7 @@ and all subsequent requests to the same nginx worker process will use the reload
module as well as the same copy of the data in it, until a `HUP` 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.
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:
1. Use the [ngx.shared.DICT](http://wiki.nginx.org/HttpLuaModule#ngx.shared.DICT) API provided by this module.
@ -4594,7 +4589,7 @@ This issue is due to limitations in the Nginx event model and only appears to af
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.
* 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.
* 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.
* 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
@ -4761,8 +4756,8 @@ Nginx Compatibility
===================
The module is compatible with the following versions of Nginx:
* 1.3.x (last tested: 1.3.6)
* 1.2.x (last tested: 1.2.3)
* 1.3.x (last tested: 1.3.7)
* 1.2.x (last tested: 1.2.4)
* 1.1.x (last tested: 1.1.5)
* 1.0.x (last tested: 1.0.15)
* 0.9.x (last tested: 0.9.4)
@ -4776,21 +4771,21 @@ The code repository of this project is hosted on github at [chaoslawful/lua-ngin
Installation
============
The [ngx_openresty bundle](http://openresty.org) can be used to install Nginx, `ngx_lua`, either one of the standard Lua 5.1 interpreter or LuaJIT 2.0, as well as a package of powerful companion Nginx modules. The basic installation step is a simple `./configure --with-luajit && make && make install`.
The [ngx_openresty bundle](http://openresty.org) can be used to install Nginx, ngx_lua, either one of the standard Lua 5.1 interpreter or LuaJIT 2.0, as well as a package of powerful companion Nginx modules. The basic installation step is a simple `./configure --with-luajit && make && make install`.
Alternatively, `ngx_lua` can be manually compiled into Nginx:
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). LuajIT can be downloaded from the [the LuaJIT project website](http://luajit.org/download.html) and Lua 5.1, from the [Lua project website](http://www.lua.org/). Some distribution package managers also distribute LuajIT and/or Lua.
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 `ngx_lua` [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))
Build the source with this module:
wget 'http://nginx.org/download/nginx-1.2.3.tar.gz'
tar -xzvf nginx-1.2.3.tar.gz
cd nginx-1.2.3/
wget 'http://nginx.org/download/nginx-1.2.4.tar.gz'
tar -xzvf nginx-1.2.4.tar.gz
cd nginx-1.2.4/
# tell nginx's build system where to find LuaJIT:
export LUAJIT_LIB=/path/to/luajit/lib
@ -4869,7 +4864,7 @@ Short Term
Longer Term
-----------
* add lightweight thread API (i.e., the `ngx.thread` API) as demonstrated in [this sample code](http://agentzh.org/misc/nginx/lua-thread2.lua).
* add Lua code automatic time slicing support by yielding and resuming the Lua VM actively via Lua's debug hooks.
* add automatic Lua code time slicing support by yielding and resuming the Lua VM actively via Lua's debug hooks.
* add `stat` mode similar to [mod_lua](http://httpd.apache.org/docs/2.3/mod/mod_lua.html).
Changes

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

@ -10,7 +10,7 @@ This module is under active development and is production ready.
= Version =
This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.7.0] released on 10 October 2012.
This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.7.1] released on 13 October 2012.
= Synopsis =
<geshi lang="nginx">
@ -235,7 +235,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
are to send a <code>HUP</code> signal or to restart Nginx.
The <code>ngx_lua</code> module does not currently support the <code>stat</code> mode available with the
The ngx_lua 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.
Disabling the Lua code cache is strongly
@ -546,7 +546,7 @@ Note that the [http://www.grid.net.ru/nginx/eval.en.html ngx_eval] module can be
}
</geshi>
can be implemented in <code>ngx_lua</code> as:
can be implemented in ngx_lua as:
<geshi lang="nginx">
location = /check-spam {
@ -645,7 +645,7 @@ Note that the [http://mdounin.ru/hg/ngx_http_auth_request_module/ ngx_auth_reque
}
</geshi>
can be implemented in <code>ngx_lua</code> as:
can be implemented in ngx_lua as:
<geshi lang="nginx">
location / {
@ -916,7 +916,7 @@ This directive was first introduced in the <code>v0.5.0rc31</code> release.
Determines whether to force the request body data to be read before running rewrite/access/access_by_lua* or not. The Nginx core does not read the client request body by default and if request body data is required, then this directive should be turned <code>on</code> or the [[#ngx.req.read_body|ngx.req.read_body]] function should be called within the Lua code.
To read the request body data within the [[HttpCoreModule#$request_body|$request_body]] variable,
[[HttpCoreModule#client_body_buffer_size|client_body_buffer_size]] must have the same value as [[HttpCoreModule#client_max_body_size|client_max_body_size]]. Because when the content length exceeds [[HttpCoreModule#client_body_buffer_size|client_body_buffer_size]] but less than [[HttpCoreModule#client_max_body_size|client_max_body_size]], Nginx will automatically buffer the data into a temporary file on the disk, which will lead to empty value in the [[HttpCoreModule#$request_body|$request_body]] variable.
[[HttpCoreModule#client_body_buffer_size|client_body_buffer_size]] must have the same value as [[HttpCoreModule#client_max_body_size|client_max_body_size]]. Because when the content length exceeds [[HttpCoreModule#client_body_buffer_size|client_body_buffer_size]] but less than [[HttpCoreModule#client_max_body_size|client_max_body_size]], Nginx will buffer the data into a temporary file on the disk, which will lead to empty value in the [[HttpCoreModule#$request_body|$request_body]] variable.
If the current location includes [[#rewrite_by_lua|rewrite_by_lua]] or [[#rewrite_by_lua_file|rewrite_by_lua_file]] directives,
then the request body will be read just before the [[#rewrite_by_lua|rewrite_by_lua]] or [[#rewrite_by_lua_file|rewrite_by_lua_file]] code is run (and also at the
@ -1033,7 +1033,7 @@ Specifies the size limit (in terms of connection count) for every cosocket conne
Default to 30 connections for every pool.
When the connection pool is exceeding the size limit, the least recently used (idle) connection already in the pool will be closed automatically to make room for the current connection.
When the connection pool exceeds the available size limit, the least recently used (idle) connection already in the pool will be closed to make room for the current connection.
Note that the cosocket connection pool is per nginx worker process rather than per nginx server instance, so so size limit specified here also applies to every single nginx worker process.
@ -1047,7 +1047,7 @@ This directive was first introduced in the <code>v0.5.0rc1</code> release.
'''context:''' ''http, server, location''
This directive controls the default maximal idle time of the connections in the cosocket built-in connection pool. When this timeout reaches, idle connections will be closed automatically and removed from the pool. This setting can be overridden by cosocket objects' [[#tcpsock:setkeepalive|setkeepalive]] method.
This directive controls the default maximal idle time of the connections in the cosocket built-in connection pool. When this timeout reaches, idle connections will be closed and removed from the pool. This setting can be overridden by cosocket objects' [[#tcpsock:setkeepalive|setkeepalive]] method.
The <code><time></code> argument can be an integer, with an optional time unit, like <code>s</code> (second), <code>ms</code> (millisecond), <code>m</code> (minute). The default time unit is <code>s</code>, i.e., "second". The default setting is <code>60s</code>.
@ -1061,7 +1061,7 @@ This directive was first introduced in the <code>v0.5.0rc1</code> release.
'''context:''' ''http, server, location''
This directive can be used to toggle the automatic error logging when a failure occurs for the TCP or UDP cosockets. If you are already doing proper error handling and logging in your Lua code, then it is recommended to turn this directive off to prevent data flushing in your nginx error log files (which is usually rather expensive).
This directive can be used to toggle error logging when a failure occurs for the TCP or UDP cosockets. If you are already doing proper error handling and logging in your Lua code, then it is recommended to turn this directive off to prevent data flushing in your nginx error log files (which is usually rather expensive).
This directive was first introduced in the <code>v0.5.13</code> release.
@ -1073,7 +1073,7 @@ This directive was first introduced in the <code>v0.5.13</code> release.
'''context:''' ''http, server, location, location-if''
Enables or disables the automatic response caching for HTTP 1.0 (or older) requests. This buffering mechanism is mainly used for HTTP 1.0 keep-alive which replies on a proper <code>Content-Length</code> response header.
Enables or disables response caching for HTTP 1.0 (or older) requests. This buffering mechanism is mainly used for HTTP 1.0 keep-alive which replies on a proper <code>Content-Length</code> response header.
If the Lua code explicitly sets a <code>Content-Length</code> response header before sending the headers (either explicitly via [[#ngx.send_headers|ngx.send_headers]] or implicitly via the first [[#ngx.say|ngx.say]] or [[#ngx.print|ngx.print]] call).
@ -1111,7 +1111,7 @@ This directive was first introduced in the <code>v0.5.0rc32</code> release.
== 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.
The API is exposed to Lua in the form of two standard packages <code>ngx</code> and <code>ndk</code>. These packages are in the default global scope within <code>ngx_lua</code> and are always available within <code>ngx_lua</code> directives.
The API is exposed to Lua in the form of two standard packages <code>ngx</code> and <code>ndk</code>. These packages are in the default global scope within ngx_lua and are always available within ngx_lua directives.
The packages can be introduced into external Lua modules by using the [http://www.lua.org/manual/5.1/manual.html#pdf-package.seeall package.seeall] option:
@ -1418,7 +1418,7 @@ Overriding <code>ngx.ctx</code> with a new Lua table is also supported, for exam
Issue a synchronous but still non-blocking ''Nginx Subrequest'' using <code>uri</code>.
Nginx's subrequests provide a powerful way to make non-blocking internal requests to other locations configured with disk file directory or ''any'' other nginx C modules like <code>ngx_proxy</code>, <code>ngx_fastcgi</code>, <code>ngx_memc</code>,
<code>ngx_postgres</code>, <code>ngx_drizzle</code>, and even <code>ngx_lua</code> itself and etc etc etc.
<code>ngx_postgres</code>, <code>ngx_drizzle</code>, and even ngx_lua itself and etc etc etc.
Also note that subrequests just mimic the HTTP interface but there is ''no'' extra HTTP/TCP traffic ''nor'' IPC involved. Everything works internally, efficiently, on the C level.
@ -1501,8 +1501,8 @@ is equivalent to
ngx.location.capture('/foo?a=1&b=3&c=%3a')
</geshi>
that is, this method will automatically escape argument keys and values according to URI rules and
concatenating them together into a complete query string. The format for the Lua table passed as the <code>args</code> argument is identical to the format used in the [[#ngx.encode_args|ngx.encode_args]] method.
that is, this method will escape argument keys and values according to URI rules and
concatenate them together into a complete query string. The format for the Lua table passed as the <code>args</code> argument is identical to the format used in the [[#ngx.encode_args|ngx.encode_args]] method.
The <code>args</code> option can also take plain query strings:
@ -1975,7 +1975,7 @@ or a Lua table holding the query arguments' key-value pairs, as in
ngx.req.set_uri_args({ a = 3, b = "hello world" })
</geshi>
where in the latter case, this method will automatically escape argument keys and values according to the URI escaping rule.
where in the latter case, this method will escape argument keys and values according to the URI escaping rule.
Multi-value arguments are also supported:
@ -2020,7 +2020,7 @@ Then <code>GET /test?foo=bar&bar=baz&bar=blah</code> will yield the response bod
Multiple occurrences of an argument key will result in a table value holding all the values for that key in order.
Keys and values are automatically unescaped according to URI escaping rules. In the settings above, <code>GET /test?a%20b=1%61+2</code> will yield:
Keys and values are unescaped according to URI escaping rules. In the settings above, <code>GET /test?a%20b=1%61+2</code> will yield:
<geshi lang="bash">
a b: 1a 2
@ -2112,7 +2112,7 @@ will yield the response body like
Multiple occurrences of an argument key will result in a table value holding all of the values for that key in order.
Keys and values will be automatically unescaped according to URI escaping rules.
Keys and values will be unescaped according to URI escaping rules.
With the settings above,
@ -2213,7 +2213,7 @@ Removing the <code>max_headers</code> cap is strongly discouraged.
Since the <code>0.6.9</code> release, all the header names in the Lua table returned are converted to the pure lower-case form by default, unless the <code>raw</code> argument is set to <code>true</code> (default to <code>false</code>).
Also, by default, an <code>__index</code> metamethod is added automatically to the resulting Lua table that will normalize the keys to the pure lower-case form with all underscores converted to dashes in case of a lookup miss. For example, if a request header <code>My-Foo-Header</code> is present, then the following invocations will all pick up the value of this header correctly:
Also, by default, an <code>__index</code> metamethod is added to the resulting Lua table and will normalize the keys to a pure lowercase form with all underscores converted to dashes in case of a lookup miss. For example, if a request header <code>My-Foo-Header</code> is present, then the following invocations will all pick up the value of this header correctly:
<geshi lang="lua">
ngx.say(headers.my_foo_header)
@ -2230,7 +2230,7 @@ The <code>__index</code> metamethod will not be added when the <code>raw</code>
Set the current request's request header named <code>header_name</code> to value <code>header_value</code>, overriding any existing ones.
By default, all the subrequests subsequently initiated by [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]] will automatically inherit the new header.
By default, all the subrequests subsequently initiated by [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]] will inherit the new header.
Here is an example of setting the <code>Content-Length</code> header:
@ -2320,7 +2320,7 @@ This function returns <code>nil</code> if
# the request body has been read into disk temporary files,
# or the request body has zero size.
If the request body has not been read yet, call [[#ngx.req.read_body|ngx.req.read_body]] first (or turned on [[#lua_need_request_body|lua_need_request_body]] to force this module to read the request body automatically, but this is not recommended).
If the request body has not been read yet, call [[#ngx.req.read_body|ngx.req.read_body]] first (or turned on [[#lua_need_request_body|lua_need_request_body]] to force this module to read the request body. This is not recommended however).
If the request body has been read into disk files, try calling the [[#ngx.req.get_body_file|ngx.req.get_body_file]] function instead.
@ -2339,9 +2339,9 @@ See also [[#ngx.req.get_body_file|ngx.req.get_body_file]].
Retrieves the file name for the in-file request body data. Returns <code>nil</code> if the request body has not been read or has been read into memory.
The returned file is read only and is usually cleaned up automatically by Nginx's memory pool. It should not be manually modified, renamed, or removed in Lua code.
The returned file is read only and is usually cleaned up by Nginx's memory pool. It should not be manually modified, renamed, or removed in Lua code.
If the request body has not been read yet, call [[#ngx.req.read_body|ngx.req.read_body]] first (or turned on [[#lua_need_request_body|lua_need_request_body]] to force this module to read the request body automatically, but this is not recommended).
If the request body has not been read yet, call [[#ngx.req.read_body|ngx.req.read_body]] first (or turned on [[#lua_need_request_body|lua_need_request_body]] to force this module to read the request body. This is not recommended however).
If the request body has been read into memory, try calling the [[#ngx.req.get_body_data|ngx.req.get_body_data]] function instead.
@ -2375,7 +2375,7 @@ See also [[#ngx.req.set_body_file|ngx.req.set_body_file]].
Set the current request's request body using the in-file data specified by the <code>file_name</code> argument.
If the optional <code>auto_clean</code> argument is given a <code>true</code> value, then this file will be automatically removed at request completion or the next time this function or [[#ngx.req.set_body_data|ngx.req.set_body_data]] are called in the same request. The <code>auto_clean</code> is default to <code>false</code>.
If the optional <code>auto_clean</code> argument is given a <code>true</code> value, then this file will be removed at request completion or the next time this function or [[#ngx.req.set_body_data|ngx.req.set_body_data]] are called in the same request. The <code>auto_clean</code> is default to <code>false</code>.
Please ensure that the file specified by the <code>file_name</code> argument exists and is readable by an Nginx worker process by setting its permission properly to avoid Lua exception errors.
@ -2397,7 +2397,7 @@ Creates a new blank request body for the current request and inializes the buffe
If the <code>buffer_size</code> argument is specified, then its value will be used for the size of the memory buffer for body writing with [[#ngx.req.append_body|ngx.req.append_body]]. If the argument is omitted, then the value specified by the standard [[HttpCoreModule#client_body_buffer_size|client_body_buffer_size]] directive will be used instead.
When the data can no longer be hold in the memory buffer for the request body, then the data will automatically be flushed onto a temporary file just like the standard request body reader in the Nginx core.
When the data can no longer be hold in the memory buffer for the request body, then the data will be flushed onto a temporary file just like the standard request body reader in the Nginx core.
It is important to always call the [[#ngx.req.finish_body|ngx.req.finish_body]] after all the data has been appended onto the current request body. Also, when this function is used together with [[#ngx.req.socket|ngx.req.socket]], it is required to call [[#ngx.req.socket|ngx.req.socket]] ''before'' this function, or you will get the "request body already exists" error message.
@ -2422,7 +2422,7 @@ This function was first introduced in the <code>v0.5.11</code> release.
Append new data chunk specified by the <code>data_chunk</code> argument onto the existing request body created by the [[#ngx.req.init_body|ngx.req.init_body]] call.
When the data can no longer be hold in the memory buffer for the request body, then the data will automatically be flushed onto a temporary file just like the standard request body reader in the Nginx core.
When the data can no longer be hold in the memory buffer for the request body, then the data will be flushed onto a temporary file just like the standard request body reader in the Nginx core.
It is important to always call the [[#ngx.req.finish_body|ngx.req.finish_body]] after all the data has been appended onto the current request body.
@ -2456,7 +2456,7 @@ In case of error, <code>nil</code> will be returned as well as a string describi
The socket object returned by this method is usually used to read the current request's body in a streaming fashion. Do not turn on the [[#lua_need_request_body|lua_need_request_body]] directive, and do not mix this call with [[#ngx.req.read_body|ngx.req.read_body]] and [[#ngx.req.discard_body|ngx.req.discard_body]].
If there is any request body data that has been pre-read into the Nginx core's request header buffer, the resulting cosocket object will take care of that automatically. So there will not be any data loss due to potential body data pre-reading.
If any request body data has been pre-read into the Nginx core request header buffer, the resulting cosocket object will take care of this to avoid potential data loss resulting from such pre-reading.
This function was first introduced in the <code>v0.5.0rc1</code> release.
@ -2500,7 +2500,7 @@ The optional second <code>args</code> can be used to specify extra URI query arg
ngx.exec("/foo", "a=3&b=hello%20world")
</geshi>
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.
Alternatively, a Lua table can be passed for the <code>args</code> argument for ngx_lua to carry out URI escaping and string concatenation.
<geshi lang="lua">
ngx.exec("/foo", { a = 3, b = "hello world" })
@ -2592,7 +2592,7 @@ It is strongly recommended to combine the <code>return</code> statement with thi
Explicitly send out the response headers.
Note that there is normally no need to manually send out response headers as <code>ngx_lua</code> will automatically send headers out
Note that there is normally no need to manually send out response headers as ngx_lua will automatically send headers out
before content is output with [[#ngx.say|ngx.say]] or [[#ngx.print|ngx.print]] or when [[#content_by_lua|content_by_lua]] exits normally.
== ngx.headers_sent ==
@ -2600,9 +2600,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*''
Returns <code>true</code> if the response headers have been sent (by <code>ngx_lua</code>), and <code>false</code> otherwise.
Returns <code>true</code> if the response headers have been sent (by ngx_lua), and <code>false</code> otherwise.
This API was first introduced in <code>ngx_lua</code> v0.3.1rc6.
This API was first introduced in ngx_lua v0.3.1rc6.
== ngx.print ==
'''syntax:''' ''ngx.print(...)''
@ -3066,7 +3066,7 @@ Returns <code>true</code> if the current request is an nginx subrequest, or <cod
'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
Matches the <code>subject</code> string using the Perl-compatible regular expression <code>regex</code> with the optional <code>options</code>.
Matches the <code>subject</code> string using the Perl compatible regular expression <code>regex</code> with the optional <code>options</code>.
Only the first occurrence of the match is returned, or <code>nil</code> if no match is found. In case of fatal errors, like seeing bad <code>UTF-8</code> sequences in <code>UTF-8</code> mode, a Lua exception will be raised.
@ -3205,7 +3205,7 @@ This feature was first introduced in the <code>v0.2.1rc12</code> release.
'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
Substitutes the first match of the Perl-compatible regular expression <code>regex</code> on the <code>subject</code> argument string with the string or function argument <code>replace</code>. The optional <code>options</code> argument has exactly the same meaning as in [[#ngx.re.match|ngx.re.match]].
Substitutes the first match of the Perl compatible regular expression <code>regex</code> on the <code>subject</code> argument string with the string or function argument <code>replace</code>. The optional <code>options</code> argument has exactly the same meaning as in [[#ngx.re.match|ngx.re.match]].
This method returns the resulting new string as well as the number of successful substitutions, or throw out a Lua exception when an error occurred (syntax errors in the <code><replace></code> string argument, for example).
@ -3577,7 +3577,7 @@ Sends data on the current UDP or datagram unix domain socket object.
In case of success, it returns <code>1</code>. Otherwise, it returns <code>nil</code> and a string describing the error.
The input argument <code>data</code> can either be a Lua string or a (nested) Lua table holding string fragments. In case of table arguments, this method will automatically copy all the string elements piece by piece to the underlying Nginx socket send buffers, which is usually optimal than doing string concatenation operations on the Lua land.
The input argument <code>data</code> can either be a Lua string or a (nested) Lua table holding string fragments. In case of table arguments, this method will copy all the string elements piece by piece to the underlying Nginx socket send buffers, which is usually optimal than doing string concatenation operations on the Lua land.
This feature was first introduced in the <code>v0.5.7</code> release.
@ -3619,7 +3619,7 @@ This feature was first introduced in the <code>v0.5.7</code> release.
Closes the current UDP or datagram unix domain socket. It returns the <code>1</code> in case of success and returns <code>nil</code> with a string describing the error otherwise.
For socket objects that have not invoked this method, they (and their connections) will be automatically closed when the socket object is released by the Lua GC (Garbage Collector) or the current client HTTP request finishes processing.
Socket objects that have not invoked this method (and associated connections) will be closed when the socket object is released by the Lua GC (Garbage Collector) or the current client HTTP request finishes processing.
This feature was first introduced in the <code>v0.5.7</code> release.
@ -3725,7 +3725,7 @@ Calling this method on an already connected socket object will cause the origina
An optional Lua table can be specified as the last argument to this method to specify various connect options:
* <code>pool</code>
: specify a custom name for the connection pool being used. If omitted, then the connection pool name will be automatically generated from the string template <code>"<host>:<port>"</code> or <code>"<unix-socket-path>"</code>.
: specify a custom name for the connection pool being used. If omitted, then the connection pool name will be generated from the string template <code>"<host>:<port>"</code> or <code>"<unix-socket-path>"</code>.
The support for the options table argument was first introduced in the <code>v0.5.7</code> release.
@ -3742,7 +3742,7 @@ This method is a synchronous operation that will not return until ''all'' the da
In case of success, it returns the total number of bytes that have been sent. Otherwise, it returns <code>nil</code> and a string describing the error.
The input argument <code>data</code> can either be a Lua string or a (nested) Lua table holding string fragments. In case of table arguments, this method will automatically copy all the string elements piece by piece to the underlying Nginx socket send buffers, which is usually optimal than doing string concatenation operations on the Lua land.
The input argument <code>data</code> can either be a Lua string or a (nested) Lua table holding string fragments. In case of table arguments, this method will copy all the string elements piece by piece to the underlying Nginx socket send buffers, which is usually optimal than doing string concatenation operations on the Lua land.
Timeout for the sending operation is controlled by the [[#lua_socket_send_timeout|lua_socket_send_timeout]] config directive and the [[#tcpsock:settimeout|settimeout]] method. And the latter takes priority. For example:
@ -3817,7 +3817,7 @@ In case of error, the iterator function will return <code>nil</code> along with
The iterator function can be called multiple times and can be mixed safely with other cosocket method calls or other iterator function calls.
The iterator function behaves differently (i.e., like a real iterator) when it is called with a <code>size</code> argument. That is, it will read that <code>size</code> of data on each invocation and will return <code>nil</code> at the last invocation (either sees the boundary pattern or meets an error). For the last successful invocation of the iterator function, the <code>err</code> return value will be <code>nil</code> too. The iterator function will automatically reset after its last successful invocation that returns <code>nil</code> data and <code>nil</code> error. Consider the following example:
The iterator function behaves differently (i.e., like a real iterator) when it is called with a <code>size</code> argument. That is, it will read that <code>size</code> of data on each invocation and will return <code>nil</code> at the last invocation (either sees the boundary pattern or meets an error). For the last successful invocation of the iterator function, the <code>err</code> return value will be <code>nil</code> too. The iterator function will be reset after the last successful invocation that returns <code>nil</code> data and <code>nil</code> error. Consider the following example:
<geshi lang="lua">
local reader = sock:receiveuntil("\r\n--abcedhb")
@ -3890,9 +3890,9 @@ This method was first introduced in the <code>v0.5.0rc1</code> release.
Closes the current TCP or stream unix domain socket. It returns the <code>1</code> in case of success and returns <code>nil</code> with a string describing the error otherwise.
For socket objects that have invoked the [[#tcpsock:setkeepalive|setkeepalive]] method, there is no need to call this method on it because the socket object is already closed (and the current connection is saved into the built-in connection pool).
Note that there is no need to call this method on socket objects that have invoked the [[#tcpsock:setkeepalive|setkeepalive]] method because the socket object is already closed (and the current connection is saved into the built-in connection pool).
For socket objects that have not invoked [[#tcpsock:setkeepalive|setkeepalive]] nor this method, they (and their connections) will be automatically closed when the socket object is released by the Lua GC (Garbage Collector) or the current client HTTP request finishes processing.
Socket objects that have not invoked this method (and associated connections) will be closed when the socket object is released by the Lua GC (Garbage Collector) or the current client HTTP request finishes processing.
This feature was first introduced in the <code>v0.5.0rc1</code> release.
@ -3929,7 +3929,7 @@ The first optional argument, <code>timeout</code>, can be used to specify the ma
The second optional argument, <code>size</code>, can be used to specify the maximal number of connections allowed in the connection pool for the current server (i.e., the current host-port pair or the unix domain socket file path). Note that the size of the connection pool cannot be changed once the pool is created. When this argument is omitted, the default setting in the [[#lua_socket_pool_size|lua_socket_pool_size]] config directive will be used.
When the connection pool is exceeding the size limit, the least recently used (idle) connection already in the pool will be closed automatically to make room for the current connection.
When the connection pool exceeds the available size limit, the least recently used (idle) connection already in the pool will be closed to make room for the current connection.
Note that the cosocket connection pool is per Nginx worker process rather than per Nginx server instance, so the size limit specified here also applies to every single Nginx worker process.
@ -4007,7 +4007,7 @@ This API was first introduced in the <code>v0.5.10</code> release.
Creates a user Lua coroutines with a Lua function, and returns a coroutine object.
Just behaves like the standard Lua [http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.create coroutine.create] API, but works in the context of the Lua coroutines created automatically by this Nginx module.
Similar to the standard Lua [http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.create coroutine.create] API, but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the <code>v0.6.0</code> release.
@ -4018,7 +4018,7 @@ This API was first introduced in the <code>v0.6.0</code> release.
Resumes the executation of a user Lua coroutine object previously yielded or just created.
Just behaves like the standard Lua [http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.resume coroutine.resume] API, but works in the context of the Lua coroutines created automatically by this Nginx module.
Similar to the standard Lua [http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.resume coroutine.resume] API, but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the <code>v0.6.0</code> release.
@ -4029,7 +4029,7 @@ This API was first introduced in the <code>v0.6.0</code> release.
Yields the executation of the current user Lua coroutine.
Just behaves like the standard Lua [http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.yield coroutine.yield] API, but works in the context of the Lua coroutines created automatically by this Nginx module.
Similar to the standard Lua [http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.yield coroutine.yield] API, but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the <code>v0.6.0</code> release.
@ -4038,7 +4038,7 @@ This API was first introduced in the <code>v0.6.0</code> release.
'''context:''' ''rewrite_by_lua*, access_by_lua*, content_by_lua*''
Just behaves like the standard Lua [http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.wrap coroutine.wrap] API, but works in the context of the Lua coroutines created automatically by this Nginx module.
Similar to the standard Lua [http://www.lua.org/manual/5.1/manual.html#pdf-coroutine.wrap coroutine.wrap] API, but works in the context of the Lua coroutines created by ngx_lua.
This API was first introduced in the <code>v0.6.0</code> release.
@ -4067,13 +4067,13 @@ This API was first enabled in the <code>v0.6.0</code> release.
Spawns a new user "light thread" with the Lua function <code>func</code> as well as those optional arguments <code>arg1</code>, <code>arg2</code>, and etc. Returns a Lua thread (or Lua coroutine) object represents this "light thread".
"Light threads" are just a special kind of Lua coroutines that are scheduled automatically by the <code>ngx_lua</code> module.
"Light threads" are just a special kind of Lua coroutines that are scheduled by the ngx_lua module.
Before <code>ngx.thread.spawn</code> returns, the <code>func</code> will be called with those optional arguments until it returns, aborts with an error, or gets yielded automatically due to I/O operations via the [[#Nginx API for Lua|Nginx API for Lua]] (like [[#tcpsock:receive|tcpsock:receive]]).
Before <code>ngx.thread.spawn</code> returns, the <code>func</code> will be called with those optional arguments until it returns, aborts with an error, or gets yielded due to I/O operations via the [[#Nginx API for Lua|Nginx API for Lua]] (like [[#tcpsock:receive|tcpsock:receive]]).
After <code>ngx.thread.spawn</code> returns, the newly-created "light thread" will keep running asynchronously usually at various I/O events.
All the Lua code chunks running by [[#rewrite_by_lua|rewrite_by_lua]], [[#access_by_lua|access_by_lua]], and [[#content_by_lua|content_by_lua]] are in a boilerplate "light thread" created automatically by <code>ngx_lua</code>. Such boilerplate "light thread" are also called "entry threads".
All the Lua code chunks running by [[#rewrite_by_lua|rewrite_by_lua]], [[#access_by_lua|access_by_lua]], and [[#content_by_lua|content_by_lua]] are in a boilerplate "light thread" created automatically by ngx_lua. Such boilerplate "light thread" are also called "entry threads".
By default, the corresponding Nginx handler (e.g., [[#rewrite_by_lua|rewrite_by_lua]] handler) will not terminate until
# both the "entry thread" and all the user "light threads" terminates,
@ -4084,12 +4084,12 @@ When the user "light thread" terminates with a Lua error, however, it will not a
Due to the limitation in the Nginx subrequest model, it is not allowed to abort a running Nginx subrequest in general. So it is also prohibited to abort a running "light thread" that is pending on one ore more Nginx subrequests. You must call [[#ngx.thread.wait|ngx.thread.wait]] to wait for those "light thread" to terminate before quitting the "world".
The "light threads" are not scheduled in a pre-emptive way. In other words, no automatic time-slicing is performed. A "light thread" will keep running exclusively on the CPU until
The "light threads" are not scheduled in a pre-emptive way. In other words, no time-slicing is performed automatically. A "light thread" will keep running exclusively on the CPU until
# a (nonblocking) I/O operation cannot be completed in a single run,
# it calls [[#coroutine.yield|coroutine.yield]] to actively give up execution, or
# it is aborted by a Lua error or an invocation of [[#ngx.exit|ngx.exit]], [[#ngx.exec|ngx.exec]], [[#ngx.redirect|ngx.redirect]], or [[#ngx.req.set_uri|ngx.req.set_uri(uri, true)]].
For the first two cases, the "light thread" will usually be resumed later by the <code>ngx_lua</code> scheduler unless a "stop-the-world" event happens.
For the first two cases, the "light thread" will usually be resumed later by the ngx_lua scheduler unless a "stop-the-world" event happens.
User "light threads" can create "light threads" themselves and normal user coroutiens created by [[#coroutine.create|coroutine.create]] can also create "light threads". The coroutine (be it a normal Lua coroutine or a "light thread") that directly spawns the "light thread" is called the "parent coroutine" for the "light thread" newly spawned.
@ -4329,7 +4329,7 @@ This feature requires the [https://github.com/simpl/ngx_devel_kit ngx_devel_kit]
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 raw bytecode files directly.
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:
Please note that the bytecode format used by LuaJIT 2.0 is not compatible with that used by the standard Lua 5.1 interpreter. So if using LuaJIT 2.0 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
@ -4341,11 +4341,11 @@ The <code>-bg</code> option can be used to include debug information in the LuaJ
/path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.luac
</geshi>
Please refer to the official LuaJIT documentation for the <code>-b</code> option for more details:
Please refer to the official LuaJIT documentation on the <code>-b</code> option for more details:
http://luajit.org/running.html#opt_b
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:
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
@ -4357,7 +4357,7 @@ Unlike as with LuaJIT, debug information is included in standard Lua 5.1 bytecod
luac -s -o /path/to/output_file.luac /path/to/input_file.lua
</geshi>
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:
Attempts to load standard Lua 5.1 bytecode files into ngx_lua instances linked to LuaJIT 2.0 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
@ -4367,21 +4367,16 @@ Loading bytecode files via the Lua primitives like <code>require</code> and <cod
= HTTP 1.0 support =
The HTTP 1.0 protocol does not support chunked outputs and always requires an
explicit <code>Content-Length</code> header when the response body is non-empty in order to support the HTTP 1.0 keep-alive (as required by the ApacheBench (ab) tool). So when
an HTTP 1.0 request is present and the [[#lua_http10_buffering|lua_http10_buffering]] directive is turned <code>on</code>, this module will automatically buffer all the
outputs of user calls of [[#ngx.say|ngx.say]] and [[#ngx.print|ngx.print]] and
postpone sending response headers until it sees all the outputs in the response
body, and at that time ngx_lua can calculate the total length of the body and
construct a proper <code>Content-Length</code> header for the HTTP 1.0 client.
If the user Lua code sets the <code>Content-Length</code> response header itself, then the automatic buffering will be disabled even if the [[#lua_http10_buffering|lua_http10_buffering]] directive is turned <code>on</code>.
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 like <code>ab</code> and <code>http_load</code> always issue
HTTP 1.0 requests by default. To force <code>curl</code> to send HTTP 1.0 requests, use
the <code>-0</code> option.
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.
= Data Sharing within an Nginx Worker =
@ -4420,7 +4415,7 @@ and all subsequent requests to the same nginx worker process will use the reload
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.
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.
@ -4438,7 +4433,7 @@ This issue is due to limitations in the Nginx event model and only appears to af
== 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.
* 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.
* 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 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()] 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 ==
@ -4600,8 +4595,8 @@ On a ThinkPad T400 2.80 GHz laptop, the Hello World example readily achieves 28k
= Nginx Compatibility =
The module is compatible with the following versions of Nginx:
* 1.3.x (last tested: 1.3.6)
* 1.2.x (last tested: 1.2.3)
* 1.3.x (last tested: 1.3.7)
* 1.2.x (last tested: 1.2.4)
* 1.1.x (last tested: 1.1.5)
* 1.0.x (last tested: 1.0.15)
* 0.9.x (last tested: 0.9.4)
@ -4613,21 +4608,21 @@ The code repository of this project is hosted on github at [http://github.com/ch
= Installation =
The [http://openresty.org ngx_openresty bundle] can be used to install Nginx, <code>ngx_lua</code>, either one of the standard Lua 5.1 interpreter or LuaJIT 2.0, as well as a package of powerful companion Nginx modules. The basic installation step is a simple <code>./configure --with-luajit && make && make install</code>.
The [http://openresty.org ngx_openresty bundle] can be used to install Nginx, ngx_lua, either one of the standard Lua 5.1 interpreter or LuaJIT 2.0, as well as a package of powerful companion Nginx modules. The basic installation step is a simple <code>./configure --with-luajit && make && make install</code>.
Alternatively, <code>ngx_lua</code> can be manually compiled into Nginx:
Alternatively, ngx_lua can be manually compiled into Nginx:
# Install LuaJIT 2.0 (Recommended) or Lua 5.1 (Lua 5.2 is ''not'' supported yet). LuajIT can be downloaded from the [http://luajit.org/download.html the LuaJIT project website] and Lua 5.1, from the [http://www.lua.org/ Lua project website]. Some distribution package managers also distribute LuajIT and/or Lua.
# 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 <code>ngx_lua</code> [http://github.com/chaoslawful/lua-nginx-module/tags HERE].
# Download the latest version of ngx_lua [http://github.com/chaoslawful/lua-nginx-module/tags HERE].
# Download the latest version of Nginx [http://nginx.org/ HERE] (See [[#Nginx Compatibility|Nginx Compatibility]])
Build the source with this module:
<geshi lang="bash">
wget 'http://nginx.org/download/nginx-1.2.3.tar.gz'
tar -xzvf nginx-1.2.3.tar.gz
cd nginx-1.2.3/
wget 'http://nginx.org/download/nginx-1.2.4.tar.gz'
tar -xzvf nginx-1.2.4.tar.gz
cd nginx-1.2.4/
# tell nginx's build system where to find LuaJIT:
export LUAJIT_LIB=/path/to/luajit/lib
@ -4698,7 +4693,7 @@ Please submit bug reports, wishlists, or patches by
== Longer Term ==
* add lightweight thread API (i.e., the <code>ngx.thread</code> API) as demonstrated in [http://agentzh.org/misc/nginx/lua-thread2.lua this sample code].
* add Lua code automatic time slicing support by yielding and resuming the Lua VM actively via Lua's debug hooks.
* 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 [http://httpd.apache.org/docs/2.3/mod/mod_lua.html mod_lua].
= Changes =