Merge pull request #916 from flrgh/master

sumneko · web-flow · commit 66fe2c2eb0d7 · 2022-01-21T17:58:15.000+08:00
update ngx/openresty annotations
diff --git a/meta/3rd/OpenResty/library/ngx.balancer.lua b/meta/3rd/OpenResty/library/ngx.balancer.lua
@@ -43,8 +43,6 @@ function balancer.set_current_peer(addr, port) end
 ---
 --- For the best performance, you should use the OpenResty bundle.
 ---
---- This function was first added in the 0.1.7 version of this library.
----
 ---@param  connect_timeout? number
 ---@param  send_timeout?    number
 ---@param  read_timeout?    number
@@ -113,8 +111,6 @@ function balancer.set_more_tries(count) end
 --- should be made only if you know the request buffer must be regenerated,
 --- instead of unconditionally in each balancer retries.
 ---
---- This function was first added in the 0.1.20 version of this library.
----
 ---@return boolean ok
 ---@return string? error
 function balancer.recreate_request() end
diff --git a/meta/3rd/OpenResty/library/ngx.errlog.lua b/meta/3rd/OpenResty/library/ngx.errlog.lua
@@ -16,8 +16,6 @@ function errlog.get_sys_filter_level() end
 ---
 --- This API should always work with directive `lua_capture_error_log`.
 ---
---- See Nginx log level constants for all nginx log levels.
----
 ---@param  level   ngx.log.level
 ---@return boolean ok
 ---@return string? err
diff --git a/meta/3rd/OpenResty/library/ngx.lua b/meta/3rd/OpenResty/library/ngx.lua
diff --git a/meta/3rd/OpenResty/library/ngx.pipe.lua b/meta/3rd/OpenResty/library/ngx.pipe.lua
@@ -129,7 +129,7 @@ local proc = {}
 ---
 ---@param write_timeout?       number
 ---@param stdout_read_timeout? number
----@param write_timeout?       number
+---@param stderr_read_timeout? number
 ---@param wait_timeout?        number
 function proc:set_timeouts(write_timeout, stdout_read_timeout, stderr_read_timeout, wait_timeout) end
 
diff --git a/meta/3rd/OpenResty/library/ngx.process.lua b/meta/3rd/OpenResty/library/ngx.process.lua
@@ -5,9 +5,6 @@ local process = {
 
 --- Returns a number value for the nginx master process's process ID (or PID).
 ---
---- This function requires NGINX 1.13.8+ cores to work properly. Otherwise it returns nil.
----
---- This feature first appeared in lua-resty-core v0.1.14.
 ---@return integer? pid
 function process.get_master_pid() end
 
diff --git a/meta/3rd/OpenResty/library/ngx.re.lua b/meta/3rd/OpenResty/library/ngx.re.lua
@@ -26,10 +26,6 @@ re.version = require("resty.core.base").version
 ---
 --- The `jit_stack_size` cannot be set to a value lower than PCRE's default of 32K.
 ---
---- This method requires the PCRE library enabled in Nginx.
----
---- This feature was first introduced in the v0.1.12 release.
----
 ---@param option string '"jit_stack_size"'
 ---@param value any
 function re.opt(option, value) end
@@ -58,15 +54,6 @@ function re.opt(option, value) end
 --- -- res is now {"a", "b", "c", "d"}
 ---```
 ---
---- The optional ctx table argument can be a Lua table holding an optional pos field. When the pos field in the ctx table argument is specified, `split()` will start splitting the subject from that index:
----
----```lua
---- local ngx_re = require "ngx.re"
----
---- local res, err = ngx_re.split("a,b,c,d", ",", nil, {pos = 5})
---- -- res is now {"c", "d"}
----```
----
 --- The optional max argument is a number that when specified, will prevent `split()` from adding more than max matches to the res array:
 ---
 ---```lua
@@ -104,8 +91,8 @@ function re.opt(option, value) end
 ---
 ---@param  subj      string
 ---@param  regex     string
----@param  opts      string
----@param  ctx?      table    a Lua table holding an optional `pos` field
+---@param  opts      ngx.re.options
+---@param  ctx?      ngx.re.ctx
 ---@param  max?      number
 ---@param  res?      string[]
 ---@return string[]? res
diff --git a/meta/3rd/OpenResty/library/ngx.req.lua b/meta/3rd/OpenResty/library/ngx.req.lua
@@ -9,8 +9,6 @@ req.version = require("resty.core.base").version
 ---
 ---The `header_value` argument can either be a string or a non-empty, array-like table. A nil or empty table value will cause this function to throw an error.
 ---
----This feature was first introduced in the v0.1.18 release.
----
 ---@param header_name string            must be a non-empty string.
 ---@param header_value string|string[]
 function req.add_header(header_name, header_value) end
diff --git a/meta/3rd/OpenResty/library/ngx.semaphore.lua b/meta/3rd/OpenResty/library/ngx.semaphore.lua
@@ -47,7 +47,7 @@ function semaphore:count() end
 ---
 ---@param  timeout? number
 ---@return boolean  ok
----@return string?  error
+---@return string|'"timeout"'  error
 function semaphore:wait(timeout) end
 
 
diff --git a/meta/3rd/OpenResty/library/ngx.ssl.clienthello.lua b/meta/3rd/OpenResty/library/ngx.ssl.clienthello.lua
@@ -11,7 +11,7 @@ clienthello.version = require("resty.core.base").version
 ---
 ---Note that the SNI name is gotten from the raw extensions of the client hello message associated with the current downstream SSL connection.
 ---
----So this function can only be called in the context of [ssl_client_hello_by_lua*](https://github.com/openresty/lua-nginx-module/#ssl_client_hello_by_lua_block).
+---So this function can only be called in the context of `ssl_client_hello_by_lua*`.
 ---@return string? host
 ---@return string? error
 function clienthello.get_client_hello_server_name() end
@@ -25,7 +25,7 @@ function clienthello.get_client_hello_server_name() end
 ---
 --- Note that the ext is gotten from the raw extensions of the client hello message associated with the current downstream SSL connection.
 ---
---- So this function can only be called in the context of [ssl_client_hello_by_lua*](https://github.com/openresty/lua-nginx-module/#ssl_client_hello_by_lua_block).
+--- So this function can only be called in the context of `ssl_client_hello_by_lua*`.
 ---
 --- Example:
 ---
@@ -86,9 +86,13 @@ function clienthello.get_client_hello_ext(ext_type) end
 --- Returns `true` on success, or a `nil` value and a string describing the error otherwise.
 ---
 --- Considering it is meaningless to set ssl protocols after the protocol is determined,
---- so this function may only be called in the context of [ssl_client_hello_by_lua*](https://github.com/openresty/lua-nginx-module/#ssl_client_hello_by_lua_block).
+--- so this function may only be called in the context of `ssl_client_hello_by_lua*`.
+---
+--- Example:
+--- ```lua
+---  ssl_clt.set_protocols({"TLSv1.1", "TLSv1.2", "TLSv1.3"})`
+--- ```
 ---
---- Example: `ssl_clt.set_protocols({"TLSv1.1", "TLSv1.2", "TLSv1.3"})`
 ---@param protocols string[]
 ---@return boolean ok
 ---@return string? error
diff --git a/meta/3rd/OpenResty/library/ngx.ssl.lua b/meta/3rd/OpenResty/library/ngx.ssl.lua
@@ -21,8 +21,6 @@ function ssl.set_der_priv_key(der_priv_key) end
 ---
 --- This function can be called in any context.
 ---
---- This function was first added in version 0.1.7.
----
 ---@param pem_priv_key string
 ---@return string? priv_key
 ---@return string? error
@@ -51,8 +49,6 @@ function ssl.get_tls1_version() end
 ---
 --- Note that this set_cert function will run slightly faster, in terms of CPU cycles wasted, than the set_der_cert variant, since the first function uses opaque cdata pointers which do not require any additional conversion needed to be performed by the SSL library during the SSL handshake.
 ---
---- This function was first added in version 0.1.7.
----
 ---@param cert_chain string
 ---@return boolean ok
 ---@return string? error
@@ -67,8 +63,6 @@ ssl.TLS1_VERSION=769
 ---
 --- Note that this set_priv_key function will run slightly faster, in terms of CPU cycles wasted, than the set_der_priv_key variant, since the first function uses opaque cdata pointers which do not require any additional conversion needed to be performed by the SSL library during the SSL handshake.
 ---
---- This function was first added in version 0.1.7.
----
 ---@param priv_key string
 ---@return boolean ok
 ---@return string? error
@@ -166,8 +160,6 @@ function ssl.clear_certs() end
 ---
 --- This function can be called in any context where downstream https is used.
 ---
---- This function was first introduced in lua-resty-core 0.1.14.
----
 ---@return string?            addr_data
 ---@return ngx.ssl.addr_type? addr_type
 ---@return string?            error
@@ -182,8 +174,6 @@ function ssl.raw_client_addr() end
 ---
 --- This function can be called in any context.
 ---
---- This function was first added in version 0.1.7.
----
 ---@return string? cert_chain
 ---@return string? error
 function ssl.parse_pem_cert(pem_cert_chain) end
@@ -286,7 +276,7 @@ function ssl.cert_pem_to_der(pem_cert_chain) end
 ---
 --- This function was first added in version 0.1.20.
 ---
----@param  ca_certs? # the CA certificate chain opaque pointer returned by the parse_pem_cert function for the current SSL connection. The list of certificates will be sent to clients. Also, they will be added to trusted store. If omitted, will not send any CA certificate to clients.
+---@param  ca_certs? any # the CA certificate chain opaque pointer returned by the parse_pem_cert function for the current SSL connection. The list of certificates will be sent to clients. Also, they will be added to trusted store. If omitted, will not send any CA certificate to clients.
 ---@param  depth?  number verification depth in the client certificates chain. If omitted, will use the value specified by ssl_verify_depth.
 ---@return boolean ok
 ---@return string? error
diff --git a/meta/3rd/OpenResty/library/ngx.ssl.session.lua b/meta/3rd/OpenResty/library/ngx.ssl.session.lua
@@ -8,11 +8,11 @@ session.version = require("resty.core.base").version
 --- If the SSL session is successfully set, the current SSL connection can resume the session
 --- directly without going through the full SSL handshake process (which is very expensive in terms of CPU time).
 ---
---- This API is usually used in the context of [ssl_session_fetch_by_lua*](https://github.com/openresty/lua-nginx-module#ssl_session_fetch_by_lua_block)
+--- This API is usually used in the context of `ssl_session_fetch_by_lua*`
 --- when a cache hit is found with the current SSL session ID.
 ---
 --- The serialized SSL session used as the argument should be originally returned by the
---- [get_serialized_session](#get_serialized_session) function.
+--- `get_serialized_session` function.
 ---
 ---@param session string
 ---@return boolean ok
@@ -21,17 +21,16 @@ function session.set_serialized_session(session) end
 
 --- Returns the serialized form of the SSL session data of the current SSL connection, in a Lua string.
 ---
---- This session can be cached in [lua-resty-lrucache](https://github.com/openresty/lua-resty-lrucache), [lua_shared_dict](https://github.com/openresty/lua-nginx-module#lua_shared_dict),
+--- This session can be cached in `lua-resty-lrucache`, `lua_shared_dict`,
 --- and/or external data storage services like `memcached` and `redis`. The SSL session ID returned
---- by the [get_session_id](#get_session_id) function is usually used as the cache key.
+--- by the `get_session_id` function is usually used as the cache key.
 ---
 --- The returned SSL session data can later be loaded into other SSL connections using the same
---- session ID via the [set_serialized_session](#set_serialized_session) function.
+--- session ID via the `set_serialized_session` function.
 ---
 --- In case of errors, it returns `nil` and a string describing the error.
 ---
---- This API function is usually called in the context of
---- [ssl_session_store_by_lua*](https://github.com/openresty/lua-nginx-module#ssl_session_store_by_lua_block)
+--- This API function is usually called in the context of `ssl_session_store_by_lua*`
 --- where the SSL handshake has just completed.
 ---
 ---@return string? session
@@ -44,8 +43,7 @@ function session.get_serialized_session() end
 --- In case of errors, it returns `nil` and a string describing the error.
 ---
 --- This API function is usually called in the contexts of
---- [ssl_session_store_by_lua*](https://github.com/openresty/lua-nginx-module/#ssl_session_store_by_lua_block)
---- and [ssl_session_fetch_by_lua*](https://github.com/openresty/lua-nginx-module/#ssl_session_fetch_by_lua_block).
+--- `ssl_session_store_by_lua*` and `ssl_session_fetch_by_lua*`.
 ---
 ---@return string? id
 ---@return string? error
diff --git a/meta/3rd/OpenResty/library/resty.core.regex.lua b/meta/3rd/OpenResty/library/resty.core.regex.lua
@@ -1,11 +1,55 @@
 ---@meta
-local resty_core_regex={}
-function resty_core_regex.collect_captures(compiled, rc, subj, flags, res) end
-function resty_core_regex.set_buf_grow_ratio(ratio) end
-function resty_core_regex.re_sub_compile(regex, opts, replace, fun) end
-function resty_core_regex.is_regex_cache_empty() end
-function resty_core_regex.check_buf_size(buf, buf_size, pos, len, new_len, must_alloc) end
-function resty_core_regex.re_match_compile(regex, opts) end
-function resty_core_regex.destroy_compiled_regex(compiled) end
-resty_core_regex.version = require("resty.core.base").version
-return resty_core_regex
+
+---@class resty.core.regex
+---@field no_pcre boolean
+local regex = {}
+
+---@param ratio integer
+function regex.set_buf_grow_ratio(ratio) end
+
+---@return boolean is_empty
+function regex.is_regex_cache_empty() end
+
+---@class resty.core.regex.compiled : ffi.cdata*
+---@field captures        ffi.cdata*
+---@field ncaptures       integer
+---@field name_count      integer
+---@field name_table      ffi.cdata*
+---@field name_entry_size integer
+
+---@param compiled resty.core.regex.compiled
+---@param flags integer
+---@param res ngx.re.captures
+function regex.collect_captures(compiled, flags, res) end
+
+---@param compiled resty.core.regex.compiled
+function regex.destroy_compiled_regex(compiled) end
+
+---@param  re                         string
+---@param  opts                       ngx.re.options
+---@return resty.core.regex.compiled? compiled
+---@return boolean|string             compile_once_or_error
+---@return integer?                   flags
+function regex.re_match_compile(re, opts) end
+
+---@param  buf        ffi.cdata*
+---@param  buf_size   integer
+---@param  pos        integer
+---@param  len        integer
+---@param  new_len    integer
+---@param  must_alloc boolean
+---@return ffi.cdata* buf
+---@return integer    buf_size
+---@return integer    new_len
+function regex.check_buf_size(buf, buf_size, pos, len, new_len, must_alloc) end
+
+---@param  re                         string
+---@param  opts                       ngx.re.options
+---@param  replace?                   string
+---@param  func?                      fun(match:string):string
+---@return resty.core.regex.compiled? compiled
+---@return boolean|string             compile_once_or_error
+---@return integer?                   flags
+function regex.re_sub_compile(re, opts, replace, func) end
+
+return regex
