forked from openresty/lua-nginx-module
-
Notifications
You must be signed in to change notification settings - Fork 1
/
README
2628 lines (1882 loc) · 95.3 KB
/
README
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
Name
ngx_lua - Embed the power of Lua into Nginx
*This module is not distributed with the Nginx source.* See the
installation instructions.
Status
This module is under active development and is already production ready.
Version
This document describes ngx_lua v0.3.1rc18
(<https://github.com/chaoslawful/lua-nginx-module/tags>) released on 21
October 2011.
Synopsis
# set search paths for pure Lua external libraries (';;' is the default path):
lua_package_path '/foo/bar/?.lua;/blah/?.lua;;';
# set search paths for Lua external libraries written in C (can also use ';;'):
lua_package_cpath '/bar/baz/?.so;/blah/blah/?.so;;';
server {
location /inline_concat {
# MIME type determined by default_type:
default_type 'text/plain';
set $a "hello";
set $b "world";
# inline lua script
set_by_lua $res "return ngx.arg[1]..ngx.arg[2]" $a $b;
echo $res;
}
location /rel_file_concat {
set $a "foo";
set $b "bar";
# script path relative to nginx prefix
# $ngx_prefix/conf/concat.lua contents:
#
# return ngx.arg[1]..ngx.arg[2]
#
set_by_lua_file $res conf/concat.lua $a $b;
echo $res;
}
location /abs_file_concat {
set $a "fee";
set $b "baz";
# absolute script path not modified
set_by_lua_file $res /usr/nginx/conf/concat.lua $a $b;
echo $res;
}
location /lua_content {
# MIME type determined by default_type:
default_type 'text/plain';
content_by_lua "ngx.say('Hello,world!')"
}
location /nginx_var {
# MIME type determined by default_type:
default_type 'text/plain';
# try access /nginx_var?a=hello,world
content_by_lua "ngx.print(ngx.var['arg_a'], '\\n')";
}
location /request_body {
# force reading request body (default off)
lua_need_request_body on;
client_max_body_size 50k;
client_body_buffer_size 50k;
content_by_lua 'ngx.print(ngx.var.request_body)';
}
# transparent non-blocking I/O in Lua via subrequests
location /lua {
# MIME type determined by default_type:
default_type 'text/plain';
content_by_lua '
local res = ngx.location.capture("/some_other_location")
if res.status == 200 then
ngx.print(res.body)
end';
}
# GET /recur?num=5
location /recur {
# MIME type determined by default_type:
default_type 'text/plain';
content_by_lua '
local num = tonumber(ngx.var.arg_num) or 0
ngx.say("num is: ", num)
if num > 0 then
res = ngx.location.capture("/recur?num=" .. tostring(num - 1))
ngx.print("status=", res.status, " ")
ngx.print("body=", res.body)
else
ngx.say("end")
end
';
}
location /foo {
rewrite_by_lua '
res = ngx.location.capture("/memc",
{ args = { cmd = 'incr', key = ngx.var.uri } }
)
';
proxy_pass http://blah.blah.com;
}
location /blah {
access_by_lua '
local res = ngx.location.capture("/auth")
if res.status == ngx.HTTP_OK then
return
end
if res.status == ngx.HTTP_FORBIDDEN then
ngx.exit(res.status)
end
ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
';
# proxy_pass/fastcgi_pass/postgres_pass/...
}
location /mixed {
rewrite_by_lua_file /path/to/rewrite.lua;
access_by_lua_file /path/to/access.lua;
content_by_lua_file /path/to/content.lua;
}
# use nginx var in code path
# WARN: contents in nginx var must be carefully filtered,
# otherwise there'll be great security risk!
location ~ ^/app/(.+) {
content_by_lua_file /path/to/lua/app/root/$1.lua;
}
location / {
lua_need_request_body on;
client_max_body_size 100k;
client_body_buffer_size 100k;
access_by_lua '
-- check the client IP addr is in our black list
if ngx.var.remote_addr == "132.5.72.3" then
ngx.exit(ngx.HTTP_FORBIDDEN)
end
-- check if the request body contains bad words
if ngx.var.request_body and
string.match(ngx.var.request_body, "fsck")
then
return ngx.redirect("/terms_of_use.html")
end
-- tests passed
';
# proxy_pass/fastcgi_pass/etc settings
}
}
Description
This module embeds the Lua interpreter or LuaJIT into the nginx core and
integrates the powerful Lua threads (aka Lua coroutines) into the nginx
event model by means of nginx subrequests.
Unlike Apache's mod_lua
(<http://httpd.apache.org/docs/2.3/mod/mod_lua.html>) and Lighttpd's
mod_magnet (<http://redmine.lighttpd.net/wiki/1/Docs:ModMagnet>), Lua
code written atop this module can be *100% non-blocking* on network
traffic as long as you use the ngx.location.capture or
ngx.location.capture_multi interfaces to let the nginx core do all your
requests to mysql, postgresql, memcached, redis, upstream http web
services, and etc etc etc (see [[HttpDrizzleModule]], ngx_postgres
(<http://github.com/FRiCKLE/ngx_postgres/>), [[HttpMemcModule]],
[[HttpRedis2Module]] and [[HttpProxyModule]] modules for details).
The Lua interpreter instance is shared across all the requests in a
single nginx worker process.
Request contexts are isolated from each other by means of Lua
(lightweight) threads (aka Lua coroutines). And Lua modules loaded are
persistent on the nginx worker process level. So the memory footprint is
quite small even when your nginx worker process is handling 10K requests
at the same time.
Directives
lua_code_cache
syntax: *lua_code_cache on | off*
default: *lua_code_cache on*
context: *main, server, location, location if*
Enable or disable the Lua code cache for set_by_lua_file,
content_by_lua_file, rewrite_by_lua_file, and access_by_lua_file, and
also force Lua module reloading on a per-request basis.
The Lua files referenced in set_by_lua_file, content_by_lua_file,
access_by_lua_file, and rewrite_by_lua_file won't be cached at all, and
Lua's "package.loaded" table will be cleared at every request's entry
point (such that Lua modules won't be cached either). So developers and
enjoy the PHP-way, i.e., edit-and-refresh.
But please note that Lua code inlined into nginx.conf like those
specified by set_by_lua, content_by_lua, access_by_lua, and
rewrite_by_lua will *always* be cached because only nginx knows how to
parse "nginx.conf" and the only way to tell it to re-load the config
file is to send a "HUP" signal to it or just to restart it from scratch.
For now, ngx_lua does not support the "stat" mode like Apache's
"mod_lua", but we will work on it in the future.
Disabling the Lua code cache is mainly used for Lua development only
because it has great impact on the over-all performance and is strongly
discouraged for production uses. Also, race conditions when reloading
Lua modules are common for concurrent requests when the code cache is
off.
lua_regex_cache_max_entries
syntax: *lua_regex_cache_max_entries <num>*
default: *lua_regex_cache_max_entries 1024*
context: *http*
Specifies the maximal entries allowed in the worker-process-level
compiled-regex cache.
The regular expressions used in ngx.re.match, ngx.re.gmatch, ngx.re.sub,
and ngx.re.gsub will be cached in this cache if the regex option "o"
(i.e., compile-once flag) is specified.
The default entries allowed is 1024.
When the user Lua programs are exceeding this limit, those new regexes
will not be cached at all (as if no "o" option is ever specified), and
there will be one (and only one) warning in nginx's "error.log" file,
like this 2011/08/27 23:18:26 [warn] 31997#0: *1 lua exceeding regex
cache max entries (1024), ...
You shouldn't specify the "o" regex option for regexes (and/or "replace"
string arguments for ngx.re.sub and ngx.re.gsub) that are generated *on
the fly* and give rise to infinite variations, or you'll quickly reach
the limit specified here.
lua_package_path
syntax: *lua_package_path <lua-style-path-str>*
default: *The content of LUA_PATH environ variable or Lua's compiled-in
defaults.*
context: *main*
Set the Lua module searching path used by scripts specified by
set_by_lua, content_by_lua and others. The path string is in standard
Lua path form, and ";;" can be used to stand for the original path.
lua_package_cpath
syntax: *lua_package_cpath <lua-style-cpath-str>*
default: *The content of LUA_CPATH environ variable or Lua's compiled-in
defaults.*
context: *main*
Set the Lua C-module searching path used by scripts specified by
set_by_lua, content_by_lua and others. The cpath string is in standard
Lua cpath form, and ";;" can be used to stand for the original cpath.
set_by_lua
syntax: *set_by_lua $res <lua-script-str> [$arg1 $arg2 ...]*
context: *main, server, location, server if, location if*
phase: *rewrite*
Execute user code specified by "<lua-script-str>" with input arguments
"$arg1 $arg2 ...", and set the script's return value to $res in string
form. In "<lua-script-str>" code the input arguments can be retrieved
from "ngx.arg" table (index starts from 1 and increased sequentially).
set_by_lua directives are designed to execute small and quick codes.
Nginx event loop is blocked during the code execution, so you'd better
not call anything that may be blocked or time-consuming.
Note that set_by_lua can only output a value to a single Nginx variable
at a time. But a work-around is also available by means of the
ngx.var.VARIABLE interface, for example, location /foo { set $diff ''; #
we have to predefine the $diff variable here
set_by_lua $sum '
local a = 32
local b = 56
ngx.var.diff = a - b; -- write to $diff directly
return a + b; -- return the $sum value normally
';
echo "sum = $sum, diff = $diff";
}
This directive can be freely mixed with all the directives of
[[HttpRewriteModule]], [[HttpSetMiscModule]], and
[[HttpArrayVarModule]]. All of these directives will run in exactly the
same order that they are written in the config file. For example, set
$foo 32; set_by_lua $bar 'tonumber(ngx.var.foo) + 1'; set $baz "bar:
$bar"; # $baz == "bar: 33"
This directive requires the ngx_devel_kit
(<https://github.com/simpl/ngx_devel_kit>) module.
set_by_lua_file
syntax: *set_by_lua_file $res <path-to-lua-script> [$arg1 $arg2 ...]*
context: *main, server, location, server if, location if*
phase: *rewrite*
Basically the same as set_by_lua, except the code to be executed is in
the file specified by "<path-lua-script>".
When the Lua code cache is on (this is the default), the user code is
loaded once at the first request and cached. Nginx config must be
reloaded if you modified the file and expected to see updated behavior.
You can disable the Lua code cache by setting "lua_code_cache off;" in
your nginx.conf.
This directive requires the ngx_devel_kit
(<https://github.com/simpl/ngx_devel_kit>) module.
content_by_lua
syntax: *content_by_lua <lua-script-str>*
context: *location, location if*
phase: *content*
Act as a content handler and execute user code specified by
"<lua-script-str>" for every request. The user code may call predefined
APIs to generate response content.
The use code is executed in a new spawned coroutine with independent
global environment (i.e. a sandbox).
Do not use this directive and other content handler directives in a same
location. For example, it's bad to use this directive with a proxy_pass
directive in the same location.
content_by_lua_file
syntax: *content_by_lua_file <path-to-lua-script>*
context: *location, location if*
phase: *content*
Basically the same as content_by_lua, except the code to be executed is
in the file specified by "<path-lua-script>".
Nginx variables can be used in "<path-to-lua-script>" string, in order
to provide greater flexibility in practice. But this feature must be
used carefully, so is not recommend for beginners.
When the Lua code cache is on (this is the default), the user code is
loaded once at the first request and cached. Nginx config must be
reloaded if you modified the file and expected to see updated behavior.
You can disable the Lua code cache by setting lua_code_cache "off" in
your "nginx.conf" file.
rewrite_by_lua
syntax: *rewrite_by_lua <lua-script-str>*
context: *http, server, location, location if*
phase: *post-rewrite*
Act as a rewrite phase handler and execute user code specified by
"<lua-script-str>" for every request. The user code may call predefined
APIs to generate response content.
This hook uses exactly the same mechamism as content_by_lua so all the
nginx APIs defined there are also available here.
Note that this handler always runs *after* the standard
[[HttpRewriteModule]]. So the following will work as expected:
location /foo {
set $a 12; # create and initialize $a
set $b ""; # create and initialize $b
rewrite_by_lua 'ngx.var.b = tonumber(ngx.var.a) + 1';
echo "res = $b";
}
because "set $a 12" and "set $b """ run *before* rewrite_by_lua.
On the other hand, the following will not work as expected:
? location /foo {
? set $a 12; # create and initialize $a
? set $b ''; # create and initialize $b
? rewrite_by_lua 'ngx.var.b = tonumber(ngx.var.a) + 1';
? if ($b = '13') {
? rewrite ^ /bar redirect;
? break;
? }
?
? echo "res = $b";
? }
because "if" runs *before* rewrite_by_lua even if it's put after
rewrite_by_lua in the config.
The right way of doing this is as follows:
location /foo {
set $a 12; # create and initialize $a
set $b ''; # create and initialize $b
rewrite_by_lua '
ngx.var.b = tonumber(ngx.var.a) + 1
if ngx.var.b == 13 then
return ngx.redirect("/bar");
end
';
echo "res = $b";
}
It's worth mentioning that, the "ngx_eval" module can be approximately
implemented by rewrite_by_lua. For example,
location / {
eval $res {
proxy_pass http://foo.com/check-spam;
}
if ($res = 'spam') {
rewrite ^ /terms-of-use.html redirect;
}
fastcgi_pass ...;
}
can be implemented in terms of "ngx_lua" like this
location = /check-spam {
internal;
proxy_pass http://foo.com/check-spam;
}
location / {
rewrite_by_lua '
local res = ngx.location.capture("/check-spam")
if res.body == "spam" then
ngx.redirect("/terms-of-use.html")
end
';
fastcgi_pass ...;
}
Just as any other rewrite phase handlers, rewrite_by_lua also runs in
subrequests.
Note that calling "ngx.exit(ngx.OK)" just returning from the current
rewrite_by_lua handler, and the nginx request processing control flow
will still continue to the content handler. To terminate the current
request from within the current rewrite_by_lua handler, calling ngx.exit
with status >= 200 ("ngx.HTTP_OK") and status < 300
("ngx.HTTP_SPECIAL_RESPONSE") for successful quits and
"ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)" (or its friends) for
failures.
If one uses [[HttpRewriteModule]]'s rewrite directive to change the URI
and initiate location re-lookups (kinda like internal redirections),
then rewrite_by_lua and rewrite_by_lua_file will be skipped altogether
in the current location. For example,
location /foo {
rewrite ^ /bar;
rewrite_by_lua 'ngx.exit(503)';
}
location /bar {
...
}
Here the Lua code "ngx.exit(503)" will never run while all the Lua code
(except access phase handlers) in the "/bar" location will not be
affected anyway. Similarly, "rewrite ^ /bar last" will also initiate a
location re-lookup. If you use the "break" modifier for the rewrite
directive, however, no location re-lookup will be triggered, and
therefore, the rewrite-phase Lua code will still be run as normal.
rewrite_by_lua_file
syntax: *rewrite_by_lua_file <path-to-lua-script>*
context: *http, server, location, location if*
phase: *post-rewrite*
Same as rewrite_by_lua, except the code to be executed is in the file
specified by "<path-lua-script>".
Nginx variables can be used in "<path-to-lua-script>" string, in order
to provide greater flexibility in practice. But this feature must be
used carefully, so is not recommend for beginners.
When the Lua code cache is on (this is the default), the user code is
loaded once at the first request and cached. Nginx config must be
reloaded if you modified the file and expected to see updated behavior.
You can disable the Lua code cache by setting lua_code_cache "off" in
your "nginx.conf" file.
access_by_lua
syntax: *access_by_lua <lua-script-str>*
context: *http, server, location, location if*
phase: *post-access*
Act as an access phase handler and execute user code specified by
"<lua-script-str>" for every request. The user code may call predefined
APIs to generate response content.
This hook uses exactly the same mechanism as content_by_lua so all the
nginx APIs defined there are also available here.
Note that this handler always runs *after* the standard
[[HttpAccessModule]]. So the following will work as expected:
location / {
deny 192.168.1.1;
allow 192.168.1.0/24;
allow 10.1.1.0/16;
deny all;
access_by_lua '
local res = ngx.location.capture("/mysql", { ... })
...
';
# proxy_pass/fastcgi_pass/...
}
That is, if a client address appears in the blacklist, then we don't
have to bother sending a MySQL query to do more advanced authentication
in access_by_lua.
It's worth mentioning that, the "ngx_auth_request" module can be
approximately implemented by access_by_lua. For example,
location / {
auth_request /auth;
# proxy_pass/fastcgi_pass/postgres_pass/...
}
can be implemented in terms of "ngx_lua" like this
location / {
access_by_lua '
local res = ngx.location.capture("/auth")
if res.status == ngx.HTTP_OK then
return
end
if res.status == ngx.HTTP_FORBIDDEN then
ngx.exit(res.status)
end
ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)
';
# proxy_pass/fastcgi_pass/postgres_pass/...
}
Just as any other access phase handlers, access_by_lua will *not* run in
subrequests.
Note that calling "ngx.exit(ngx.OK)" just returning from the current
access_by_lua handler, and the nginx request processing control flow
will still continue to the content handler. To terminate the current
request from within the current access_by_lua handler, calling
"ngx.exit(status)" where status >= 200 ("ngx.HTTP_OK") and status < 300
("ngx.HTTP_SPECIAL_RESPONSE") for successful quits and
"ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)" or its friends for failures.
access_by_lua_file
syntax: *access_by_lua_file <path-to-lua-script>*
context: *http, server, location, location if*
phase: *post-access*
Same as access_by_lua, except the code to be executed is in the file
specified by "<path-lua-script>".
Nginx variables can be used in "<path-to-lua-script>" string, in order
to provide greater flexibility in practice. But this feature must be
used carefully, so is not recommend for beginners.
When the Lua code cache is on (this is the default), the user code is
loaded once at the first request and cached. Nginx config must be
reloaded if you modified the file and expected to see updated behavior.
You can disable the Lua code cache by setting lua_code_cache "off" in
your "nginx.conf" file.
header_filter_by_lua
syntax: *header_filter_by_lua <lua-script-str>*
context: *http, server, location, location if*
phase: *output-header-filter*
Use Lua defined in "<lua-script-str>" to define an output header filter.
For now, the following Nginx Lua APIs are disabled in this context:
* Output API (e.g., ngx.say and ngx.send_headers)
* Control APIs (e.g., ngx.exit)
* Subrequest APIs (e.g., ngx.location.capture and
ngx.location.capture_multi)
Here's a small example of overriding a response header (or adding if it
does not exist) in our Lua header filter: location / { proxy_pass
http://mybackend; header_filter_by_lua 'ngx.header.Foo = "blah"'; }
This directive was first introduced in the "v0.2.1rc20" release.
header_filter_by_lua_file
syntax: *header_filter_by_lua_file <path-to-lua-script-file>*
context: *http, server, location, location if*
phase: *output-header-filter*
Use Lua code defined in a separate file specified by
"<path-to-lua-script-file>" to define an output header filter.
This is very much like header_filter_by_lua except that it loads Lua
code from an external Lua source file.
This directive was first introduced in the "v0.2.1rc20" release.
lua_need_request_body
syntax: *lua_need_request_body <on | off>*
default: *off*
context: *main | server | location*
phase: *depends on usage*
Force reading request body data or not. The client request body won't be
read, so you have to explicitly force reading the body if you need its
content.
If you want to read the request body data from the $request_body
variable, make sure that your have configured client_body_buffer_size to
have exactly the same value as client_max_body_size.
If the current location defines rewrite_by_lua or rewrite_by_lua_file,
then the request body will be read just before the rewrite_by_lua or
rewrite_by_lua_file code is run (and also at the "rewrite" phase).
Similarly, if only content_by_lua is specified, the request body won't
be read until the content handler's Lua code is about to run (i.e., the
request body will be read at the content phase).
You're recommended to use the ngx.req.read_body function and
ngx.req.discard_body for finer control over the request body reading
process though.
The same applies to access_by_lua and access_by_lua_file.
Nginx API for Lua
The Nginx API exposed to the Lua land is provided in the form of two
standard packages "ngx" and "ndk". These packages are in the default
global scope.
When you're writing your own external Lua modules, however, you can
introduce these packages by using the package.seeall
(<http://www.lua.org/manual/5.1/manual.html#pdf-package.seeall>) option:
module("my_module", package.seeall)
function say(a) ngx.say(a) end
Alternatively, import them to your Lua modules by using file-scoped
local Lua variables, like this:
local ngx = ngx
module("my_module")
function say(a) ngx.say(a) end
You can directly require the standard packages "ngx" and "ndk"
introduced by this Nginx module, like this:
local ngx = require "ngx"
local ndk = require "ndk"
The ability to require these packages was introduced in the "v0.2.1rc19"
release.
Network I/O operations in user code should only be done through our
Nginx APIs defined below, otherwise Nginx event loop may be blocked and
performance may drop off dramatically. Small disk file operations can be
done via Lua's standard "io" and "file" libraries but should be
eliminated wherever possible because these also block the Nginx process.
Delegating all network and disk I/O operations to Nginx subrequests (via
the ngx.location.capture method and its friends) are strongly
recommended.
ngx.arg
syntax: *val = ngx.arg[index]*
context: *set_by_lua**
Index the input arguments to the set_by_lua and set_by_lua_file
directives:
value = ngx.arg[n]
Here's an example
location /foo {
set $a 32;
set $b 56;
set_by_lua $res
'return tonumber(ngx.arg[1]) + tonumber(ngx.arg[2])'
$a $b;
echo $sum;
}
that outputs 88, the sum of 32 and 56.
ngx.var.VARIABLE
syntax: *ngx.var.VAR_NAME*
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua** value = ngx.var.some_nginx_variable_name
ngx.var.some_nginx_variable_name = value Note that you can only write to
nginx variables that are already defined. For example: location /foo {
set $my_var ''; # this line is required to create $my_var at config time
content_by_lua ' ngx.var.my_var = 123; ... '; } That is, nginx variables
cannot be created on-the-fly.
Some special nginx variables like $args and $limit_rate can be assigned
a value, some are not, like $arg_PARAMETER.
Nginx regex group capturing variables $1, $2, $3, and etc, can be read
by this interface as well, by writing "ngx.var[1]", "ngx.var[2]",
"ngx.var[3]", and etc.
Core constants
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua**
ngx.OK (0)
ngx.ERROR (-1)
ngx.AGAIN (-2)
ngx.DONE (-4)
They take the same values of C<NGX_OK>, C<NGX_AGAIN>, C<NGX_DONE>, C<NGX_ERROR>, and etc. But now
only L<ngx.exit|/"ngx.exit"> only take two of these values, i.e., C<NGX_OK> and C<NGX_ERROR>.
HTTP method constants
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua**
ngx.HTTP_GET
ngx.HTTP_HEAD
ngx.HTTP_PUT
ngx.HTTP_POST
ngx.HTTP_DELETE
These constants are usually used in ngx.location.catpure and
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** value = ngx.HTTP_OK (200) value =
ngx.HTTP_CREATED (201) value = ngx.HTTP_SPECIAL_RESPONSE (300) value =
ngx.HTTP_MOVED_PERMANENTLY (301) value = ngx.HTTP_MOVED_TEMPORARILY
(302) value = ngx.HTTP_SEE_OTHER (303) value = ngx.HTTP_NOT_MODIFIED
(304) value = ngx.HTTP_BAD_REQUEST (400) value = ngx.HTTP_UNAUTHORIZED
(401) value = ngx.HTTP_FORBIDDEN (403) value = ngx.HTTP_NOT_FOUND (404)
value = ngx.HTTP_NOT_ALLOWED (405) value = ngx.HTTP_GONE (410) value =
ngx.HTTP_INTERNAL_SERVER_ERROR (500) value =
ngx.HTTP_METHOD_NOT_IMPLEMENTED (501) value =
ngx.HTTP_SERVICE_UNAVAILABLE (503)
Nginx log level constants
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua** ngx.STDERR ngx.EMERG ngx.ALERT ngx.CRIT ngx.ERR
ngx.WARN ngx.NOTICE ngx.INFO ngx.DEBUG
These constants are usually used by the ngx.log method.
print
syntax: *print(...)*
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua**
Emit args concatenated to nginx's "error.log" file, with log level
"ngx.NOTICE" and prefix "lua print: ".
It's equivalent to ngx.log(ngx.NOTICE, 'lua print: ', a, b, ...) Lua
"nil" arguments are accepted and result in literal "nil", and Lua
booleans result in "true" or "false".
ngx.ctx
context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*,
header_filter_by_lua**
This table can be used to store per-request context data for Lua
programmers.
This table has a liftime identical to the current request (just like
Nginx variables). Consider the following example, location /test {
rewrite_by_lua ' ngx.say("foo = ", ngx.ctx.foo) ngx.ctx.foo = 76 ';
access_by_lua ' ngx.ctx.foo = ngx.ctx.foo + 3 '; content_by_lua '
ngx.say(ngx.ctx.foo) '; } Then "GET /test" will yield the output foo =
nil 79 That is, the "ngx.ctx.foo" entry persists across the rewrite,
access, and content phases of a request.
Also, every request has its own copy, include subrequests, for example:
location /sub { content_by_lua ' ngx.say("sub pre: ", ngx.ctx.blah)
ngx.ctx.blah = 32 ngx.say("sub post: ", ngx.ctx.blah) '; }
location /main {
content_by_lua '
ngx.ctx.blah = 73
ngx.say("main pre: ", ngx.ctx.blah)
local res = ngx.location.capture("/sub")
ngx.print(res.body)
ngx.say("main post: ", ngx.ctx.blah)
';
}
Then C<GET /main> will give the output
main pre: 73
sub pre: nil
sub post: 32
main post: 73
We can see that modification of the C<ngx.ctx.blah> entry in the subrequest does not affect the one in its parent request. They do have two separate versions of C<ngx.ctx.blah> per se.
Internal redirection will destroy the original request's "ngx.ctx" data
(if any) and the new request will have an emptied "ngx.ctx" table. For
instance, location /new { content_by_lua ' ngx.say(ngx.ctx.foo) '; }
location /orig {
content_by_lua '
ngx.ctx.foo = "hello"
ngx.exec("/new")
';
}
Then C<GET /orig> will give you
nil
rather than the original C<"hello"> value.
Arbitrary data values can be inserted into this "matic" table, including
Lua closures and nested tables. You can also register your own meta
methods with it.
Overriding "ngx.ctx" with a new Lua table is also supported, for
example, ngx.ctx = { foo = 32, bar = 54 }
ngx.location.capture
syntax: *res = ngx.location.capture(uri, options?)*
context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
Issue a synchronous but still non-blocking *Nginx Subrequest* using
"uri".
Nginx 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.
Also note that subrequests just mimic the HTTP interface but there's
*no* extra HTTP/TCP traffic *nor* IPC involved. Everything works
internally, efficiently, on the C level.
Subrequests are completely different from HTTP 301/302 redirection (via
ngx.redirect) and internal redirection (via ngx.exec).
Here's a basic example: res = ngx.location.capture(uri) Returns a Lua
table with three slots ("res.status", "res.header", and "res.body").
"res.header" holds all the response headers of the subrequest and it is
a normal Lua table. For multi-value response headers, the value is a Lua
(array) table that holds all the values in the order that they appear.
For instance, if the subrequest response headers contains the following
lines: Set-Cookie: a=3 Set-Cookie: foo=bar Set-Cookie: baz=blah Then
"res.header["Set-Cookie"]" will be evaluted to the table value "{"a=3",
"foo=bar", "baz=blah"}".
URI query strings can be concatenated to URI itself, for instance, res =
ngx.location.capture('/foo/bar?a=3&b=4') Named locations like @foo are
not allowed due to a limitation in the nginx core. Use normal locations
combined with the "internal" directive to prepare internal-only
locations.
An optional option table can be fed as the second argument, which
support various options like "method", "body", "args", and
"share_all_vars". Issuing a POST subrequest, for example, can be done as
follows res = ngx.location.capture( '/foo/bar', { method =
ngx.HTTP_POST, body = 'hello, world' } ) See HTTP method constants
methods other than POST. The "method" option is "ngx.HTTP_GET" by
default.
The "share_all_vars" option can control whether to share nginx variables
among the current request and the new subrequest. If this option is set
to "true", then the subrequest can see all the variable values of the
current request while the current requeset can also see any variable
value changes made by the subrequest. Note that variable sharing can
have unexpected side-effects and lead to confusing issues, use it with
special care. So, by default, the option is set to "false".
The "args" option can specify extra url arguments, for instance,
ngx.location.capture('/foo?a=1', { args = { b = 3, c = ':' } } ) 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.
Because it's all done in hand-written C, it should be faster than your
own Lua code.
The "args" option can also take plain query string:
ngx.location.capture('/foo?a=1', { args = 'b=3&c=%3a' } } ) This is
functionally identical to the previous examples.
Note that, by default, subrequests issued by ngx.location.capture
inherit all the request headers of the current request. This may have
unexpected side-effects on the subrequest responses. For example, when
you're using the standard "ngx_proxy" module to serve your subrequests,
then an "Accept-Encoding: gzip" header in your main request may result
in gzip'd responses that your Lua code is not able to handle properly.
So always set proxy_pass_request_headers "off" in your subrequest
location to ignore the original request headers.
ngx.location.capture_multi
syntax: *res1, res2, ... = ngx.location.capture_multi({ {uri, options?},
{uri, options?}, ... })*
context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
Just like ngx.location.capture, but supports multiple subrequests
running in parallel.
This function issue several parallel subrequests specified by the input
table, and returns their results in the same order. For example, res1,
res2, res3 = ngx.location.capture_multi{ { "/foo", { args = "a=3&b=4" }
}, { "/bar" }, { "/baz", { method = ngx.HTTP_POST, body = "hello" } }, }
if res1.status == ngx.HTTP_OK then
...
end
if res2.body == "BLAH" then
...
end
This function will not return until all the subrequests terminate.
The total latency is the longest latency of the subrequests, instead of their sum.
When you don't know inadvance how many subrequests you want to issue,
you can use Lua tables for both requests and responses. For instance, --
construct the requests table local reqs = {} table.insert(reqs, {
"/mysql" }) table.insert(reqs, { "/postgres" }) table.insert(reqs, {
"/redis" }) table.insert(reqs, { "/memcached" })
-- issue all the requests at once and wait until they all return
local resps = { ngx.location.capture_multi(reqs) }
-- loop over the responses table
for i, resp in ipairs(resps) do
-- process the response table "resp"
end
The L<ngx.location.capture|/"ngx.location.capture"> function is just a special form
of this function. Logically speaking, the L<ngx.location.capture|/"ngx.location.capture"> can be implemented like this
ngx.location.capture =
function (uri, args)