diff --git a/.travis.yml b/.travis.yml index 0e516a9c4b..39f9278b80 100644 --- a/.travis.yml +++ b/.travis.yml @@ -12,7 +12,6 @@ compiler: addons: apt: packages: - - mysql-server - axel - cpanminus - libtest-base-perl @@ -24,7 +23,6 @@ addons: - libgd-dev cache: - apt: true directories: - download-cache @@ -36,14 +34,14 @@ env: - LUAJIT_LIB=$LUAJIT_PREFIX/lib - LUAJIT_INC=$LUAJIT_PREFIX/include/luajit-2.1 - LUA_INCLUDE_DIR=$LUAJIT_INC - - PCRE_VER=8.33 + - PCRE_VER=8.40 - PCRE_PREFIX=/opt/pcre - PCRE_LIB=$PCRE_PREFIX/lib - PCRE_INC=$PCRE_PREFIX/include - OPENSSL_PREFIX=/opt/ssl - OPENSSL_LIB=$OPENSSL_PREFIX/lib - OPENSSL_INC=$OPENSSL_PREFIX/include - - OPENSSL_VER=1.0.2h + - OPENSSL_VER=1.0.2k - LIBDRIZZLE_PREFIX=/opt/drizzle - LIBDRIZZLE_INC=$LIBDRIZZLE_PREFIX/include/libdrizzle-1.0 - LIBDRIZZLE_LIB=$LIBDRIZZLE_PREFIX/lib @@ -51,23 +49,25 @@ env: - DRIZZLE_VER=2011.07.21 - TEST_NGINX_SLEEP=0.006 matrix: - - NGINX_VERSION=1.9.15 -# - NGINX_VERSION=1.10.0 + - NGINX_VERSION=1.11.2 services: - memcache - redis-server + - mysql + +before_install: + - '! grep -n -P ''(?<=.{80}).+'' --color `find src -name ''*.c''` `find . -name ''*.h''` || (echo "ERROR: Found C source lines exceeding 80 columns." > /dev/stderr; exit 1)' + - '! grep -n -P ''\t+'' --color `find src -name ''*.c''` `find . -name ''*.h''` || (echo "ERROR: Cannot use tabs." > /dev/stderr; exit 1)' install: - - if [ ! -d download-cache ]; then mkdir download-cache; fi - - rm -f download-cache/drizzle7-$DRIZZLE_VER.tar.gz # alas, we may end up with corrupted drizzle tarball stuck in the download-cache/ forever. - - if [ ! -f download-cache/drizzle7-$DRIZZLE_VER.tar.gz ]; then wget -O download-cache/drizzle7-$DRIZZLE_VER.tar.gz http://openresty.org/download/drizzle7-$DRIZZLE_VER.tar.gz; fi - - if [ ! -f download-cache/pcre-$PCRE_VER.tar.gz ]; then wget -O download-cache/pcre-$PCRE_VER.tar.gz http://ftp.cs.stanford.edu/pub/exim/pcre/pcre-$PCRE_VER.tar.gz; fi - - if [ ! -f download-cache/openssl-$OPENSSL_VER.tar.gz ]; then wget -O download-cache/openssl-$OPENSSL_VER.tar.gz https://www.openssl.org/source/openssl-$OPENSSL_VER.tar.gz; fi + - if [ ! -f download-cache/drizzle7-$DRIZZLE_VER.tar.gz ]; then wget -P download-cache http://openresty.org/download/drizzle7-$DRIZZLE_VER.tar.gz; fi + - if [ ! -f download-cache/pcre-$PCRE_VER.tar.gz ]; then wget -P download-cache http://ftp.cs.stanford.edu/pub/exim/pcre/pcre-$PCRE_VER.tar.gz; fi + - if [ ! -f download-cache/openssl-$OPENSSL_VER.tar.gz ]; then wget -P download-cache https://www.openssl.org/source/openssl-$OPENSSL_VER.tar.gz; fi - git clone https://github.com/openresty/test-nginx.git - git clone https://github.com/openresty/openresty.git ../openresty - git clone https://github.com/openresty/no-pool-nginx.git ../no-pool-nginx - - git clone https://github.com/openresty/nginx-devel-utils.git + - git clone https://github.com/openresty/openresty-devel-utils.git - git clone https://github.com/openresty/mockeagain.git - git clone https://github.com/openresty/lua-cjson.git - git clone https://github.com/openresty/lua-upstream-nginx-module.git ../lua-upstream-nginx-module @@ -82,6 +82,8 @@ install: - git clone https://github.com/openresty/rds-json-nginx-module.git ../rds-json-nginx-module - git clone https://github.com/openresty/srcache-nginx-module.git ../srcache-nginx-module - git clone https://github.com/openresty/redis2-nginx-module.git ../redis2-nginx-module + - git clone https://github.com/openresty/lua-resty-core.git ../lua-resty-core + - git clone https://github.com/openresty/lua-resty-lrucache.git ../lua-resty-lrucache - git clone -b v2.1-agentzh https://github.com/openresty/luajit2.git before_script: @@ -89,7 +91,7 @@ before_script: script: - cd luajit2/ - - make -j$JOBS CCDEBUG=-g Q= PREFIX=$LUAJIT_PREFIX CC=$CC XCFLAGS='-DLUA_USE_APICHECK -DLUA_USE_ASSERT' > build.log 2>&1 || (cat build.log && exit 1) + - make -j$JOBS CCDEBUG=-g Q= PREFIX=$LUAJIT_PREFIX CC=$CC XCFLAGS='-DLUA_USE_APICHECK -DLUA_USE_ASSERT -msse4.2' > build.log 2>&1 || (cat build.log && exit 1) - sudo make install PREFIX=$LUAJIT_PREFIX > build.log 2>&1 || (cat build.log && exit 1) - cd .. - tar xzf download-cache/drizzle7-$DRIZZLE_VER.tar.gz && cd drizzle7-$DRIZZLE_VER @@ -97,7 +99,6 @@ script: - make libdrizzle-1.0 -j$JOBS > build.log 2>&1 || (cat build.log && exit 1) - sudo make install-libdrizzle-1.0 > build.log 2>&1 || (cat build.log && exit 1) - cd ../mockeagain/ && make CC=$CC -j$JOBS && cd .. - - cd test-nginx/ && sudo cpanm . && cd .. - cd lua-cjson/ && make -j$JOBS && sudo make install && cd .. - tar zxf download-cache/pcre-$PCRE_VER.tar.gz - cd pcre-$PCRE_VER/ @@ -107,13 +108,13 @@ script: - cd .. - tar zxf download-cache/openssl-$OPENSSL_VER.tar.gz - cd openssl-$OPENSSL_VER/ - - wget https://raw.githubusercontent.com/openresty/openresty/master/patches/openssl-$OPENSSL_VER-sess_set_get_cb_yield.patch - - patch -p1 < openssl-$OPENSSL_VER-sess_set_get_cb_yield.patch + - if [ ! -f ../download-cache/openssl-1.0.2h-sess_set_get_cb_yield.patch ]; then wget -P ../download-cache https://raw.githubusercontent.com/openresty/openresty/master/patches/openssl-1.0.2h-sess_set_get_cb_yield.patch; fi + - patch -p1 < ../download-cache/openssl-1.0.2h-sess_set_get_cb_yield.patch - ./config shared --prefix=$OPENSSL_PREFIX -DPURIFY > build.log 2>&1 || (cat build.log && exit 1) - make -j$JOBS > build.log 2>&1 || (cat build.log && exit 1) - sudo make PATH=$PATH install_sw > build.log 2>&1 || (cat build.log && exit 1) - cd .. - - export PATH=$PWD/work/nginx/sbin:$PWD/nginx-devel-utils:$PATH + - export PATH=$PWD/work/nginx/sbin:$PWD/openresty-devel-utils:$PATH - export NGX_BUILD_CC=$CC - sh util/build.sh $NGINX_VERSION > build.log 2>&1 || (cat build.log && exit 1) - nginx -V @@ -123,4 +124,4 @@ script: - export TEST_NGINX_RESOLVER=8.8.4.4 - dig +short @$TEST_NGINX_RESOLVER openresty.org || exit 0 - dig +short @$TEST_NGINX_RESOLVER agentzh.org || exit 0 - - prove -r t + - prove -Itest-nginx/lib -r t diff --git a/README.markdown b/README.markdown index 99b5275329..fac3a0d79b 100644 --- a/README.markdown +++ b/README.markdown @@ -62,7 +62,7 @@ Production ready. Version ======= -This document describes ngx_lua [v0.10.6](https://github.com/openresty/lua-nginx-module/tags) released on 15 August 2016. +This document describes ngx_lua [v0.10.10](https://github.com/openresty/lua-nginx-module/tags) released on 8 August 2017. Synopsis ======== @@ -150,7 +150,7 @@ Synopsis } # use nginx var in code path - # WARNING: contents in nginx var must be carefully filtered, + # CAUTION: contents in nginx var must be carefully filtered, # otherwise there'll be great security risk! location ~ ^/app/([-_a-zA-Z0-9/]+) { set $path $1; @@ -263,7 +263,7 @@ Nginx cores older than 1.6.0 (exclusive) are *not* supported. Installation ============ -It is highly recommended to use the [OpenResty bundle](http://openresty.org) that bundles Nginx, ngx_lua, LuaJIT 2.0/2.1 (or the optional standard Lua 5.1 interpreter), as well as a package of powerful companion Nginx modules. The basic installation step is a simple command: `./configure --with-luajit && make && make install`. +It is *highly* recommended to use [OpenResty releases](http://openresty.org) which integrate Nginx, ngx_lua, LuaJIT 2.1, as well as other powerful companion Nginx modules and Lua libraries. It is discouraged to build this module with nginx yourself since it is tricky to set up exactly right. Also, the stock nginx cores have various limitations and long standing bugs that can make some of this modules' features become disabled, not work properly, or run slower. Alternatively, ngx_lua can be manually compiled into Nginx: @@ -298,6 +298,12 @@ Build the source with this module: --add-module=/path/to/ngx_devel_kit \ --add-module=/path/to/lua-nginx-module + # Note that you may also want to add `./configure` options which are used in your + # current nginx build. + # You can get usually those options using command nginx -V + + # you can change the parallism number 2 below to fit the number of spare CPU cores in your + # machine. make -j2 make install ``` @@ -312,8 +318,9 @@ Starting from NGINX 1.9.11, you can also compile this module as a dynamic module directive, for example, ```nginx -load_module /path/to/modules/ndk_http_module.so; # assuming NDK is built as a dynamic module too -load_module /path/to/modules/ngx_http_lua_module.so; + + load_module /path/to/modules/ndk_http_module.so; # assuming NDK is built as a dynamic module too + load_module /path/to/modules/ngx_http_lua_module.so; ``` [Back to TOC](#table-of-contents) @@ -406,14 +413,14 @@ Please note that the bytecode format used by LuaJIT 2.0/2.1 is not compatible wi ```bash - /path/to/luajit/bin/luajit -b /path/to/input_file.lua /path/to/output_file.luac + /path/to/luajit/bin/luajit -b /path/to/input_file.lua /path/to/output_file.ljbc ``` The `-bg` option can be used to include debug information in the LuaJIT bytecode file: ```bash - /path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.luac + /path/to/luajit/bin/luajit -bg /path/to/input_file.lua /path/to/output_file.ljbc ``` Please refer to the official LuaJIT documentation on the `-b` option for more details: @@ -585,10 +592,10 @@ and then accessing it from `nginx.conf`: ```nginx location /lua { - content_by_lua ' + content_by_lua_block { local mydata = require "mydata" ngx.say(mydata.get_age("dog")) - '; + } } ``` @@ -623,9 +630,9 @@ Known Issues TCP socket connect operation issues ----------------------------------- -The [tcpsock:connect](#tcpsockconnect) method may indicate `success` despite connection failures such as with `Connection Refused` errors. +The [tcpsock:connect](#tcpsockconnect) method may indicate `success` despite connection failures such as with `Connection Refused` errors. -However, later attempts to manipulate the cosocket object will fail and return the actual error status message generated by the failed connect operation. +However, later attempts to manipulate the cosocket object will fail and return the actual error status message generated by the failed connect operation. This issue is due to limitations in the Nginx event model and only appears to affect Mac OS X. @@ -656,15 +663,29 @@ instead of the old deprecated form: Here is the reason: by design, the global environment has exactly the same lifetime as the Nginx request handler associated with it. Each request handler has its own set of Lua global variables and that is the idea of request isolation. The Lua module is actually loaded by the first Nginx request handler and is cached by the `require()` built-in in the `package.loaded` table for later reference, and the `module()` builtin used by some Lua modules has the side effect of setting a global variable to the loaded module table. But this global variable will be cleared at the end of the request handler, and every subsequent request handler all has its own (clean) global environment. So one will get Lua exception for accessing the `nil` value. -Generally, use of Lua global variables is a really really bad idea in the context of ngx_lua because +The use of Lua global variables is a generally inadvisable in the ngx_lua context as: + +1. the misuse of Lua globals has detrimental side effects on concurrent requests when such variables should instead be local in scope, +1. Lua global variables require Lua table look-ups in the global environment which is computationally expensive, and +1. some Lua global variable references may include typing errors which make such difficult to debug. -1. misuse of Lua globals has very bad side effects for concurrent requests when these variables are actually supposed to be local only, -1. Lua global variables require Lua table look-up in the global environment (which is just a Lua table), which is kinda expensive, and -1. some Lua global variable references are just typos, which are hard to debug. +It is therefore *highly* recommended to always declare such within an appropriate local scope instead. -It's *highly* recommended to always declare them via "local" in the scope that is reasonable. +```lua -To find out all the uses of Lua global variables in your Lua code, you can run the [lua-releng tool](https://github.com/openresty/nginx-devel-utils/blob/master/lua-releng) across all your .lua source files: + -- Avoid + foo = 123 + -- Recommended + local foo = 123 + + -- Avoid + function foo() return 123 end + -- Recommended + local function foo() return 123 end +``` + + +To find all instances of Lua global variables in your Lua code, run the [lua-releng tool](https://github.com/openresty/nginx-devel-utils/blob/master/lua-releng) across all `.lua` source files: $ lua-releng Checking use of Lua global variables in file lib/foo/bar.lua ... @@ -685,9 +706,9 @@ The [ngx.location.capture](#ngxlocationcapture) and [ngx.location.capture_multi] ```nginx location /foo { - content_by_lua ' + content_by_lua_block { res = ngx.location.capture("/bar") - '; + } } location /bar { echo_location /blah; @@ -709,28 +730,27 @@ will not work as expected. Cosockets Not Available Everywhere ---------------------------------- -Due the internal limitations in the nginx core, the cosocket API are disabled in the following contexts: [set_by_lua*](#set_by_lua), [log_by_lua*](#log_by_lua), [header_filter_by_lua*](#header_filter_by_lua), and [body_filter_by_lua](#body_filter_by_lua). +Due to internal limitations in the nginx core, the cosocket API is disabled in the following contexts: [set_by_lua*](#set_by_lua), [log_by_lua*](#log_by_lua), [header_filter_by_lua*](#header_filter_by_lua), and [body_filter_by_lua](#body_filter_by_lua). The cosockets are currently also disabled in the [init_by_lua*](#init_by_lua) and [init_worker_by_lua*](#init_worker_by_lua) directive contexts but we may add support for these contexts in the future because there is no limitation in the nginx core (or the limitation might be worked around). -There exists a work-around, however, when the original context does *not* need to wait for the cosocket results. That is, creating a 0-delay timer via the [ngx.timer.at](#ngxtimerat) API and do the cosocket results in the timer handler, which runs asynchronously as to the original context creating the timer. +There exists a work-around, however, when the original context does *not* need to wait for the cosocket results. That is, creating a zero-delay timer via the [ngx.timer.at](#ngxtimerat) API and do the cosocket results in the timer handler, which runs asynchronously as to the original context creating the timer. [Back to TOC](#table-of-contents) Special Escaping Sequences -------------------------- -**WARNING** We no longer suffer from this pitfall since the introduction of the -`*_by_lua_block {}` configuration directives. +**NOTE** Following the `v0.9.17` release, this pitfall can be avoided by using the `*_by_lua_block {}` configuration directives. -PCRE sequences such as `\d`, `\s`, or `\w`, require special attention because in string literals, the backslash character, `\`, is stripped out by both the Lua language parser and by the Nginx config file parser before processing. So the following snippet will not work as expected: +PCRE sequences such as `\d`, `\s`, or `\w`, require special attention because in string literals, the backslash character, `\`, is stripped out by both the Lua language parser and by the nginx config file parser before processing if not within a `*_by_lua_block {}` directive. So the following snippet will not work as expected: ```nginx # nginx.conf ? location /test { ? content_by_lua ' - ? local regex = "\d+" -- THIS IS WRONG!! + ? local regex = "\d+" -- THIS IS WRONG OUTSIDE OF A *_by_lua_block DIRECTIVE ? local m = ngx.re.match("hello, 1234", regex) ? if m then ngx.say(m[0]) else ngx.say("not matched!") end ? '; @@ -755,7 +775,7 @@ To avoid this, *double* escape the backslash: Here, `\\\\d+` is stripped down to `\\d+` by the Nginx config file parser and this is further stripped down to `\d+` by the Lua language parser before running. -Alternatively, the regex pattern can be presented as a long-bracketed Lua string literal by encasing it in "long brackets", `[[...]]`, in which case backslashes have to only be escaped once for the Nginx config file parser. +Alternatively, the regex pattern can be presented as a long-bracketed Lua string literal by encasing it in "long brackets", `[[...]]`, in which case backslashes have to only be escaped once for the Nginx config file parser. ```nginx @@ -772,7 +792,7 @@ Alternatively, the regex pattern can be presented as a long-bracketed Lua string Here, `[[\\d+]]` is stripped down to `[[\d+]]` by the Nginx config file parser and this is processed correctly. -Note that a longer from of the long bracket, `[=[...]=]`, may be required if the regex pattern contains `[...]` sequences. +Note that a longer from of the long bracket, `[=[...]=]`, may be required if the regex pattern contains `[...]` sequences. The `[=[...]=]` form may be used as the default form if desired. ```nginx @@ -788,7 +808,7 @@ The `[=[...]=]` form may be used as the default form if desired. # evaluates to "1234" ``` -An alternative approach to escaping PCRE sequences is to ensure that Lua code is placed in external script files and executed using the various `*_by_lua_file` directives. +An alternative approach to escaping PCRE sequences is to ensure that Lua code is placed in external script files and executed using the various `*_by_lua_file` directives. With this approach, the backslashes are only stripped by the Lua language parser and therefore only need to be escaped once each. ```lua @@ -800,8 +820,8 @@ With this approach, the backslashes are only stripped by the Lua language parser -- evaluates to "1234" ``` -Within external script files, PCRE sequences presented as long-bracketed Lua string literals do not require modification. - +Within external script files, PCRE sequences presented as long-bracketed Lua string literals do not require modification. + ```lua -- test.lua @@ -811,6 +831,22 @@ Within external script files, PCRE sequences presented as long-bracketed Lua str -- evaluates to "1234" ``` +As noted earlier, PCRE sequences presented within `*_by_lua_block {}` directives (available following the `v0.9.17` release) do not require modification. + +```nginx + + # nginx.conf + location /test { + content_by_lua_block { + local regex = "\d+" + local m = ngx.re.match("hello, 1234", regex) + if m then ngx.say(m[0]) else ngx.say("not matched!") end + } + } + # evaluates to "1234" +``` + + [Back to TOC](#table-of-contents) Mixing with SSI Not Supported @@ -859,9 +895,9 @@ servers in Lua. For example, datagram { server { listen 1953; - handler_by_lua ' + handler_by_lua_block { -- custom Lua code implementing the special UDP server... - '; + } } } ``` @@ -871,7 +907,6 @@ servers in Lua. For example, * cosocket: pool-based backend concurrency level control: implement automatic `connect` queueing when the backend concurrency exceeds its connection pool limit. * cosocket: review and merge aviramc's [patch](https://github.com/openresty/lua-nginx-module/pull/290) for adding the `bsdrecv` method. * add new API function `ngx.resp.add_header` to emulate the standard `add_header` config directive. -* review and apply Jader H. Silva's patch for `ngx.re.split()`. * review and apply vadim-pavlov's patch for [ngx.location.capture](#ngxlocationcapture)'s `extra_headers` option * use `ngx_hash_t` to optimize the built-in header look-up process for [ngx.req.set_header](#ngxreqset_header), [ngx.header.HEADER](#ngxheaderheader), and etc. * add configure options for different strategies of handling the cosocket connection exceeding in the pools. @@ -879,14 +914,14 @@ servers in Lua. For example, * add `ignore_resp_headers`, `ignore_resp_body`, and `ignore_resp` options to [ngx.location.capture](#ngxlocationcapture) and [ngx.location.capture_multi](#ngxlocationcapture_multi) methods, to allow micro performance tuning on the user side. * 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](https://httpd.apache.org/docs/trunk/mod/mod_lua.html). -* cosocket: add client SSL certificiate support. +* cosocket: add client SSL certificate support. [Back to TOC](#table-of-contents) Changes ======= -The changes of every release of this module can be obtained from the OpenResty bundle's change logs: +The changes made in every release of this module are listed in the change logs of the OpenResty bundle: @@ -955,9 +990,9 @@ Copyright and License This module is licensed under the BSD license. -Copyright (C) 2009-2016, by Xiaozhe Wang (chaoslawful) . +Copyright (C) 2009-2017, by Xiaozhe Wang (chaoslawful) . -Copyright (C) 2009-2016, by Yichun "agentzh" Zhang (章亦春) , CloudFlare Inc. +Copyright (C) 2009-2017, by Yichun "agentzh" Zhang (章亦春) , OpenResty Inc. All rights reserved. @@ -1001,7 +1036,9 @@ See Also Directives ========== +* [lua_capture_error_log](#lua_capture_error_log) * [lua_use_default_type](#lua_use_default_type) +* [lua_malloc_trim](#lua_malloc_trim) * [lua_code_cache](#lua_code_cache) * [lua_regex_cache_max_entries](#lua_regex_cache_max_entries) * [lua_regex_match_limit](#lua_regex_match_limit) @@ -1073,6 +1110,56 @@ how the result will be used. Below is a diagram showing the order in which direc [Back to TOC](#table-of-contents) +lua_capture_error_log +--------------------- +**syntax:** *lua_capture_error_log size* + +**default:** *none* + +**context:** *http* + +Enables a buffer of the specified `size` for capturing all the nginx error log message data (not just those produced +by this module or the nginx http subsystem, but everything) without touching files or disks. + +You can use units like `k` and `m` in the `size` value, as in + +```nginx + + lua_capture_error_log 100k; +``` + +As a rule of thumb, a 4KB buffer can usually hold about 20 typical error log messages. So do the maths! + +This buffer never grows. If it is full, new error log messages will replace the oldest ones in the buffer. + +The size of the buffer must be bigger than the maximum length of a single error log message (which is 4K in OpenResty and 2K in stock NGINX). + +You can read the messages in the buffer on the Lua land via the +[get_logs()](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/errlog.md#get_logs) +function of the +[ngx.errlog](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/errlog.md#readme) +module of the [lua-resty-core](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/errlog.md#readme) +library. This Lua API function will return the captured error log messages and +also remove these already read from the global capturing buffer, making room +for any new error log data. For this reason, the user should not configure this +buffer to be too big if the user read the buffered error log data fast enough. + +Note that the log level specified in the standard [error_log](http://nginx.org/r/error_log) directive +*does* have effect on this capturing facility. It only captures log +messages of a level no lower than the specified log level in the [error_log](http://nginx.org/r/error_log) directive. +The user can still choose to set an even higher filtering log level on the fly via the Lua API function +[errlog.set_filter_level](https://github.com/openresty/lua-resty-core/blob/master/lib/ngx/errlog.md#set_filter_level). +So it is more flexible than the static [error_log](http://nginx.org/r/error_log) directive. + +It is worth noting that there is no way to capture the debugging logs +without building OpenResty or NGINX with the `./configure` +option `--with-debug`. And enabling debugging logs is +strongly discouraged in production builds due to high overhead. + +This directive was first introduced in the `v0.10.9` release. + +[Back to TOC](#directives) + lua_use_default_type -------------------- **syntax:** *lua_use_default_type on | off* @@ -1081,7 +1168,7 @@ lua_use_default_type **context:** *http, server, location, location if* -Specifies whether to use the MIME type specified by the [default_type](http://nginx.org/en/docs/http/ngx_http_core_module.html#default_type) directive for the default value of the `Content-Type` response header. If you do not want a default `Content-Type` response header for your Lua request handlers, then turn this directive off. +Specifies whether to use the MIME type specified by the [default_type](http://nginx.org/en/docs/http/ngx_http_core_module.html#default_type) directive for the default value of the `Content-Type` response header. Deactivate this directive if a default `Content-Type` response header for Lua request handlers is not desired. This directive is turned on by default. @@ -1089,6 +1176,38 @@ This directive was first introduced in the `v0.9.1` release. [Back to TOC](#directives) +lua_malloc_trim +--------------- +**syntax:** *lua_malloc_trim <request-count>* + +**default:** *lua_malloc_trim 1000* + +**context:** *http* + +Asks the underlying `libc` runtime library to release its cached free memory back to the operating system every +`N` requests processed by the NGINX core. By default, `N` is 1000. You can configure the request count +by using your own numbers. Smaller numbers mean more frequent releases, which may introduce higher CPU time consumption and +smaller memory footprint while larger numbers usually lead to less CPU time overhead and relatively larger memory footprint. +Just tune the number for your own use cases. + +Configuring the argument to `0` essentially turns off the periodical memory trimming altogether. + +```nginx + + lua_malloc_trim 0; # turn off trimming completely +``` + +The current implementation uses an NGINX log phase handler to do the request counting. So the appearance of the +[log_subrequest on](http://nginx.org/en/docs/http/ngx_http_core_module.html#log_subrequest) directives in `nginx.conf` +may make the counting faster when subrequests are involved. By default, only "main requests" count. + +Note that this directive does *not* affect the memory allocated by LuaJIT's own allocator based on the `mmap` +system call. + +This directive was first introduced in the `v0.10.7` release. + +[Back to TOC](#directives) + lua_code_cache -------------- **syntax:** *lua_code_cache on | off* @@ -1120,8 +1239,8 @@ The ngx_lua module does not support the `stat` mode available with the Apache `mod_lua` module (yet). Disabling the Lua code cache is strongly -discouraged for production use and should only be used during -development as it has a significant negative impact on overall performance. For example, the performance a "hello world" Lua example can drop by an order of magnitude after disabling the Lua code cache. +discouraged for production use and should only be used during +development as it has a significant negative impact on overall performance. For example, the performance of a "hello world" Lua example can drop by an order of magnitude after disabling the Lua code cache. [Back to TOC](#directives) @@ -1143,6 +1262,8 @@ The default number of entries allowed is 1024 and when this limit is reached, ne 2011/08/27 23:18:26 [warn] 31997#0: *1 lua exceeding regex cache max entries (1024), ... +If you are using the `ngx.re.*` implementation of [lua-resty-core](https://github.com/openresty/lua-resty-core) by loading the `resty.core.regex` module (or just the `resty.core` module), then an LRU cache is used for the regex cache being used here. + Do not activate the `o` option for regular expressions (and/or `replace` string arguments for [ngx.re.sub](#ngxresub) and [ngx.re.gsub](#ngxregsub)) that are generated *on the fly* and give rise to infinite variations to avoid hitting the specified limit. [Back to TOC](#directives) @@ -1208,8 +1329,7 @@ init_by_lua **phase:** *loading-config* -**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*; -use the new [init_by_lua_block](#init_by_lua_block) directive instead. +**NOTE** Use of this directive is *discouraged* following the `v0.9.17` release. Use the [init_by_lua_block](#init_by_lua_block) directive instead. Runs the Lua code specified by the argument `` on the global Lua VM level when the Nginx master process (if any) is loading the Nginx config file. @@ -1223,9 +1343,9 @@ Usually you can register (true) Lua global variables or pre-load Lua modules at server { location = /api { - content_by_lua ' + content_by_lua_block { ngx.say(cjson.encode({dog = 5, cat = 6})) - '; + } } } ``` @@ -1243,10 +1363,10 @@ You can also initialize the [lua_shared_dict](#lua_shared_dict) shm storage at t server { location = /api { - content_by_lua ' + content_by_lua_block { local dogs = ngx.shared.dogs; ngx.say(dogs:get("Tom")) - '; + } } } ``` @@ -1325,7 +1445,7 @@ init_worker_by_lua **phase:** *starting-worker* -**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*; use the new [init_worker_by_lua_block](#init_worker_by_lua_block) directive instead. +**NOTE** Use of this directive is *discouraged* following the `v0.9.17` release. Use the [init_worker_by_lua_block](#init_worker_by_lua_block) directive instead. Runs the specified Lua code upon every Nginx worker process's startup when the master process is enabled. When the master process is disabled, this hook will just run after [init_by_lua*](#init_by_lua). @@ -1351,8 +1471,8 @@ This hook is often used to create per-worker reoccurring timers (via the [ngx.ti end end - local ok, err = new_timer(delay, check) - if not ok then + local hdl, err = new_timer(delay, check) + if not hdl then log(ERR, "failed to create timer: ", err) return end @@ -1414,7 +1534,7 @@ set_by_lua **phase:** *rewrite* -**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*; use the new [set_by_lua_block](#set_by_lua_block) directive instead. +**NOTE** Use of this directive is *discouraged* following the `v0.9.17` release. Use the [set_by_lua_block](#set_by_lua_block) directive instead. Executes code specified in `` with optional input arguments `$arg1 $arg2 ...`, and returns string output to `$res`. The code in `` can make [API calls](#nginx-api-for-lua) and can retrieve input arguments from the `ngx.arg` table (index starts from `1` and increases sequentially). @@ -1504,15 +1624,15 @@ set_by_lua_file **phase:** *rewrite* -Equivalent to [set_by_lua](#set_by_lua), except that the file specified by `` contains the Lua code, or, as from the `v0.5.0rc32` release, the [Lua/LuaJIT bytecode](#lualuajit-bytecode-support) to be executed. +Equivalent to [set_by_lua](#set_by_lua), except that the file specified by `` contains the Lua code, or, as from the `v0.5.0rc32` release, the [Lua/LuaJIT bytecode](#lualuajit-bytecode-support) to be executed. Nginx variable interpolation is supported in the `` argument string of this directive. But special care must be taken for injection attacks. When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. -When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached +When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached and the Nginx config must be reloaded each time the Lua source file is modified. -The Lua code cache can be temporarily disabled during development by +The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](#lua_code_cache) `off` in `nginx.conf` to avoid reloading Nginx. This directive requires the [ngx_devel_kit](https://github.com/simpl/ngx_devel_kit) module. @@ -1528,10 +1648,9 @@ content_by_lua **phase:** *content* -**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*; -use the new [content_by_lua_block](#content_by_lua_block) directive instead. +**NOTE** Use of this directive is *discouraged* following the `v0.9.17` release. Use the [content_by_lua_block](#content_by_lua_block) directive instead. -Acts as a "content handler" and executes Lua code string specified in `` for every request. +Acts as a "content handler" and executes Lua code string specified in `` for every request. The Lua code may make [API calls](#nginx-api-for-lua) and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox). Do not use this directive and other content handler directives in the same location. For example, this directive and the [proxy_pass](http://nginx.org/en/docs/http/ngx_http_proxy_module.html#proxy_pass) directive should not be used in the same location. @@ -1580,16 +1699,16 @@ Nginx variables can be used in the `` string to provide When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. -When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached +When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached and the Nginx config must be reloaded each time the Lua source file is modified. -The Lua code cache can be temporarily disabled during development by +The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](#lua_code_cache) `off` in `nginx.conf` to avoid reloading Nginx. Nginx variables are supported in the file path for dynamic dispatch, for example: ```nginx - # WARNING: contents in nginx var must be carefully filtered, + # CAUTION: contents in nginx var must be carefully filtered, # otherwise there'll be great security risk! location ~ ^/app/([-_a-zA-Z0-9/]+) { set $path $1; @@ -1610,8 +1729,7 @@ rewrite_by_lua **phase:** *rewrite tail* -**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*; -use the new [rewrite_by_lua_block](#rewrite_by_lua_block) directive instead. +**NOTE** Use of this directive is *discouraged* following the `v0.9.17` release. Use the [rewrite_by_lua_block](#rewrite_by_lua_block) directive instead. Acts as a rewrite phase handler and executes Lua code string specified in `` for every request. The Lua code may make [API calls](#nginx-api-for-lua) and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox). @@ -1787,8 +1905,7 @@ access_by_lua **phase:** *access tail* -**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*; -use the new [access_by_lua_block](#access_by_lua_block) directive instead. +**NOTE** Use of this directive is *discouraged* following the `v0.9.17` release. Use the [access_by_lua_block](#access_by_lua_block) directive instead. Acts as an access phase handler and executes Lua code string specified in `` for every request. The Lua code may make [API calls](#nginx-api-for-lua) and is executed as a new spawned coroutine in an independent global environment (i.e. a sandbox). @@ -1900,7 +2017,7 @@ Nginx variables can be used in the `` string to provide When a relative path like `foo/bar.lua` is given, they will be turned into the absolute path relative to the `server prefix` path determined by the `-p PATH` command-line option while starting the Nginx server. -When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached +When the Lua code cache is turned on (by default), the user code is loaded once at the first request and cached and the Nginx config must be reloaded each time the Lua source file is modified. The Lua code cache can be temporarily disabled during development by switching [lua_code_cache](#lua_code_cache) `off` in `nginx.conf` to avoid repeatedly reloading Nginx. @@ -1917,8 +2034,7 @@ header_filter_by_lua **phase:** *output-header-filter* -**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*; -use the new [header_filter_by_lua_block](#header_filter_by_lua_block) directive instead. +**NOTE** Use of this directive is *discouraged* following the `v0.9.17` release. Use the [header_filter_by_lua_block](#header_filter_by_lua_block) directive instead. Uses Lua code specified in `` to define an output header filter. @@ -1996,8 +2112,7 @@ body_filter_by_lua **phase:** *output-body-filter* -**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*; -use the new [body_filter_by_lua_block](#body_filter_by_lua_block) directive instead. +**NOTE** Use of this directive is *discouraged* following the `v0.9.17` release. Use the [body_filter_by_lua_block](#body_filter_by_lua_block) directive instead. Uses Lua code specified in `` to define an output body filter. @@ -2062,7 +2177,7 @@ When the Lua code may change the length of the response body, then it is require location /foo { # fastcgi_pass/proxy_pass/... - header_filter_by_lua 'ngx.header.content_length = nil'; + header_filter_by_lua_block { ngx.header.content_length = nil } body_filter_by_lua 'ngx.arg[1] = string.len(ngx.arg[1]) .. "\\n"'; } ``` @@ -2133,15 +2248,14 @@ log_by_lua **phase:** *log* -**WARNING** Since the `v0.9.17` release, use of this directive is *discouraged*; -use the new [log_by_lua_block](#log_by_lua_block) directive instead. +**NOTE** Use of this directive is *discouraged* following the `v0.9.17` release. Use the [log_by_lua_block](#log_by_lua_block) directive instead. Runs the Lua source code inlined as the `` at the `log` request processing phase. This does not replace the current access logs, but runs before. Note that the following API functions are currently disabled within this context: * Output API functions (e.g., [ngx.say](#ngxsay) and [ngx.send_headers](#ngxsend_headers)) -* Control API functions (e.g., [ngx.exit](#ngxexit)) +* Control API functions (e.g., [ngx.exit](#ngxexit)) * Subrequest API functions (e.g., [ngx.location.capture](#ngxlocationcapture) and [ngx.location.capture_multi](#ngxlocationcapture_multi)) * Cosocket API functions (e.g., [ngx.socket.tcp](#ngxsockettcp) and [ngx.req.socket](#ngxreqsocket)). @@ -2172,7 +2286,7 @@ Here is an example of gathering average data for [$upstream_response_time](http: } location = /status { - content_by_lua ' + content_by_lua_block { local log_dict = ngx.shared.log_dict local sum = log_dict:get("upstream_time-sum") local nb = log_dict:get("upstream_time-nb") @@ -2183,7 +2297,7 @@ Here is an example of gathering average data for [$upstream_response_time](http: else ngx.say("no data yet") end - '; + } } } ``` @@ -2329,15 +2443,15 @@ Determines whether to force the request body data to be read before running rewr To read the request body data within the [$request_body](http://nginx.org/en/docs/http/ngx_http_core_module.html#var_request_body) variable, [client_body_buffer_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size) must have the same value as [client_max_body_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_max_body_size). Because when the content length exceeds [client_body_buffer_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size) but less than [client_max_body_size](http://nginx.org/en/docs/http/ngx_http_core_module.html#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://nginx.org/en/docs/http/ngx_http_core_module.html#var_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 +If the current location includes [rewrite_by_lua*](#rewrite_by_lua) directives, +then the request body will be read just before the [rewrite_by_lua*](#rewrite_by_lua) code is run (and also at the `rewrite` phase). Similarly, if only [content_by_lua](#content_by_lua) is specified, the request body will not be read until the content handler's Lua code is about to run (i.e., the request body will be read during the content phase). It is recommended however, to use the [ngx.req.read_body](#ngxreqread_body) and [ngx.req.discard_body](#ngxreqdiscard_body) functions for finer control over the request body reading process instead. -This also applies to [access_by_lua](#access_by_lua) and [access_by_lua_file](#access_by_lua_file). +This also applies to [access_by_lua*](#access_by_lua). [Back to TOC](#directives) @@ -2452,7 +2566,7 @@ ssl_session_fetch_by_lua_block **syntax:** *ssl_session_fetch_by_lua_block { lua-script }* -**context:** *server* +**context:** *http* **phase:** *right-before-SSL-handshake* @@ -2508,6 +2622,9 @@ apply the following patch to the standard NGINX core 1.11.2 or later: This directive was first introduced in the `v0.10.6` release. +Note that: this directive is only allowed to used in **http context** from the `v0.10.7` release +(because SSL session resumption happens before server name dispatch). + [Back to TOC](#directives) ssl_session_fetch_by_lua_file @@ -2515,7 +2632,7 @@ ssl_session_fetch_by_lua_file **syntax:** *ssl_session_fetch_by_lua_file <path-to-lua-script-file>* -**context:** *server* +**context:** *http* **phase:** *right-before-SSL-handshake* @@ -2525,6 +2642,9 @@ When a relative path like `foo/bar.lua` is given, they will be turned into the a This directive was first introduced in the `v0.10.6` release. +Note that: this directive is only allowed to used in **http context** from the `v0.10.7` release +(because SSL session resumption happens before server name dispatch). + [Back to TOC](#directives) ssl_session_store_by_lua_block @@ -2532,7 +2652,7 @@ ssl_session_store_by_lua_block **syntax:** *ssl_session_store_by_lua_block { lua-script }* -**context:** *server* +**context:** *http* **phase:** *right-after-SSL-handshake* @@ -2559,6 +2679,9 @@ But do not forget to comment this line out before publishing your site to the wo This directive was first introduced in the `v0.10.6` release. +Note that: this directive is only allowed to used in **http context** from the `v0.10.7` release +(because SSL session resumption happens before server name dispatch). + [Back to TOC](#directives) ssl_session_store_by_lua_file @@ -2566,7 +2689,7 @@ ssl_session_store_by_lua_file **syntax:** *ssl_session_store_by_lua_file <path-to-lua-script-file>* -**context:** *server* +**context:** *http* **phase:** *right-before-SSL-handshake* @@ -2576,6 +2699,9 @@ When a relative path like `foo/bar.lua` is given, they will be turned into the a This directive was first introduced in the `v0.10.6` release. +Note that: this directive is only allowed to used in **http context** from the `v0.10.7` release +(because SSL session resumption happens before server name dispatch). + [Back to TOC](#directives) lua_shared_dict @@ -2621,7 +2747,7 @@ lua_socket_connect_timeout **context:** *http, server, location* -This directive controls the default timeout value used in TCP/unix-domain socket object's [connect](#tcpsockconnect) method and can be overridden by the [settimeout](#tcpsocksettimeout) method. +This directive controls the default timeout value used in TCP/unix-domain socket object's [connect](#tcpsockconnect) method and can be overridden by the [settimeout](#tcpsocksettimeout) or [settimeouts](#tcpsocksettimeouts) methods. The `