Permalink
Browse files

added more tests for header_filter_by_lua (confirmed that various API…

…s are properly injected).
  • Loading branch information...
1 parent 1380640 commit 644b1da68c73783188ab5cbc9b75f32f3fd9f2f8 @agentzh agentzh committed Sep 1, 2011
Showing with 384 additions and 151 deletions.
  1. +107 −52 README
  2. +92 −49 README.markdown
  3. +87 −46 doc/HttpLuaModule.wiki
  4. +4 −0 src/ngx_http_lua_headerfilterby.c
  5. +19 −2 t/006-escape.t
  6. +37 −1 t/009-log.t
  7. +17 −0 t/018-ndk.t
  8. +21 −1 t/033-ctx.t
View
@@ -8,9 +8,9 @@ Status
This module is under active development and is already production ready.
Version
- This document describes ngx_lua v0.2.1rc19
+ This document describes ngx_lua v0.2.1rc20
(<https://github.com/chaoslawful/lua-nginx-module/downloads>) released
- on 27 August 2011.
+ on 1 September 2011.
Synopsis
# set search paths for pure Lua external libraries (';;' is the default path):
@@ -356,9 +356,31 @@ Directives
APIs to generate response content.
The use code is executed in a new spawned coroutine with independent
- globals environment (i.e. a sandbox). I/O operations in user code should
- only be done through predefined Nginx APIs, otherwise Nginx event loop
- may be blocked and performance may drop off dramatically.
+ 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>*
@@ -463,6 +485,26 @@ Directives
"ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)" (or its friends) for
failures.
+ rewrite_by_lua_file
+ syntax: *rewrite_by_lua_file <path-to-lua-script>*
+
+ context: *http, server, location, location if*
+
+ phase: *rewrite tail*
+
+ 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>*
@@ -538,15 +580,15 @@ Directives
("ngx.HTTP_SPECIAL_RESPONSE") for successful quits and
"ngx.exit(ngx.HTTP_INTERNAL_SERVER_ERROR)" or its friends for failures.
- content_by_lua_file
- syntax: *content_by_lua_file <path-to-lua-script>*
+ access_by_lua_file
+ syntax: *access_by_lua_file <path-to-lua-script>*
- context: *location, location if*
+ context: *http, server, location, location if*
- phase: *content*
+ phase: *access tail*
- Basically the same as content_by_lua, except the code to be executed is
- in the file specified by "<path-lua-script>".
+ 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
@@ -558,45 +600,43 @@ Directives
You can disable the Lua code cache by setting lua_code_cache "off" in
your "nginx.conf" file.
- rewrite_by_lua_file
- syntax: *rewrite_by_lua_file <path-to-lua-script>*
+ header_filter_by_lua
+ syntax: *header_filter_by_lua <lua-script-str>*
context: *http, server, location, location if*
- phase: *rewrite tail*
+ phase: *output header filter*
- Same as rewrite_by_lua, except the code to be executed is in the file
- specified by "<path-lua-script>".
+ 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:
- 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.
+ * Output API (e.g., ngx.say and ngx.send_headers)
- 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.
+ * Control APIs (e.g., ngx.exit)
- access_by_lua_file
- syntax: *access_by_lua_file <path-to-lua-script>*
+ * 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: *access tail*
+ phase: *output header filter*
- Same as access_by_lua, except the code to be executed is in the file
- specified by "<path-lua-script>".
+ Use Lua code defined in a separate file specified by
+ "<path-to-lua-script-file>" to define an output header filter.
- 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.
+ This is very much like header_filter_by_lua except that it loads Lua
+ code from an external Lua source file.
- 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.
+ This directive was first introduced in the "v0.2.1rc20" release.
lua_need_request_body
syntax: *lua_need_request_body <on | off>*
@@ -654,8 +694,19 @@ Nginx API for Lua
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**
+ syntax: *val = ngx.arg[index]*
+
+ context: *set_by_lua**
Index the input arguments to the set_by_lua and set_by_lua_file
directives:
@@ -696,13 +747,17 @@ Nginx API for Lua
"ngx.var[3]", and etc.
Core constants
- context: *rewrite_by_lua*, access_by_lua*, content_by_lua** ngx.OK (0)
- ngx.ERROR (-1) ngx.AGAIN (-2) ngx.DONE (-4) They take the same values of
- "NGX_OK", "NGX_AGAIN", "NGX_DONE", "NGX_ERROR", and etc. But now only
- ngx.exit only take two of these values, i.e., "NGX_OK" and "NGX_ERROR".
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_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: *rewrite_by_lua*, access_by_lua*, content_by_lua**
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
ngx.HTTP_GET
ngx.HTTP_HEAD
@@ -714,8 +769,8 @@ Nginx API for Lua
ngx.location.capture_multi method calls.
HTTP status constants
- context: *rewrite_by_lua*, access_by_lua*, content_by_lua** value =
- ngx.HTTP_OK (200) value = ngx.HTTP_CREATED (201) value =
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_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
@@ -744,7 +799,7 @@ Nginx API for Lua
booleans result in "true" or "false".
ngx.ctx
- context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
This table can be used to store per-request context data for Lua
programmers.
@@ -964,7 +1019,7 @@ Nginx API for Lua
ngx.req.get_uri_args
syntax: *args = ngx.req.get_uri_args()*
- context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
Returns a Lua table holds all of the current request's request URL query
arguments.
@@ -995,7 +1050,7 @@ Nginx API for Lua
ngx.req.get_post_args
syntax: *ngx.req.get_post_args()*
- context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
Returns a Lua table holds all of the current request's POST query
arguments. It's required to turn on the lua_need_request_body directive,
@@ -1026,7 +1081,7 @@ Nginx API for Lua
ngx.req.get_headers
syntax: *headers = ngx.req.get_headers()*
- context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
Returns a Lua table holds all of the current request's request headers.
@@ -1042,7 +1097,7 @@ Nginx API for Lua
ngx.req.set_header
syntax: *ngx.req.set_header(header_name, header_value)*
- context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
Set the current request's request header named "header_name" to value
"header_value", overriding any existing ones. None of the current
@@ -1061,7 +1116,7 @@ Nginx API for Lua
ngx.req.clear_header
syntax: *ngx.req.clear_header(header_name)*
- context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
Clear the current request's request header named "header_name". None of
the current request's subrequests will be affected.
@@ -1581,7 +1636,7 @@ Nginx API for Lua
ndk.set_var.DIRECTIVE
syntax: *res = ndk.set_var.DIRECTIVE_NAME*
- context: *rewrite_by_lua*, access_by_lua*, content_by_lua**
+ context: *set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua**
This mechanism allows calling other nginx C modules' directives that are
implemented by Nginx Devel Kit
Oops, something went wrong.

0 comments on commit 644b1da

Please sign in to comment.