nginx lua api翻译

nginx的lua模块提供了很多lua的函数API给用户使用，以便让lua更好的操作nginx

24.1 Introduction
这里说的Nginx api for lua，指的就是在nginx.conf文件中用*_by_lua 和*_by_lua_file指令使用lua代码，为lua提供的专门的api。

syntax: val = ngx.arg[index]

context: set_by_lua*, body_filter_by_lua*

通过用valua = ngx.arg[n]，让nginx的变量作为参数传入lua给lua调用，使用方式如下列的代码

 location /foo {
        set $a 32;
        set $b 56;
 
        set_by_lua $sum
            'return tonumber(ngx.arg[1]) + tonumber(ngx.arg[2])'
            $a $b;
 
        echo $sum;
    }

$sum 的值最后是88。

24.3 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*, body_filter_by_lua*, log_by_lua*
可以通过以下的代码进行读写nginx的变量
value = ngx.var.some_nginx_variable_name
ngx.var.some_nginx_variable_name=value
```
 location /foo {
        set $my_var ''; # this line is required to create $my_var at config time
        content_by_lua '
            ngx.var.my_var = 123;
            ...
        ';
    }
```
在lua代码里面就可以得到或者设置nginx.conf的变量，比较下跟上面的nginx.arg有什么区别~
24.4 Core constants
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*, ngx.timer.*
一些核心常量
```
  ngx.OK (0)
  ngx.ERROR (-1)
  ngx.AGAIN (-2)
  ngx.DONE (-4)
  ngx.DECLINED (-5)
```

24.5 HTTP method constants
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*, ngx.timer.*

  ngx.HTTP_GET
  ngx.HTTP_HEAD
  ngx.HTTP_PUT
  ngx.HTTP_POST
  ngx.HTTP_DELETE
  ngx.HTTP_OPTIONS   (added in the v0.5.0rc24 release)
  ngx.HTTP_MKCOL     (added in the v0.8.2 release)
  ngx.HTTP_COPY      (added in the v0.8.2 release)
  ngx.HTTP_MOVE      (added in the v0.8.2 release)
  ngx.HTTP_PROPFIND  (added in the v0.8.2 release)
  ngx.HTTP_PROPPATCH (added in the v0.8.2 release)
  ngx.HTTP_LOCK      (added in the v0.8.2 release)
  ngx.HTTP_UNLOCK    (added in the v0.8.2 release)
  ngx.HTTP_PATCH     (added in the v0.8.2 release)
  ngx.HTTP_TRACE     (added in the v0.8.2 release)

一些http method的常量，一般用在ngx.location.capture 和ngx.location.capture_multi 这几个API的调用中~

24.6 HTTP status constants
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*, ngx.timer.*

  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)
  value = ngx.HTTP_GATEWAY_TIMEOUT (504) (first added in the v0.3.1rc38 release)

http响应状态的常量

24.7 Nginx log level constants
context: 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.*
```
  ngx.STDERR
  ngx.EMERG
  ngx.ALERT
  ngx.CRIT
  ngx.ERR
  ngx.WARN
  ngx.NOTICE
  ngx.INFO
  ngx.DEBUG
```
nginx日志的一些级别常量，一般用在 ngx.log的api中
24.8 print
syntax: print(...)

context: init_by_lua*, 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.*
这个API是采用ngx.NOTICE的日志级别将参数的值写入error.log文件中，等同于ngx.log(ngx.NOTICE,...)

24.9 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.*
ngx.ctx.xxx xxx是任意的一个变量名，ngx.ctx可以看成一个临时字典，作用域是每一个请求，也就是说不同的request是不同的ngx.ctx
如下面的例子

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)
        ';
    }

输出的结果是

    foo = nil
    79

这个ngx.ctx.foo的实例是贯穿在一个请求中rewrite、access还有content三个周期。
再看下面这个例子

    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)
        ';
    }

结果是

    main pre: 73
    sub pre: nil
    sub post: 32
    main post: 73

ngx.location.capture是请求另外一个链接，所以可以看到，sub和main中的ngx.ctx是不同的实例。

另外在init_worker_by_lua的指令中，我们可以初始化ngx.ctx，通过字典的形式
ngx.ctx = {foo = 32,bar = 54}

24.10 ngx.location.capture

syntax: res = ngx.location.capture(uri, options?)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*

通过这个api，lua可以访问本server的其他location，只能是同一个server的。用法如下

 res = ngx.location.capture(uri)

返回的是一个response对象，这个对象持有其他包括res.status、res.body以及res.header三个对象。
-capture函数除了url还有其他参数可以选择，包括
-method 设置访问的method类型
-body 设置访问子请求的httpbody内容
-args设置请求的参数

    ngx.location.capture('/foo?a=1',
        { args = { b = 3, c = ':' } }
    )

等价于下面的调用，都是传递请求参数

    ngx.location.capture('/foo?a=1&b=3&c=%3a')

-ctx 之前在ngx.ctx说的，在一个请求中独享一个ngx.ctx。但是在这里通过ctx，可以传入一个字典，然后通过子请求设置ngx.ctx的值，从而，我们在父请求中得到子请求ngx.ctx的值。

 location /sub {
        content_by_lua '
            ngx.ctx.foo = "bar";
        ';
    }
    location /lua {
        content_by_lua '
            local ctx = {}
            res = ngx.location.capture("/sub", { ctx = ctx })
 
            ngx.say(ctx.foo);
            ngx.say(ngx.ctx.foo);
        ';
    }

结果如下,仅仅是设置ctx这个字典的值，而不是共享ngx.ctx

    bar
    nil

-vars 这个参数用来在父请求中设置nginx的变量值并向子请求传递，这个方法比通过url参数传递更加有效果。

  location /other {
        content_by_lua '
            ngx.say("dog = ", ngx.var.dog)
            ngx.say("cat = ", ngx.var.cat)
        ';
    }
 
    location /lua {
        set $dog '';
        set $cat '';
        content_by_lua '
            res = ngx.location.capture("/other",
                { vars = { dog = "hello", cat = 32 }});
 
            ngx.print(res.body)
        ';
    }

结果如下

   dog = hello
    cat = 32

-copy_all_vars 拷贝父请求的nginx的变量给子请求

 location /other {
        set $dog "$dog world";
        echo "$uri dog: $dog";
    }
 
    location /lua {
        set $dog 'hello';
        content_by_lua '
            res = ngx.location.capture("/other",
                { copy_all_vars = true });
 
            ngx.print(res.body)
            ngx.say(ngx.var.uri, ": ", ngx.var.dog)
        ';
    }

结果如下

    /other dog: hello world
    /lua: hello

-share_all_vars 同享父请求和子请求的nginx的变量。

    location /other {
        set $dog "$dog world";
        echo "$uri dog: $dog";
    }
 
    location /lua {
        set $dog 'hello';
        content_by_lua '
            res = ngx.location.capture("/other",
                { share_all_vars = true });
 
            ngx.print(res.body)
            ngx.say(ngx.var.uri, ": ", ngx.var.dog)
        ';
    }

结果如下

    /other dog: hello world
    /lua: hello world

这个比copy_all_vars优先。

-always_forward_body 如果body属性没有设置，这个属性设置为true，那将发送父请求的httpbody给子请求。

24.11 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*

类似于上面的ngx.location.capture ，不过支持并行请求多个子请求

 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

    -- 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

24.12 ngx.status
context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*
读取或者设置当前的请求响应状态，这个应该在发送内容给浏览器之前执行
```
    ngx.status = ngx.HTTP_CREATED
    status = ngx.status
```

24.13 ngx.header.HEADER

syntax: ngx.header.HEADER = VALUE

syntax: value = ngx.header.HEADER

context: rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*

获取或者设置http header的值

   -- equivalent to ngx.header["Content-Type"] = 'text/plain'
    ngx.header.content_type = 'text/plain';
 
    ngx.header["X-My-Header"] = 'blah blah';

多个值的可以像下面那样设置

    ngx.header['Set-Cookie'] = {'a=32; path=/', 'b=4; path=/'}

    Set-Cookie: a=32; path=/
    Set-Cookie: b=4; path=/

特别是在header_filter_by_lua有效果，如

    location /test {
        set $footer '';
 
        proxy_pass http://some-backend;
 
        header_filter_by_lua '
            if ngx.header["X-My-Header"] == "blah" then
                ngx.var.footer = "some value"
            end
        ';
 
        echo_after_body $footer;
    }

24.14 ngx.resp.get_headers
syntax: headers = ngx.resp.get_headers(max_headers?, raw?)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*
```
local h = ngx.resp.get_headers()
for k, v in pairs(h) do
    ...
end
```
在lua中得到http请求的响应头，以字典的形式
24.15 ngx.req.start_time
syntax: secs = ngx.req.start_time()

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*, log_by_lua*
```
 local request_time = ngx.now() - ngx.req.start_time()
```
用来获取此次请求发起的时候的时间，用来模拟$request_time。
24.16 ngx.req.http_version
syntax: num = ngx.req.http_version()

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*
获取请求的http version
24.17 ngx.req.raw_header
syntax: str = ngx.req.raw_header(no_request_line?)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*
得到原http header的字符串文本内容
```
  ngx.print(ngx.req.raw_header())
```
结果是
```
    GET /t HTTP/1.1
    Host: localhost
    Connection: close
    Foo: bar
```
24.18 ngx.req.get_method
syntax: method_name = ngx.req.get_method()

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*
获得当前请求的method 名字
24.19 ngx.req.set_method
syntax: ngx.req.set_method(method_id)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*
设置覆盖此次请求的method名字
24.20 ngx.req.set_uri
syntax: ngx.req.set_uri(uri, jump?)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*
作用与rewrite相同，其中jump默认为false，false的时候
```
  ngx.req.set_uri("/foo", false)
```
结果是
```
rewrite ^ /foo break;
```
如果jump为true，那就是
```
ngx.req.set_uri("/foo", true)
```
结果是
```
rewrite ^ /foo last;
```
24.21 ngx.req.set_uri_args
syntax: ngx.req.set_uri_args(args)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*
rewrite当前的请求参数
```
ngx.req.set_uri_args("a=3&b=hello%20world")
```
或者
```
ngx.req.set_uri_args({ a = 3, b = "hello world" })
```

24.22 ngx.req.get_uri_args

syntax: args = ngx.req.get_uri_args(max_args?)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*

获得请求的参数

    location = /test {
        content_by_lua '
            local args = ngx.req.get_uri_args()
            for key, val in pairs(args) do
                if type(val) == "table" then
                    ngx.say(key, ": ", table.concat(val, ", "))
                else
                    ngx.say(key, ": ", val)
                end
            end
        ';
    }

当访问的是

GET
/test?foo=bar&bar=baz&bar=blah 结果就是

   foo: bar
    bar: baz, blah

24.23 ngx.req.get_post_args

syntax: args, err = ngx.req.get_post_args(max_args?)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*

得到post提交的参数

  location = /test {
        content_by_lua '
            ngx.req.read_body()
            local args, err = ngx.req.get_post_args()
            if not args then
                ngx.say("failed to get post args: ", err)
                return
            end
            for key, val in pairs(args) do
                if type(val) == "table" then
                    ngx.say(key, ": ", table.concat(val, ", "))
                else
                    ngx.say(key, ": ", val)
                end
            end
        ';
    }

当我们用curl提交参数时

    # Post request with the body 'foo=bar&bar=baz&bar=blah'
    $ curl --data 'foo=bar&bar=baz&bar=blah' localhost/test

结果是

    foo: bar
    bar: baz, blah

24.24 ngx.req.get_headers
syntax: headers = ngx.req.get_headers(max_headers?, raw?)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua, log_by_lua*
获取当前请求的头信息
```
  local h = ngx.req.get_headers()
    for k, v in pairs(h) do
        ...
    end
```
```
    ngx.say("Host: ", ngx.req.get_headers()["Host"])
```
24.25 ngx.req.set_header
syntax: ngx.req.set_header(header_name, header_value)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua
设置当前的请求头
```
 ngx.req.set_header("Content-Type", "text/css")
```
```
  ngx.req.set_header("Foo", {"a", "abc"})
```
24.26 ngx.req.clear_header
syntax: ngx.req.clear_header(header_name)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, body_filter_by_lua*
清除某一个请求头
24.27 ngx.req.read_body
syntax: ngx.req.read_body()

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
在不阻塞nginx事件轮询的情况下读取客户端请求的body
```
    ngx.req.read_body()
    local args = ngx.req.get_post_args()
```
24.28 ngx.req.discard_body
syntax: ngx.req.discard_body()

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
明确丢弃客户端请求body
24.29 ngx.req.get_body_data
syntax: data = ngx.req.get_body_data()

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
以字符串的形式获得客户端的请求body内容
24.30 ngx.req.get_body_file
syntax: file_name = ngx.req.get_body_file()

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
当发送文件请求的时候，获得文件的名字
24.31 ngx.req.set_body_data
syntax: ngx.req.set_body_data(data)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
设置客户端请求的body
24.32 ngx.req.set_body_file
syntax: ngx.req.set_body_data(data)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
通过filename来指定当前请求的file data。

24.33 ngx.req.init_body

syntax: ngx.req.init_body(buffer_size?)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*

创建一个当前请求的空白body的buffer，后续可以自己写入请求的body。

  ngx.req.init_body(128 * 1024)  -- buffer is 128KB
    for chunk in next_data_chunk() 
    do
        ngx.req.append_body(chunk) -- each chunk can be 4KB
    end
    ngx.req.finish_body()

24.34 ngx.req.append_body
syntax: ngx.req.append_body(data_chunk)

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*
追加当前请求的http body
24.35 ngx.req.finish_body
syntax: ngx.req.finish_body()

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*
标志完成ngx.req.init_body的数据追加。
24.36 ngx.req.socket
syntax: tcpsock, err = ngx.req.socket()

syntax: tcpsock, err = ngx.req.socket(raw)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
这个方法会返回一个只读的cosocket对象，用来读取当前请求的request http body内容。

24.37 ngx.exec

syntax: ngx.exec(uri, args?)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*

执行内部跳转根据url和请求参数

   ngx.exec('/some-location');
    ngx.exec('/some-location', 'a=3&b=5&c=6');
    ngx.exec('/some-location?a=3&b=5', 'c=6');

   location /foo {
        content_by_lua '
            ngx.exec("@bar", "a=goodbye");
        ';
    }
 
    location @bar {
        content_by_lua '
            local args = ngx.req.get_uri_args()
            for key, val in pairs(args) do
                if key == "a" then
                    ngx.say(val)
                end
            end
        ';
    }

24.38 ngx.redirect
syntax: ngx.redirect(uri, status?)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
执行301或者302的重定向。
24.39 ngx.send_headers
syntax: ok, err = ngx.send_headers()

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
指定响应头。
24.40 ngx.headers_sent
syntax: value = ngx.headers_sent

context: set_by_lua*, rewrite_by_lua*, access_by_lua*, content_by_lua*
判断头部是否发送给客户端了。

24.41 ngx.print

syntax: ok, err = ngx.print(...)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*

发送数据给客户端响应页面

   local table = {
        "hello, ",
        {"world: ", true, " or ", false,
            {": ", nil}}
    }
    ngx.print(table)

24.42 ngx.say
syntax: ok, err = ngx.say(...)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
作用类似于ngx.print
24.43 ngx.log
syntax: ngx.log(log_level, ...)

context: init_by_lua*, 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.*
向error.log中记录日志
24.44 ngx.flush
syntax: ok, err = ngx.flush(wait?)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*
将flush内容到客户端页面
24.45 ngx.exit
syntax: ngx.exit(status)

context: rewrite_by_lua*, access_by_lua*, content_by_lua*, header_filter_by_lua*, ngx.timer.*
```
    ngx.status = ngx.HTTP_GONE
    ngx.say("This is our own content")
    -- to cause quit the whole request rather than the current phase handler
    ngx.exit(ngx.HTTP_OK)
```
当status>=200的时候，直接停止当前请求的后续操作，并且返回状态码
当status==0的时候，跳过此次代码片段，并且继续执行下面的。

24.46 ngx.eof

syntax: ok, err = ngx.eof()

context: rewrite_by_lua*, access_by_lua*, content_by_lua*

  location = /async {
        keepalive_timeout 0;
        content_by_lua '
            ngx.say("got the task!")
            ngx.eof()  -- a descent HTTP client will close the connection at this point
            -- access MySQL, PostgreSQL, Redis, Memcached, and etc here...
        ';
    }

明确指定关闭结束输出流。