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

明確指定關閉結束輸出流。