openresty 常用API學習一

ngx.exit
函數原型: ngx.exit(status)
函數說明: 中斷當前請求，並將status返回給nginx

 

ngx.worker.exiting
函數原型：boolean = ngx.worker.exiting()
函數說明: 此函數返回一個布爾值，指示當前Nginx工作進程是否已開始退出。Nginx worker進程退出發生在Nginx server quit或configuration reload
（也稱為HUP reload）上。

 

ngx.timer.at
函數原型：hdl, err = ngx.timer.at(delay, callback, user_arg1, user_arg2, ...)
函數說明: 創建帶有用戶回調函數和可選用戶參數的Nginx計時器
第一個參數delay指定計時器的延遲（秒）。在這里可以指定0.001這樣的小數秒為1毫秒。也可以指定0延遲，
    在這種情況下，當當前處理程序產生執行時，計時器將立即過期。
第二個參數callback可以是任何Lua函數，稍后將在指定延遲后的后台“light thread”中調用該函數。
    Nginx核心將使用參數premature、user_arg1、user_arg2等自動調用用戶回調，其中premature參數接受一個布爾值，該值指示是否是過早計時器過期，
    user_arg1、user_arg2等是調用時指定的（額外的）用戶參數下一代計時器作為剩下的論點。
強調①:當Nginx工作進程正在嘗試關閉時，會發生提前定時器到期，如在Nginx配置中由HUP信號觸發的重新加載或Nginx服務器關閉。
當Nginx工作器試圖關閉時，不能再調用ngx.timer.at創建具有非零延遲的新定時器，在這種情況下ngx.timer.at將返回nil，還有一個描述錯誤的字符串，即“進程退出”。
從v0.9.3版本開始，即使Nginx工作進程開始關閉，也允許創建零延遲計時器。
強調②當計時器過期時，計時器回調中的用戶Lua代碼將在一個“輕線程”中運行，該線程與創建計時器的原始請求完全分離(說明該線程仍然被主線程所join，
並沒有detach，即定時器不執行完成，主進程無法退出)。
因此，不能在原始請求和計時器用戶回調函數之間共享與創建它們的請求具有相同生存期的對象（如cosockets）。
ngx.timer.at本質上還是開辟一個線程協作運行，但是ngx.timer的運行時間並非執行完ngx.timer.at函數之后立即開始，
而是等待執行ngx.timer.at的協程運行完畢之后再執行 local delay = 5
 local handler
 handler = function (premature)
     -- do some routine job in Lua just like a cron job
     if premature then
         return
     end
     local ok, err = ngx.timer.at(delay, handler)
     if not ok then
         ngx.log(ngx.ERR, "failed to create the timer: ", err)
         return
     end
 end

 local ok, err = ngx.timer.at(delay, handler)
 if not ok then
     ngx.log(ngx.ERR, "failed to create the timer: ", err)
     return
 end
 
 location / {
     ...
     log_by_lua_block {
         local function push_data(premature, uri, args, status)
             -- push the data uri, args, and status to the remote
             -- via ngx.socket.tcp or ngx.socket.udp
             -- (one may want to buffer the data in Lua a bit to
             -- save I/O operations)
         end
         local ok, err = ngx.timer.at(0, push_data,
                                      ngx.var.uri, ngx.var.args, ngx.header.status)
         if not ok then
             ngx.log(ngx.ERR, "failed to create timer: ", err)
             return
         end
     }
 }
 

 

ngx.get_phase
函數原型: str = ngx.get_phase()
函數說明: 檢索當前運行的階段
返回值如下:(https://github.com/openresty/lua-nginx-module#ngxget_phase)
init for the context of init_by_lua*.
init_worker for the context of init_worker_by_lua*.
ssl_cert for the context of ssl_certificate_by_lua*.
ssl_session_fetch for the context of ssl_session_fetch_by_lua*.
ssl_session_store for the context of ssl_session_store_by_lua*.
set for the context of set_by_lua*.
rewrite for the context of rewrite_by_lua*.
balancer for the context of balancer_by_lua*.
access for the context of access_by_lua*.
content for the context of content_by_lua*.
header_filter for the context of header_filter_by_lua*.
body_filter for the context of body_filter_by_lua*.
log for the context of log_by_lua*.
timer for the context of user callback functions for ngx.timer.*.

 

ngx.escape_uri
函數原型: newstr = ngx.escape_uri(str)
函數說明: 做url字符串轉化
返回值: 新字符串

 

ngx.thread.spawn
函數原型: co = ngx.thread.spawn(func, arg1, arg2, ...)
函數說明: 創建一個Lua線程(或者協程)執行func函數，func的參數列表是 arg1,arg2

 

ngx.req.set_uri
函數原型: ngx.req.set_uri(uri, jump?)
函數說明: 重寫當前請求的url使用形參代替，要求形參必須是lua字符串，當jump為true時，調用ngx.req.set_uri后，
nginx將會根據修改后的uri，重新匹配新的location；如果jump為false，將不會進行locations的重新匹配，而僅僅是修改了當前請求的URI而已。jump的默認值為false。

 

ngx.re.match
函數原型: captures, err = ngx.re.match(subject, regex, options?, ctx?, res_table?)
函數說明: 使用Perl兼容的正則表達式regex與可選選項匹配主題字符串。只返回第一個匹配項[強調]，如果沒有找到匹配項，則返回nil。
如果出現錯誤，例如看到錯誤的正則表達式或超出PCRE堆棧限制，將返回nil和描述錯誤的字符串。

支持子表達式 local m, err = ngx.re.match("hello, 1234", "([0-9])[0-9]+")
 -- m[0] == "1234"
 -- m[1] == "1"