ngx.ctx

https://github.com/openresty/lua-nginx-module#ngxctx

要点

1. 生命周期和请求一致
2. 每个请求的ngx.ctx是相互独立的,包括ngx.location.capture的子请求
3. 内部跳转(Internal redirection)如ngx.exec会销毁ngx.ctx,重建新的.
4. ngx.ctx的属性查找代价相对昂贵,所以尽量使用显式的函数参数.

原文

context: init_worker_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.timer., balancer_by_lua*

This table can be used to store per-request Lua context data and has a life time identical to the current request (as with the Nginx variables).

Consider the following example,

location /test {
rewrite_by_lua '
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

79
That is, the ngx.ctx.foo entry persists across the rewrite, access, and content phases of a request.

Every request, including subrequests, has its own copy of the table. 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 GET /main will give the output

main pre: 73
sub pre: nil
sub post: 32
main post: 73
Here, modification of the ngx.ctx.blah entry in the subrequest does not affect the one in the parent request. This is because they have two separate versions of ngx.ctx.blah.

Internal redirection will destroy the original request ngx.ctx data (if any) and the new request will have an empty 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 GET /orig will give

nil
rather than the original "hello" value.

Arbitrary data values, including Lua closures and nested tables, can be inserted into this "magic" table. It also allows the registration of custom meta methods.

Overriding ngx.ctx with a new Lua table is also supported, for example,

ngx.ctx = { foo = 32, bar = 54 }
When being used in the context of init_worker_by_lua*, this table just has the same lifetime of the current Lua handler.

The ngx.ctx lookup requires relatively expensive metamethod calls and it is much slower than explicitly passing per-request data along by your own function arguments. So do not abuse this API for saving your own function arguments because it usually has quite some performance impact.

Because of the metamethod magic, never "local" the ngx.ctx table outside your Lua function scope on the Lua module level level due to worker-level data sharing. For example, the following is bad:

-- mymodule.lua
local _M = {}

-- the following line is bad since ngx.ctx is a per-request
-- data while this ctx variable is on the Lua module level
-- and thus is per-nginx-worker.
local ctx = ngx.ctx

function _M.main()
ctx.foo = "bar"
end

return _M
Use the following instead:

-- mymodule.lua
local _M = {}

function _M.main(ctx)
ctx.foo = "bar"
end

return _M
That is, let the caller pass the ctx table explicitly via a function argument.