documented the ngx.ctx "magic table"; also checked in the tests for ngx.ctx.

README.markdown

@@ -736,6 +736,84 @@ It's equivalent to
 
 Lua nil arguments are accepted and result in literal "nil", and Lua booleans result in "true" or "false".
 
+ngx.ctx
+-------
+* **Context:** `rewrite_by_lua*`, `access_by_lua*`, `content_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 sown 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 `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 `ngx.ctx.blah` entry in the subrequest does not affect the one in its parent request. They do have two separate versions of `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 `GET /orig` will give you
+
+    nil
+
+rather than the original `"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.
+
 ngx.location.capture(uri, options?)
 -----------------------------------
 * **Context:** `rewrite_by_lua*`, `access_by_lua*`, `content_by_lua*`

t/033-ctx.t

@@ -0,0 +1,104 @@
+# vim:set ft= ts=4 sw=4 et fdm=marker:
+use lib 'lib';
+use Test::Nginx::Socket;
+
+#worker_connections(1014);
+#master_on();
+#workers(2);
+log_level('warn');
+
+repeat_each(2);
+#repeat_each(1);
+
+plan tests => repeat_each() * (blocks() * 2);
+
+#no_diff();
+#no_long_string();
+run_tests();
+
+__DATA__
+
+=== TEST 1: sanity
+--- config
+    location /lua {
+        content_by_lua '
+            ngx.ctx.foo = 32;
+            ngx.say(ngx.ctx.foo)
+        ';
+    }
+--- request
+GET /lua
+--- response_body
+32
+
+
+
+=== TEST 2: rewrite, access, and content
+--- config
+    location /lua {
+        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)
+        ';
+    }
+--- request
+GET /lua
+--- response_body
+foo = nil
+79
+
+
+
+=== TEST 3: interal redirect clears ngx.ctx
+--- config
+    location /echo {
+        content_by_lua '
+            ngx.say(ngx.ctx.foo)
+        ';
+    }
+    location /lua {
+        content_by_lua '
+            ngx.ctx.foo = ngx.var.arg_data
+            -- ngx.say(ngx.ctx.foo)
+            ngx.exec("/echo")
+        ';
+    }
+--- request
+GET /lua?data=hello
+--- response_body
+nil
+
+
+
+=== TEST 4: subrequest has its own ctx
+--- config
+    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)
+        ';
+    }
+--- request
+    GET /main
+--- response_body
+main pre: 73
+sub pre: nil
+sub post: 32
+main post: 73
+