Skip to content
This repository
Browse code

documented the init_by_lua* directives and also bumped version number…

… to 0.5.5.
  • Loading branch information...
commit 4275482f4916f4840c7f6dbe2675ea9725db6ab5 1 parent 588ee4d
Yichun Zhang authored July 04, 2012
160  README
@@ -8,9 +8,9 @@ Status
8 8
     This module is under active development and is production ready.
9 9
 
10 10
 Version
11  
-    This document describes ngx_lua v0.5.4
12  
-    (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 28
13  
-    June 2012.
  11
+    This document describes ngx_lua v0.5.5
  12
+    (<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 4
  13
+    July 2012.
14 14
 
15 15
 Synopsis
16 16
         # set search paths for pure Lua external libraries (';;' is the default path):
@@ -297,6 +297,103 @@ Directives
297 297
     of the "server prefix" usually determined by the "-p PATH" command-line
298 298
     option while starting the Nginx server.
299 299
 
  300
+  init_by_lua
  301
+    syntax: *init_by_lua <lua-script-str>*
  302
+
  303
+    context: *http*
  304
+
  305
+    phase: *loading-config*
  306
+
  307
+    Runs the Lua code specified by the argument "<lua-script-str>" on the
  308
+    global Lua VM level when the Nginx master process (if any) is loading
  309
+    the Nginx config file.
  310
+
  311
+    When Nginx receives the "HUP" signal and starts reloading the config
  312
+    file, the Lua VM will also be re-created and "init_by_lua" will run
  313
+    again on the new Lua VM.
  314
+
  315
+    Usually you can register (true) Lua global variables or pre-load Lua
  316
+    modules at server start-up by means of this hook. Here is an example for
  317
+    pre-loading Lua modules:
  318
+
  319
+        init_by_lua 'require "cjson"';
  320
+
  321
+        server {
  322
+            location = /api {
  323
+                content_by_lua '
  324
+                    ngx.say(cjson.encode({dog = 5, cat = 6}))
  325
+                ';
  326
+            }
  327
+        }
  328
+
  329
+    You can also initialize the lua_shared_dict shm storage at this phase.
  330
+    Here is an example for this:
  331
+
  332
+        lua_shared_dict dogs 1m;
  333
+
  334
+        init_by_lua '
  335
+            local dogs = ngx.shared.dogs;
  336
+            dogs:set("Tom", 56)
  337
+        ';
  338
+
  339
+        server {
  340
+            location = /api {
  341
+                content_by_lua '
  342
+                    local dogs = ngx.shared.dogs;
  343
+                    ngx.say(dogs:get("Tom"))
  344
+                ';
  345
+            }
  346
+        }
  347
+
  348
+    But note that, the lua_shared_dict's shm storage will not be cleared
  349
+    through a config reload (via the "HUP" signal, for example). So if you
  350
+    do *not* want to re-initialize the shm storage in your "init_by_lua"
  351
+    code in this case, then you just need to set a custom flag in the shm
  352
+    storage and always check the flag in your "init_by_lua" code.
  353
+
  354
+    Because the Lua code in this context runs before Nginx forks its worker
  355
+    processes (if any), data or code loaded here will enjoy the
  356
+    Copy-on-write (COW) (<http://en.wikipedia.org/wiki/Copy-on-write>)
  357
+    feature provided by many operating systems among all the worker
  358
+    processes, thus saving a lot of memory.
  359
+
  360
+    Only a small set of the Nginx API for Lua is supported in this context:
  361
+
  362
+    *   Logging APIs: ngx.log and print,
  363
+
  364
+    *   Shared Dictionary API: ngx.shared.DICT.
  365
+
  366
+    More Nginx APIs for Lua may be supported in this context upon future
  367
+    user requests.
  368
+
  369
+    Basically you can safely use Lua libraries that do blocking I/O in this
  370
+    very context because blocking the master process during server start-up
  371
+    is completely okay. Even the Nginx core does blocking I/O (at least on
  372
+    resolving upstream's host names) at the configure-loading phase.
  373
+
  374
+    You should be very careful about potential security vulnerabilities in
  375
+    your Lua code registered in this context because the Nginx master
  376
+    process is often run under the "root" account.
  377
+
  378
+    This directive was first introduced in the "v0.5.5" release.
  379
+
  380
+  init_by_lua_file
  381
+    syntax: *init_by_lua_file <path-to-lua-script-file>*
  382
+
  383
+    context: *http*
  384
+
  385
+    phase: *loading-config*
  386
+
  387
+    Equivalent to init_by_lua, except that the file specified by
  388
+    "<path-to-lua-script-file>" contains the Lua code (or the Lua raw
  389
+    bytecode) to be executed.
  390
+
  391
+    When a relative path like "foo/bar.lua" is given, they will be turned
  392
+    into the absolute path relative to the "server prefix" path determined
  393
+    by the "-p PATH" command-line option while starting the Nginx server.
  394
+
  395
+    This directive was first introduced in the "v0.5.5" release.
  396
+
300 397
   set_by_lua
301 398
     syntax: *set_by_lua $res <lua-script-str> [$arg1 $arg2 ...]*
302 399
 
@@ -1291,8 +1388,9 @@ Nginx API for Lua
1291 1388
         ngx.var.args = nil
1292 1389
 
1293 1390
   Core constants
1294  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
1295  
-    header_filter_by_lua*, body_filter_by_lua, *log_by_lua**
  1391
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  1392
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua,
  1393
+    *log_by_lua**
1296 1394
 
1297 1395
       ngx.OK (0)
1298 1396
       ngx.ERROR (-1)
@@ -1316,8 +1414,8 @@ Nginx API for Lua
1316 1414
     release.
1317 1415
 
1318 1416
   HTTP method constants
1319  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
1320  
-    header_filter_by_lua*, body_filter_by_lua, log_by_lua**
  1417
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  1418
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua**
1321 1419
 
1322 1420
       ngx.HTTP_GET
1323 1421
       ngx.HTTP_HEAD
@@ -1330,8 +1428,8 @@ Nginx API for Lua
1330 1428
     ngx.location.capture_multi method calls.
1331 1429
 
1332 1430
   HTTP status constants
1333  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
1334  
-    header_filter_by_lua*, body_filter_by_lua, log_by_lua**
  1431
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  1432
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua**
1335 1433
 
1336 1434
       value = ngx.HTTP_OK (200)
1337 1435
       value = ngx.HTTP_CREATED (201)
@@ -1370,8 +1468,8 @@ Nginx API for Lua
1370 1468
   print
1371 1469
     syntax: *print(...)*
1372 1470
 
1373  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
1374  
-    header_filter_by_lua*, body_filter_by_lua, log_by_lua**
  1471
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  1472
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua**
1375 1473
 
1376 1474
     Writes argument values into the nginx "error.log" file with the
1377 1475
     "ngx.NOTICE" log level.
@@ -2675,8 +2773,9 @@ Nginx API for Lua
2675 2773
   ngx.log
2676 2774
     syntax: *ngx.log(log_level, ...)*
2677 2775
 
2678  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
2679  
-    header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  2776
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  2777
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
  2778
+    log_by_lua**
2680 2779
 
2681 2780
     Log arguments concatenated to error.log with the given logging level.
2682 2781
 
@@ -3374,8 +3473,9 @@ Nginx API for Lua
3374 3473
   ngx.shared.DICT
3375 3474
     syntax: *dict = ngx.shared.DICT*
3376 3475
 
3377  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
3378  
-    header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3476
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  3477
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
  3478
+    log_by_lua**
3379 3479
 
3380 3480
     Fetching the shm-based Lua dictionary object for the shared memory zone
3381 3481
     named "DICT" defined by the lua_shared_dict directive.
@@ -3480,8 +3580,9 @@ Nginx API for Lua
3480 3580
     syntax: *success, err, forcible = ngx.shared.DICT:set(key, value,
3481 3581
     exptime?, flags?)*
3482 3582
 
3483  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
3484  
-    header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3583
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  3584
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
  3585
+    log_by_lua**
3485 3586
 
3486 3587
     Unconditionally sets a key-value pair into the shm-based dictionary
3487 3588
     ngx.shared.DICT. Returns three values:
@@ -3546,8 +3647,9 @@ Nginx API for Lua
3546 3647
     syntax: *success, err, forcible = ngx.shared.DICT:add(key, value,
3547 3648
     exptime?, flags?)*
3548 3649
 
3549  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
3550  
-    header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3650
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  3651
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
  3652
+    log_by_lua**
3551 3653
 
3552 3654
     Just like the set method, but only stores the key-value pair into the
3553 3655
     dictionary ngx.shared.DICT if the key does *not* exist.
@@ -3564,8 +3666,9 @@ Nginx API for Lua
3564 3666
     syntax: *success, err, forcible = ngx.shared.DICT:replace(key, value,
3565 3667
     exptime?, flags?)*
3566 3668
 
3567  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
3568  
-    header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3669
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  3670
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
  3671
+    log_by_lua**
3569 3672
 
3570 3673
     Just like the set method, but only stores the key-value pair into the
3571 3674
     dictionary ngx.shared.DICT if the key *does* exist.
@@ -3581,8 +3684,9 @@ Nginx API for Lua
3581 3684
   ngx.shared.DICT.delete
3582 3685
     syntax: *ngx.shared.DICT:delete(key)*
3583 3686
 
3584  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
3585  
-    header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3687
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  3688
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
  3689
+    log_by_lua**
3586 3690
 
3587 3691
     Unconditionally removes the key-value pair from the shm-based dictionary
3588 3692
     ngx.shared.DICT.
@@ -3596,8 +3700,9 @@ Nginx API for Lua
3596 3700
   ngx.shared.DICT.incr
3597 3701
     syntax: *newval, err = ngx.shared.DICT:incr(key, value)*
3598 3702
 
3599  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
3600  
-    header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3703
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  3704
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
  3705
+    log_by_lua**
3601 3706
 
3602 3707
     Increments the (numerical) value for "key" in the shm-based dictionary
3603 3708
     ngx.shared.DICT by the step value "value". Returns the new resulting
@@ -3620,8 +3725,9 @@ Nginx API for Lua
3620 3725
   ngx.shared.DICT.flush_all
3621 3726
     syntax: *ngx.shared.DICT:flush_all()*
3622 3727
 
3623  
-    context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
3624  
-    header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3728
+    context: *init_by_lua*, set_by_lua*, rewrite_by_lua*, access_by_lua*,
  3729
+    content_by_lua*, header_filter_by_lua*, body_filter_by_lua*,
  3730
+    log_by_lua**
3625 3731
 
3626 3732
     Flushes out all the items in the dictionary.
3627 3733
 
105  README.markdown
Source Rendered
@@ -18,7 +18,7 @@ This module is under active development and is production ready.
18 18
 Version
19 19
 =======
20 20
 
21  
-This document describes ngx_lua [v0.5.4](https://github.com/chaoslawful/lua-nginx-module/tags) released on 28 June 2012.
  21
+This document describes ngx_lua [v0.5.5](https://github.com/chaoslawful/lua-nginx-module/tags) released on 4 July 2012.
22 22
 
23 23
 Synopsis
24 24
 ========
@@ -289,6 +289,85 @@ can be used to stand for the original cpath.
289 289
 
290 290
 Since the `v0.5.0rc29` release, the special notation `$prefix` or `${prefix}` can be used in the search path string to indicate the path of the `server prefix` usually determined by the `-p PATH` command-line option while starting the Nginx server.
291 291
 
  292
+init_by_lua
  293
+-----------
  294
+
  295
+**syntax:** *init_by_lua &lt;lua-script-str&gt;*
  296
+
  297
+**context:** *http*
  298
+
  299
+**phase:** *loading-config*
  300
+
  301
+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.
  302
+
  303
+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.
  304
+
  305
+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:
  306
+
  307
+
  308
+    init_by_lua 'require "cjson"';
  309
+
  310
+    server {
  311
+        location = /api {
  312
+            content_by_lua '
  313
+                ngx.say(cjson.encode({dog = 5, cat = 6}))
  314
+            ';
  315
+        }
  316
+    }
  317
+
  318
+
  319
+You can also initialize the [lua_shared_dict](http://wiki.nginx.org/HttpLuaModule#lua_shared_dict) shm storage at this phase. Here is an example for this:
  320
+
  321
+
  322
+    lua_shared_dict dogs 1m;
  323
+
  324
+    init_by_lua '
  325
+        local dogs = ngx.shared.dogs;
  326
+        dogs:set("Tom", 56)
  327
+    ';
  328
+
  329
+    server {
  330
+        location = /api {
  331
+            content_by_lua '
  332
+                local dogs = ngx.shared.dogs;
  333
+                ngx.say(dogs:get("Tom"))
  334
+            ';
  335
+        }
  336
+    }
  337
+
  338
+
  339
+But note that, the [lua_shared_dict](http://wiki.nginx.org/HttpLuaModule#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.
  340
+
  341
+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.
  342
+
  343
+Only a small set of the [Nginx API for Lua](http://wiki.nginx.org/HttpLuaModule#Nginx_API_for_Lua) is supported in this context:
  344
+
  345
+* Logging APIs: [ngx.log](http://wiki.nginx.org/HttpLuaModule#ngx.log) and [print](http://wiki.nginx.org/HttpLuaModule#print),
  346
+* Shared Dictionary API: [ngx.shared.DICT](http://wiki.nginx.org/HttpLuaModule#ngx.shared.DICT).
  347
+
  348
+More Nginx APIs for Lua may be supported in this context upon future user requests.
  349
+
  350
+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.
  351
+
  352
+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.
  353
+
  354
+This directive was first introduced in the `v0.5.5` release.
  355
+
  356
+init_by_lua_file
  357
+----------------
  358
+
  359
+**syntax:** *init_by_lua_file &lt;path-to-lua-script-file&gt;*
  360
+
  361
+**context:** *http*
  362
+
  363
+**phase:** *loading-config*
  364
+
  365
+Equivalent to [init_by_lua](http://wiki.nginx.org/HttpLuaModule#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.
  366
+
  367
+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.
  368
+
  369
+This directive was first introduced in the `v0.5.5` release.
  370
+
292 371
 set_by_lua
293 372
 ----------
294 373
 
@@ -1165,7 +1244,7 @@ Setting `ngx.var.Foo` to a `nil` value will unset the `$Foo` Nginx variable.
1165 1244
 
1166 1245
 Core constants
1167 1246
 --------------
1168  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, *log_by_lua**
  1247
+**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**
1169 1248
 
1170 1249
 
1171 1250
       ngx.OK (0)
@@ -1187,7 +1266,7 @@ The `ngx.DECLINED` constant was first introduced in the `v0.5.0rc19` release.
1187 1266
 
1188 1267
 HTTP method constants
1189 1268
 ---------------------
1190  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua**
  1269
+**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**
1191 1270
 
1192 1271
 
1193 1272
       ngx.HTTP_GET
@@ -1202,7 +1281,7 @@ These constants are usually used in [ngx.location.capture](http://wiki.nginx.org
1202 1281
 
1203 1282
 HTTP status constants
1204 1283
 ---------------------
1205  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua**
  1284
+**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**
1206 1285
 
1207 1286
 
1208 1287
       value = ngx.HTTP_OK (200)
@@ -1246,7 +1325,7 @@ print
1246 1325
 -----
1247 1326
 **syntax:** *print(...)*
1248 1327
 
1249  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua**
  1328
+**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**
1250 1329
 
1251 1330
 Writes argument values into the nginx `error.log` file with the `ngx.NOTICE` log level.
1252 1331
 
@@ -2523,7 +2602,7 @@ ngx.log
2523 2602
 -------
2524 2603
 **syntax:** *ngx.log(log_level, ...)*
2525 2604
 
2526  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  2605
+**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**
2527 2606
 
2528 2607
 Log arguments concatenated to error.log with the given logging level.
2529 2608
 
@@ -3174,7 +3253,7 @@ ngx.shared.DICT
3174 3253
 ---------------
3175 3254
 **syntax:** *dict = ngx.shared.DICT*
3176 3255
 
3177  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3256
+**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**
3178 3257
 
3179 3258
 Fetching the shm-based Lua dictionary object for the shared memory zone named `DICT` defined by the [lua_shared_dict](http://wiki.nginx.org/HttpLuaModule#lua_shared_dict) directive.
3180 3259
 
@@ -3268,7 +3347,7 @@ ngx.shared.DICT.set
3268 3347
 -------------------
3269 3348
 **syntax:** *success, err, forcible = ngx.shared.DICT:set(key, value, exptime?, flags?)*
3270 3349
 
3271  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3350
+**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**
3272 3351
 
3273 3352
 Unconditionally sets a key-value pair into the shm-based dictionary [ngx.shared.DICT](http://wiki.nginx.org/HttpLuaModule#ngx.shared.DICT). Returns three values:
3274 3353
 
@@ -3310,7 +3389,7 @@ ngx.shared.DICT.add
3310 3389
 -------------------
3311 3390
 **syntax:** *success, err, forcible = ngx.shared.DICT:add(key, value, exptime?, flags?)*
3312 3391
 
3313  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3392
+**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**
3314 3393
 
3315 3394
 Just like the [set](http://wiki.nginx.org/HttpLuaModule#ngx.shared.DICT.set) method, but only stores the key-value pair into the dictionary [ngx.shared.DICT](http://wiki.nginx.org/HttpLuaModule#ngx.shared.DICT) if the key does *not* exist.
3316 3395
 
@@ -3324,7 +3403,7 @@ ngx.shared.DICT.replace
3324 3403
 -----------------------
3325 3404
 **syntax:** *success, err, forcible = ngx.shared.DICT:replace(key, value, exptime?, flags?)*
3326 3405
 
3327  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3406
+**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**
3328 3407
 
3329 3408
 Just like the [set](http://wiki.nginx.org/HttpLuaModule#ngx.shared.DICT.set) method, but only stores the key-value pair into the dictionary [ngx.shared.DICT](http://wiki.nginx.org/HttpLuaModule#ngx.shared.DICT) if the key *does* exist.
3330 3409
 
@@ -3338,7 +3417,7 @@ ngx.shared.DICT.delete
3338 3417
 ----------------------
3339 3418
 **syntax:** *ngx.shared.DICT:delete(key)*
3340 3419
 
3341  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3420
+**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**
3342 3421
 
3343 3422
 Unconditionally removes the key-value pair from the shm-based dictionary [ngx.shared.DICT](http://wiki.nginx.org/HttpLuaModule#ngx.shared.DICT).
3344 3423
 
@@ -3352,7 +3431,7 @@ ngx.shared.DICT.incr
3352 3431
 --------------------
3353 3432
 **syntax:** *newval, err = ngx.shared.DICT:incr(key, value)*
3354 3433
 
3355  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3434
+**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**
3356 3435
 
3357 3436
 Increments the (numerical) value for `key` in the shm-based dictionary [ngx.shared.DICT](http://wiki.nginx.org/HttpLuaModule#ngx.shared.DICT) by the step value `value`. Returns the new resulting number if the operation is successfully completed or `nil` and an error message otherwise.
3358 3437
 
@@ -3370,7 +3449,7 @@ ngx.shared.DICT.flush_all
3370 3449
 -------------------------
3371 3450
 **syntax:** *ngx.shared.DICT:flush_all()*
3372 3451
 
3373  
-**context:** *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua**
  3452
+**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**
3374 3453
 
3375 3454
 Flushes out all the items in the dictionary.
3376 3455
 
103  doc/HttpLuaModule.wiki
Source Rendered
@@ -10,7 +10,7 @@ This module is under active development and is production ready.
10 10
 
11 11
 = Version =
12 12
 
13  
-This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.4] released on 28 June 2012.
  13
+This document describes ngx_lua [https://github.com/chaoslawful/lua-nginx-module/tags v0.5.5] released on 4 July 2012.
14 14
 
15 15
 = Synopsis =
16 16
 <geshi lang="nginx">
@@ -274,6 +274,83 @@ can be used to stand for the original cpath.
274 274
 
275 275
 Since the <code>v0.5.0rc29</code> release, the special notation <code>$prefix</code> or <code>${prefix}</code> can be used in the search path string to indicate the path of the <code>server prefix</code> usually determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
276 276
 
  277
+== init_by_lua ==
  278
+
  279
+'''syntax:''' ''init_by_lua <lua-script-str>''
  280
+
  281
+'''context:''' ''http''
  282
+
  283
+'''phase:''' ''loading-config''
  284
+
  285
+Runs the Lua code specified by the argument <code><lua-script-str></code> on the global Lua VM level when the Nginx master process (if any) is loading the Nginx config file.
  286
+
  287
+When Nginx receives the <code>HUP</code> signal and starts reloading the config file, the Lua VM will also be re-created and <code>init_by_lua</code> will run again on the new Lua VM.
  288
+
  289
+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:
  290
+
  291
+<geshi lang="nginx">
  292
+    init_by_lua 'require "cjson"';
  293
+
  294
+    server {
  295
+        location = /api {
  296
+            content_by_lua '
  297
+                ngx.say(cjson.encode({dog = 5, cat = 6}))
  298
+            ';
  299
+        }
  300
+    }
  301
+</geshi>
  302
+
  303
+You can also initialize the [[#lua_shared_dict|lua_shared_dict]] shm storage at this phase. Here is an example for this:
  304
+
  305
+<geshi lang="nginx">
  306
+    lua_shared_dict dogs 1m;
  307
+
  308
+    init_by_lua '
  309
+        local dogs = ngx.shared.dogs;
  310
+        dogs:set("Tom", 56)
  311
+    ';
  312
+
  313
+    server {
  314
+        location = /api {
  315
+            content_by_lua '
  316
+                local dogs = ngx.shared.dogs;
  317
+                ngx.say(dogs:get("Tom"))
  318
+            ';
  319
+        }
  320
+    }
  321
+</geshi>
  322
+
  323
+But note that, the [[#lua_shared_dict|lua_shared_dict]]'s shm storage will not be cleared through a config reload (via the <code>HUP</code> signal, for example). So if you do ''not'' want to re-initialize the shm storage in your <code>init_by_lua</code> code in this case, then you just need to set a custom flag in the shm storage and always check the flag in your <code>init_by_lua</code> code.
  324
+
  325
+Because the Lua code in this context runs before Nginx forks its worker processes (if any), data or code loaded here will enjoy the [http://en.wikipedia.org/wiki/Copy-on-write Copy-on-write (COW)] feature provided by many operating systems among all the worker processes, thus saving a lot of memory.
  326
+
  327
+Only a small set of the [[#Nginx API for Lua|Nginx API for Lua]] is supported in this context:
  328
+
  329
+* Logging APIs: [[#ngx.log|ngx.log]] and [[#print|print]],
  330
+* Shared Dictionary API: [[#ngx.shared.DICT|ngx.shared.DICT]].
  331
+
  332
+More Nginx APIs for Lua may be supported in this context upon future user requests.
  333
+
  334
+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.
  335
+
  336
+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 <code>root</code> account.
  337
+
  338
+This directive was first introduced in the <code>v0.5.5</code> release.
  339
+
  340
+== init_by_lua_file ==
  341
+
  342
+'''syntax:''' ''init_by_lua_file <path-to-lua-script-file>''
  343
+
  344
+'''context:''' ''http''
  345
+
  346
+'''phase:''' ''loading-config''
  347
+
  348
+Equivalent to [[#init_by_lua|init_by_lua]], except that the file specified by <code><path-to-lua-script-file></code> contains the Lua code (or the Lua raw bytecode) to be executed.
  349
+
  350
+When a relative path like <code>foo/bar.lua</code> is given, they will be turned into the absolute path relative to the <code>server prefix</code> path determined by the <code>-p PATH</code> command-line option while starting the Nginx server.
  351
+
  352
+This directive was first introduced in the <code>v0.5.5</code> release.
  353
+
277 354
 == set_by_lua ==
278 355
 
279 356
 '''syntax:''' ''set_by_lua $res <lua-script-str> [$arg1 $arg2 ...]''
@@ -1119,7 +1196,7 @@ Setting <code>ngx.var.Foo</code> to a <code>nil</code> value will unset the <cod
1119 1196
 </geshi>
1120 1197
 
1121 1198
 == Core constants ==
1122  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, *log_by_lua*''
  1199
+'''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*''
1123 1200
 
1124 1201
 <geshi lang="lua">
1125 1202
   ngx.OK (0)
@@ -1140,7 +1217,7 @@ The <code>ngx.null</code> constant is a <code>NULL</code> light userdata usually
1140 1217
 The <code>ngx.DECLINED</code> constant was first introduced in the <code>v0.5.0rc19</code> release.
1141 1218
 
1142 1219
 == HTTP method constants ==
1143  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*''
  1220
+'''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*''
1144 1221
 
1145 1222
 <geshi lang="text">
1146 1223
   ngx.HTTP_GET
@@ -1154,7 +1231,7 @@ The <code>ngx.DECLINED</code> constant was first introduced in the <code>v0.5.0r
1154 1231
 These constants are usually used in [[#ngx.location.capture|ngx.location.capture]] and [[#ngx.location.capture_multi|ngx.location.capture_multi]] method calls.
1155 1232
 
1156 1233
 == HTTP status constants ==
1157  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*''
  1234
+'''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*''
1158 1235
 
1159 1236
 <geshi lang="nginx">
1160 1237
   value = ngx.HTTP_OK (200)
@@ -1196,7 +1273,7 @@ These constants are usually used by the [[#ngx.log|ngx.log]] method.
1196 1273
 == print ==
1197 1274
 '''syntax:''' ''print(...)''
1198 1275
 
1199  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*''
  1276
+'''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*''
1200 1277
 
1201 1278
 Writes argument values into the nginx <code>error.log</code> file with the <code>ngx.NOTICE</code> log level.
1202 1279
 
@@ -2447,7 +2524,7 @@ Just as [[#ngx.print|ngx.print]] but also emit a trailing newline.
2447 2524
 == ngx.log ==
2448 2525
 '''syntax:''' ''ngx.log(log_level, ...)''
2449 2526
 
2450  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
  2527
+'''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*''
2451 2528
 
2452 2529
 Log arguments concatenated to error.log with the given logging level.
2453 2530
 
@@ -3067,7 +3144,7 @@ This feature was first introduced in the <code>v0.2.1rc15</code> release.
3067 3144
 == ngx.shared.DICT ==
3068 3145
 '''syntax:''' ''dict = ngx.shared.DICT''
3069 3146
 
3070  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
  3147
+'''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*''
3071 3148
 
3072 3149
 Fetching the shm-based Lua dictionary object for the shared memory zone named <code>DICT</code> defined by the [[#lua_shared_dict|lua_shared_dict]] directive.
3073 3150
 
@@ -3159,7 +3236,7 @@ See also [[#ngx.shared.DICT|ngx.shared.DICT]].
3159 3236
 == ngx.shared.DICT.set ==
3160 3237
 '''syntax:''' ''success, err, forcible = ngx.shared.DICT:set(key, value, exptime?, flags?)''
3161 3238
 
3162  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
  3239
+'''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*''
3163 3240
 
3164 3241
 Unconditionally sets a key-value pair into the shm-based dictionary [[#ngx.shared.DICT|ngx.shared.DICT]]. Returns three values:
3165 3242
 
@@ -3200,7 +3277,7 @@ See also [[#ngx.shared.DICT|ngx.shared.DICT]].
3200 3277
 == ngx.shared.DICT.add ==
3201 3278
 '''syntax:''' ''success, err, forcible = ngx.shared.DICT:add(key, value, exptime?, flags?)''
3202 3279
 
3203  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
  3280
+'''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*''
3204 3281
 
3205 3282
 Just like the [[#ngx.shared.DICT.set|set]] method, but only stores the key-value pair into the dictionary [[#ngx.shared.DICT|ngx.shared.DICT]] if the key does ''not'' exist.
3206 3283
 
@@ -3213,7 +3290,7 @@ See also [[#ngx.shared.DICT|ngx.shared.DICT]].
3213 3290
 == ngx.shared.DICT.replace ==
3214 3291
 '''syntax:''' ''success, err, forcible = ngx.shared.DICT:replace(key, value, exptime?, flags?)''
3215 3292
 
3216  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
  3293
+'''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*''
3217 3294
 
3218 3295
 Just like the [[#ngx.shared.DICT.set|set]] method, but only stores the key-value pair into the dictionary [[#ngx.shared.DICT|ngx.shared.DICT]] if the key ''does'' exist.
3219 3296
 
@@ -3226,7 +3303,7 @@ See also [[#ngx.shared.DICT|ngx.shared.DICT]].
3226 3303
 == ngx.shared.DICT.delete ==
3227 3304
 '''syntax:''' ''ngx.shared.DICT:delete(key)''
3228 3305
 
3229  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
  3306
+'''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*''
3230 3307
 
3231 3308
 Unconditionally removes the key-value pair from the shm-based dictionary [[#ngx.shared.DICT|ngx.shared.DICT]].
3232 3309
 
@@ -3239,7 +3316,7 @@ See also [[#ngx.shared.DICT|ngx.shared.DICT]].
3239 3316
 == ngx.shared.DICT.incr ==
3240 3317
 '''syntax:''' ''newval, err = ngx.shared.DICT:incr(key, value)''
3241 3318
 
3242  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
  3319
+'''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*''
3243 3320
 
3244 3321
 Increments the (numerical) value for <code>key</code> in the shm-based dictionary [[#ngx.shared.DICT|ngx.shared.DICT]] by the step value <code>value</code>. Returns the new resulting number if the operation is successfully completed or <code>nil</code> and an error message otherwise.
3245 3322
 
@@ -3256,7 +3333,7 @@ See also [[#ngx.shared.DICT|ngx.shared.DICT]].
3256 3333
 == ngx.shared.DICT.flush_all ==
3257 3334
 '''syntax:''' ''ngx.shared.DICT:flush_all()''
3258 3335
 
3259  
-'''context:''' ''set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*''
  3336
+'''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*''
3260 3337
 
3261 3338
 Flushes out all the items in the dictionary.
3262 3339
 

0 notes on commit 4275482

Please sign in to comment.
Something went wrong with that request. Please try again.