Skip to content

Commit

Permalink
documented the init_by_lua* directives and also bumped version number…
Browse files Browse the repository at this point in the history 
… to 0.5.5.
  • Loading branch information
@agentzh
agentzh committed Jul 4, 2012
1 parent 588ee4d commit 4275482
Show file tree
Hide file tree
Showing 3 changed files with 315 additions and 53 deletions.
160 changes: 133 additions & 27 deletions README
View file
Expand Up @@ -8,9 +8,9 @@ Status
This module is under active development and is production ready.

Version
This document describes ngx_lua v0.5.4
(<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 28
June 2012.
This document describes ngx_lua v0.5.5
(<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 4
July 2012.

Synopsis
# set search paths for pure Lua external libraries (';;' is the default path):
Expand Down Expand Up @@ -297,6 +297,103 @@ Directives
of the "server prefix" usually determined by the "-p PATH" command-line
option while starting the Nginx server.

init_by_lua
syntax: *init_by_lua <lua-script-str>*

context: *http*

phase: *loading-config*

Runs the Lua code specified by the argument "<lua-script-str>" on the
global Lua VM level when the Nginx master process (if any) is loading
the Nginx config file.

When Nginx receives the "HUP" signal and starts reloading the config
file, the Lua VM will also be re-created and "init_by_lua" will run
again on the new Lua VM.

Usually you can register (true) Lua global variables or pre-load Lua
modules at server start-up by means of this hook. Here is an example for
pre-loading Lua modules:

init_by_lua 'require "cjson"';

server {
location = /api {
content_by_lua '
ngx.say(cjson.encode({dog = 5, cat = 6}))
';
}
}

You can also initialize the lua_shared_dict shm storage at this phase.
Here is an example for this:

lua_shared_dict dogs 1m;

init_by_lua '
local dogs = ngx.shared.dogs;
dogs:set("Tom", 56)
';

server {
location = /api {
content_by_lua '
local dogs = ngx.shared.dogs;
ngx.say(dogs:get("Tom"))
';
}
}

But note that, the lua_shared_dict's shm storage will not be cleared
through a config reload (via the "HUP" signal, for example). So if you
do *not* want to re-initialize the shm storage in your "init_by_lua"
code in this case, then you just need to set a custom flag in the shm
storage and always check the flag in your "init_by_lua" code.

Because the Lua code in this context runs before Nginx forks its worker
processes (if any), data or code loaded here will enjoy the
Copy-on-write (COW) (<http://en.wikipedia.org/wiki/Copy-on-write>)
feature provided by many operating systems among all the worker
processes, thus saving a lot of memory.

Only a small set of the Nginx API for Lua is supported in this context:

* Logging APIs: ngx.log and print,

* Shared Dictionary API: ngx.shared.DICT.

More Nginx APIs for Lua may be supported in this context upon future
user requests.

Basically you can safely use Lua libraries that do blocking I/O in this
very context because blocking the master process during server start-up
is completely okay. Even the Nginx core does blocking I/O (at least on
resolving upstream's host names) at the configure-loading phase.

You should be very careful about potential security vulnerabilities in
your Lua code registered in this context because the Nginx master
process is often run under the "root" account.

This directive was first introduced in the "v0.5.5" release.

init_by_lua_file
syntax: *init_by_lua_file <path-to-lua-script-file>*

context: *http*

phase: *loading-config*

Equivalent to init_by_lua, except that the file specified by
"<path-to-lua-script-file>" contains the Lua code (or the Lua raw
bytecode) to be executed.

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.

This directive was first introduced in the "v0.5.5" release.

set_by_lua
syntax: *set_by_lua $res <lua-script-str> [$arg1 $arg2 ...]*

Expand Down Expand Up @@ -1291,8 +1388,9 @@ Nginx API for Lua
ngx.var.args = nil

Core constants
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua, *log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua,
*log_by_lua**

ngx.OK (0)
ngx.ERROR (-1)
Expand All @@ -1316,8 +1414,8 @@ Nginx API for Lua
release.

HTTP method constants
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua**

ngx.HTTP_GET
ngx.HTTP_HEAD
Expand All @@ -1330,8 +1428,8 @@ Nginx API for Lua
ngx.location.capture_multi method calls.

HTTP status constants
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua**

value = ngx.HTTP_OK (200)
value = ngx.HTTP_CREATED (201)
Expand Down Expand Up @@ -1370,8 +1468,8 @@ Nginx API for Lua
print
syntax: *print(...)*

context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua**

Writes argument values into the nginx "error.log" file with the
"ngx.NOTICE" log level.
Expand Down Expand Up @@ -2675,8 +2773,9 @@ Nginx API for Lua
ngx.log
syntax: *ngx.log(log_level, ...)*

context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
log_by_lua**

Log arguments concatenated to error.log with the given logging level.

Expand Down Expand Up @@ -3374,8 +3473,9 @@ Nginx API for Lua
ngx.shared.DICT
syntax: *dict = ngx.shared.DICT*

context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
log_by_lua**

Fetching the shm-based Lua dictionary object for the shared memory zone
named "DICT" defined by the lua_shared_dict directive.
Expand Down Expand Up @@ -3480,8 +3580,9 @@ Nginx API for Lua
syntax: *success, err, forcible = ngx.shared.DICT:set(key, value,
exptime?, flags?)*

context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
log_by_lua**

Unconditionally sets a key-value pair into the shm-based dictionary
ngx.shared.DICT. Returns three values:
Expand Down Expand Up @@ -3546,8 +3647,9 @@ Nginx API for Lua
syntax: *success, err, forcible = ngx.shared.DICT:add(key, value,
exptime?, flags?)*

context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
log_by_lua**

Just like the set method, but only stores the key-value pair into the
dictionary ngx.shared.DICT if the key does *not* exist.
Expand All @@ -3564,8 +3666,9 @@ Nginx API for Lua
syntax: *success, err, forcible = ngx.shared.DICT:replace(key, value,
exptime?, flags?)*

context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
log_by_lua**

Just like the set method, but only stores the key-value pair into the
dictionary ngx.shared.DICT if the key *does* exist.
Expand All @@ -3581,8 +3684,9 @@ Nginx API for Lua
ngx.shared.DICT.delete
syntax: *ngx.shared.DICT:delete(key)*

context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
log_by_lua**

Unconditionally removes the key-value pair from the shm-based dictionary
ngx.shared.DICT.
Expand All @@ -3596,8 +3700,9 @@ Nginx API for Lua
ngx.shared.DICT.incr
syntax: *newval, err = ngx.shared.DICT:incr(key, value)*

context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
log_by_lua**

Increments the (numerical) value for "key" in the shm-based dictionary
ngx.shared.DICT by the step value "value". Returns the new resulting
Expand All @@ -3620,8 +3725,9 @@ Nginx API for Lua
ngx.shared.DICT.flush_all
syntax: *ngx.shared.DICT:flush_all()*

context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
log_by_lua**

Flushes out all the items in the dictionary.

Expand Down

0 comments on commit 4275482

Please sign in to comment.