Merge pull request #1265 from flrgh/chore/resty-annotations

OpenResty type annotation updates

4 files changed, 1309 insertions, 25 deletions

diff --git a/meta/3rd/OpenResty/library/cjson.lua b/meta/3rd/OpenResty/library/cjson.lua
new file mode 100644
index 00000000..aeef436a
--- /dev/null
+++ b/meta/3rd/OpenResty/library/cjson.lua
@@ -0,0 +1,488 @@
+---@meta
+
+--- lua cjson
+---
+--- https://kyne.com.au/~mark/software/lua-cjson.php
+--- https://kyne.com.au/~mark/software/lua-cjson-manual.html
+--- https://openresty.org/en/lua-cjson-library.html
+---
+--- **NOTE:** This includes the additions in the OpenResty-maintained cjson fork: https://github.com/openresty/lua-cjson
+---
+--- ---
+---
+--- The cjson module will throw an error during JSON conversion if any invalid
+--- data is encountered. Refer to `cjson.encode` and cjson.decode for details.
+---
+--- The cjson.safe module behaves identically to the cjson module, except when
+--- errors are encountered during JSON conversion. On error, the cjson_safe.encode
+--- and cjson_safe.decode functions will return nil followed by the error message.
+---
+--- cjson.new can be used to instantiate an independent copy of the Lua CJSON
+--- module. The new module has a separate persistent encoding buffer, and default settings.
+---
+--- Lua CJSON can support Lua implementations using multiple preemptive threads
+--- within a single Lua state provided the persistent encoding buffer is not
+--- shared. This can be achieved by one of the following methods:
+---
+---  * Disabling the persistent encoding buffer with cjson.encode_keep_buffer
+---  * Ensuring each thread calls cjson.encode separately (ie, treat cjson.encode as non-reentrant).
+---  * Using a separate cjson module table per preemptive thread (cjson.new)
+---
+--- ## Note
+---
+--- Lua CJSON uses `strtod` and `snprintf` to perform numeric conversion as they
+--- are usually well supported, fast and bug free. However, these functions
+--- require a workaround for JSON encoding/parsing under locales using a comma
+--- decimal separator. Lua CJSON detects the current locale during instantiation
+--- to determine and automatically implement the workaround if required. Lua
+--- CJSON should be reinitialised via cjson.new if the locale of the current
+--- process changes. Using a different locale per thread is not supported.
+---
+---@class cjson
+---@field _NAME          string
+---@field _VERSION       string
+---@field null           cjson.null
+---@field empty_array    cjson.empty_array
+---@field array_mt       cjson.array_mt
+---@field empty_array_mt cjson.empty_array_mt
+---
+local cjson = {}
+
+
+--- A metatable which can "tag" a table as a JSON Array in case it is empty (that
+--- is, if the table has no elements, `cjson.encode()` will encode it as an empty
+--- JSON Array).
+---
+--- Instead of:
+---
+---```lua
+--- local function serialize(arr)
+---     if #arr < 1 then
+---         arr = cjson.empty_array
+---     end
+---
+---     return cjson.encode({some_array = arr})
+--- end
+---```
+---
+--- This is more concise:
+---
+---```lua
+--- local function serialize(arr)
+---     setmetatable(arr, cjson.empty_array_mt)
+---
+---     return cjson.encode({some_array = arr})
+--- end
+---```
+---
+--- Both will generate:
+---
+---```json
+--- {
+---     "some_array": []
+--- }
+---```
+---
+--- **NOTE:** This field is specific to the OpenResty cjson fork.
+---
+---@alias cjson.empty_array_mt table
+
+
+--- When lua-cjson encodes a table with this metatable, it will systematically
+--- encode it as a JSON Array. The resulting, encoded Array will contain the
+--- array part of the table, and will be of the same length as the `#` operator
+--- on that table. Holes in the table will be encoded with the null JSON value.
+---
+--- ## Example
+---
+---```lua
+--- local t = { "hello", "world" }
+--- setmetatable(t, cjson.array_mt)
+--- cjson.encode(t) -- ["hello","world"]
+---```
+---
+--- Or:
+---
+---```lua
+--- local t = {}
+--- t[1] = "one"
+--- t[2] = "two"
+--- t[4] = "three"
+--- t.foo = "bar"
+--- setmetatable(t, cjson.array_mt)
+--- cjson.encode(t) -- ["one","two",null,"three"]
+---```
+---
+--- **NOTE:** This field is specific to the OpenResty cjson fork.
+---
+--- This value was introduced in the 2.1.0.5 release of this module.
+---
+---@alias cjson.array_mt table
+
+
+--- Sentinel type that denotes a JSON `null` value
+---@alias cjson.null lightuserdata
+
+
+--- A lightuserdata, similar to `cjson.null`, which will be encoded as an empty
+--- JSON Array by `cjson.encode()`.
+---
+--- For example, since encode_empty_table_as_object is true by default:
+---
+---```lua
+--- local cjson = require "cjson"
+---
+--- local json = cjson.encode({
+---     foo = "bar",
+---     some_object = {},
+---     some_array = cjson.empty_array
+--- })
+---```
+---
+--- This will generate:
+---
+---```json
+--- {
+---     "foo": "bar",
+---     "some_object": {},
+---     "some_array": []
+--- }
+---```
+---
+--- **NOTE:** This field is specific to the OpenResty cjson fork.
+---
+---@alias cjson.empty_array lightuserdata
+
+
+--- unserialize a json string to a lua value
+---
+--- `cjson.decode` will deserialise any UTF-9 JSON string into a Lua value or table.
+---
+--- UTF-16 and UTF-32 JSON strings are not supported.
+---
+--- cjson.decode requires that any NULL (ASCII 0) and double quote (ASCII 34) characters are escaped within strings. All escape codes will be decoded and other bytes will be passed transparently. UTF-8 characters are not validated during decoding and should be checked elsewhere if required.
+---
+--- JSON null will be converted to a NULL lightuserdata value. This can be compared with `cjson.null` for convenience.
+---
+--- By default, numbers incompatible with the JSON specification (infinity, NaN, hexadecimal) can be decoded. This default can be changed with `cjson.decode_invalid_numbers()`.
+---
+--- ```lua
+--- local json_text '[ true, { "foo": "bar" } ]'
+--- cjson.decode(json_text) --> { true, { foo = "bar" } }
+--- ```
+---
+---@param json string
+---@return any
+function cjson.decode(json) end
+
+
+--- decode_invalid_numbers
+---
+--- Lua CJSON may generate an error when trying to decode numbers not supported
+--- by the JSON specification. Invalid numbers are defined as:
+---
+---  * infinity
+---  * not-a-number (NaN)
+---  * hexadecimal
+---
+--- Available settings:
+---
+---  * `true`: Accept and decode invalid numbers. This is the default setting.
+---  * `false`:  Throw an error when invalid numbers are encountered.
+---
+--- The current setting is always returned, and is only updated when an argument is provided.
+---
+---@param setting? boolean # (default: `true`)
+---@return boolean setting # the value of the current setting
+function cjson.decode_invalid_numbers(setting) end
+
+
+--- decode_max_depth
+---
+--- Lua CJSON will generate an error when parsing deeply nested JSON once the
+--- maximum array/object depth has been exceeded.  This check prevents
+--- unnecessarily complicated JSON from slowing down the application, or crashing
+--- the application due to lack of process stack space.
+---
+--- An error may be generated before the depth limit is hit if Lua is unable to
+--- allocate more objects on the Lua stack.
+---
+--- By default, Lua CJSON will reject JSON with arrays and/or objects nested
+--- more than 1000 levels deep.
+---
+--- The current setting is always returned, and is only updated when an argument is provided.
+---
+---@param depth? integer # must be positive (default `1000`)
+---@return integer depth
+function cjson.decode_max_depth(depth) end
+
+
+--- decode_array_with_array_mt
+---
+--- If enabled, JSON Arrays decoded by cjson.decode will result in Lua tables
+--- with the array_mt metatable. This can ensure a 1-to-1 relationship between
+--- arrays upon multiple encoding/decoding of your JSON data with this module.
+---
+--- If disabled, JSON Arrays will be decoded to plain Lua tables, without the
+--- `cjson.array_mt` metatable.
+---
+--- ## Example
+---
+---```lua
+--- local cjson = require "cjson"
+---
+--- -- default behavior
+--- local my_json = [[{"my_array":[]}]]
+--- local t = cjson.decode(my_json)
+--- cjson.encode(t) -- {"my_array":{}} back to an object
+---
+--- -- now, if this behavior is enabled
+--- cjson.decode_array_with_array_mt(true)
+---
+--- local my_json = [[{"my_array":[]}]]
+--- local t = cjson.decode(my_json)
+--- cjson.encode(t) -- {"my_array":[]} properly re-encoded as an array
+---```
+---
+--- **NOTE:** This function is specific to the OpenResty cjson fork.
+---
+---@param enabled boolean # (default: false)
+function cjson.decode_array_with_array_mt(enabled) end
+
+
+--- serialize a lua value to a json string
+---
+--- cjson.encode will serialise a Lua value into a string containing the JSON representation.
+---
+--- cjson.encode supports the following types:
+---
+---  * boolean
+---  * lightuserdata (NULL value only)
+---  * nil
+---  * number
+---  * string
+---  * table
+---
+--- The remaining Lua types will generate an error:
+---
+---  * function
+---  * lightuserdata (non-NULL values)
+---  * thread
+---  * userdata
+---
+--- By default, numbers are encoded with 14 significant digits. Refer to cjson.encode_number_precision for details.
+---
+--- Lua CJSON will escape the following characters within each UTF-8 string:
+---
+---  * Control characters (ASCII 0 - 31)
+---  * Double quote (ASCII 34)
+---  * Forward slash (ASCII 47)
+---  * Blackslash (ASCII 92)
+---  * Delete (ASCII 127)
+---
+--- All other bytes are passed transparently.
+---
+---
+--- ## Caution
+---
+--- Lua CJSON will successfully encode/decode binary strings, but this is technically not supported by JSON and may not be compatible with other JSON libraries. To ensure the output is valid JSON, applications should ensure all Lua strings passed to cjson.encode are UTF-8.
+---
+--- ---
+--- Base64 is commonly used to encode binary data as the most efficient encoding under UTF-8 can only reduce the encoded size by a further ~8%. Lua Base64 routines can be found in the LuaSocket and lbase64 packages.
+---
+--- Lua CJSON uses a heuristic to determine whether to encode a Lua table as a JSON array or an object. A Lua table with only positive integer keys of type number will be encoded as a JSON array. All other tables will be encoded as a JSON object.
+---
+--- Lua CJSON does not use metamethods when serialising tables.
+---
+---  * `rawget()` is used to iterate over Lua arrays
+---  * `next()` is used to iterate over Lua objects
+---
+--- Lua arrays with missing entries (sparse arrays) may optionally be encoded in
+--- several different ways. Refer to cjson.encode_sparse_array for details.
+---
+--- JSON object keys are always strings. Hence cjson.encode only supports table
+--- keys which are type number or string. All other types will generate an error.
+---
+--- ## Note
+--- 	Standards compliant JSON must be encapsulated in either an object ({}) or an array ([]). If strictly standards compliant JSON is desired, a table must be passed to cjson.encode.
+---
+--- ---
+---
+--- By default, encoding the following Lua values will generate errors:
+---
+---  * Numbers incompatible with the JSON specification (infinity, NaN)
+---  * Tables nested more than 1000 levels deep
+---  * Excessively sparse Lua arrays
+---
+--- These defaults can be changed with:
+---
+---  * cjson.encode_invalid_numbers
+---  * cjson.encode_max_depth
+---  * cjson.encode_sparse_array
+---
+---```lua
+--- local value = { true, { foo = "bar" } }
+--- cjson.encode(value) --> '[true,{"foo":"bar"}]'
+---```
+---
+---@param value any
+---@return string json
+function cjson.encode(value) end
+
+
+--- encode_invalid_numbers
+---
+--- Lua CJSON may generate an error when encoding floating point numbers not
+--- supported by the JSON specification (invalid numbers):
+---
+---  * infinity
+---  * not-a-number (NaN)
+---
+--- Available settings:
+---
+--- * `true`: Allow invalid numbers to be encoded. This will generate non-standard JSON, but this output is supported by some libraries.
+--- * `false`: Throw an error when attempting to encode invalid numbers. This is the default setting.
+--- * `"null"`: Encode invalid numbers as a JSON null value. This allows infinity and NaN to be encoded into valid JSON.
+---
+--- The current setting is always returned, and is only updated when an argument is provided.
+---
+---@param setting? boolean|'"null"'
+---@return boolean|'"null"' setting
+function cjson.encode_invalid_numbers(setting) end
+
+
+--- encode_keep_buffer
+---
+--- Lua CJSON can reuse the JSON encoding buffer to improve performance.
+---
+--- Available settings:
+---
+--- * `true` - The buffer will grow to the largest size required and is not freed until the Lua CJSON module is garbage collected. This is the default setting.
+--- * `false` - Free the encode buffer after each call to cjson.encode.
+---
+--- The current setting is always returned, and is only updated when an argument is provided.
+---
+---@param setting? boolean
+---@return boolean setting
+function cjson.encode_keep_buffer(setting) end
+
+
+--- encode_max_depth
+---
+--- Once the maximum table depth has been exceeded Lua CJSON will generate an
+--- error. This prevents a deeply nested or recursive data structure from
+--- crashing the application.
+---
+--- By default, Lua CJSON will generate an error when trying to encode data
+--- structures with more than 1000 nested tables.
+---
+--- The current setting is always returned, and is only updated when an argument is provided.
+---
+---@param depth? integer # must be positive (default `1000`)
+---@return integer depth
+function cjson.encode_max_depth(depth) end
+
+
+--- encode_number_precision
+---
+--- The amount of significant digits returned by Lua CJSON when encoding numbers
+--- can be changed to balance accuracy versus performance. For data structures
+--- containing many numbers, setting cjson.encode_number_precision to a smaller
+--- integer, for example 3, can improve encoding performance by up to 50%.
+---
+--- By default, Lua CJSON will output 14 significant digits when converting a number to text.
+---
+--- The current setting is always returned, and is only updated when an argument is provided.
+---
+--- **NOTE:** The maximum value of 16 is only supported by the OpenResty cjson
+--- fork. The maximum in the upstream mpx/lua-cjson module is 14.
+---
+---@param precision? integer # must be between 1 and 16
+---@return integer precision
+function cjson.encode_number_precision(precision) end
+
+
+--- encode_sparse_array
+---
+--- Lua CJSON classifies a Lua table into one of three kinds when encoding a JSON array. This is determined by the number of values missing from the Lua array as follows:
+---
+---  * Normal - All values are available.
+---  * Sparse - At least 1 value is missing.
+---  * Excessively sparse - The number of values missing exceeds the configured ratio.
+---
+--- Lua CJSON encodes sparse Lua arrays as JSON arrays using JSON null for the missing entries.
+---
+--- An array is excessively sparse when all the following conditions are met:
+---
+---  * ratio > 0
+---  * maximum_index > safe
+---  * maximum_index > item_count * ratio
+---
+--- Lua CJSON will never consider an array to be excessively sparse when ratio = 0.
+--- The safe limit ensures that small Lua arrays are always encoded as sparse arrays.
+---
+--- By default, attempting to encode an excessively sparse array will generate
+--- an error. If convert is set to true, excessively sparse arrays will be
+--- converted to a JSON object.
+---
+--- The current settings are always returned. A particular setting is only
+--- changed when the argument is provided (non-nil).
+---
+--- ## Example: Encoding a sparse array
+---
+---```lua
+--- cjson.encode({ [3] = "data" })
+--- -- Returns: '[null,null,"data"]'
+---```
+---
+--- ## Example: Enabling conversion to a JSON object
+---
+---```lua
+--- cjson.encode_sparse_array(true)
+--- cjson.encode({ [1000] = "excessively sparse" })
+--- -- Returns: '{"1000":"excessively sparse"}'
+---```
+---
+---@param convert? boolean # (default: false)
+---@param ratio? integer   # must be positive (default: 2)
+---@param safe?  integer   # must be positive (default: 10)
+---@return boolean convert
+---@return integer ratio
+---@return integer safe
+function cjson.encode_sparse_array(convert, ratio, safe) end
+
+
+--- encode_empty_table_as_object
+---
+--- Change the default behavior when encoding an empty Lua table.
+---
+--- By default, empty Lua tables are encoded as empty JSON Objects (`{}`). If
+--- this is set to false, empty Lua tables will be encoded as empty JSON Arrays
+--- instead (`[]`).
+---
+--- **NOTE:** This function is specific to the OpenResty cjson fork.
+---
+---@param setting boolean|'"on"'|'"off"'
+function cjson.encode_empty_table_as_object(setting) end
+
+
+--- encode_escape_forward_slash
+---
+--- If enabled, forward slash '/' will be encoded as '\/'.
+---
+--- If disabled, forward slash '/' will be encoded as '/' (no escape is applied).
+---
+--- **NOTE:** This function is specific to the OpenResty cjson fork.
+---
+---@param enabled boolean # (default: true)
+function cjson.encode_escape_forward_slash(enabled) end
+
+
+--- instantiate an independent copy of the Lua CJSON module
+---
+--- The new module has a separate persistent encoding buffer, and default settings
+---@return cjson
+function cjson.new() end
+
+
+return cjson
diff --git a/meta/3rd/OpenResty/library/cjson.safe.lua b/meta/3rd/OpenResty/library/cjson.safe.lua
new file mode 100644
index 00000000..64244b15
--- /dev/null
+++ b/meta/3rd/OpenResty/library/cjson.safe.lua
@@ -0,0 +1,46 @@
+---@meta
+
+--- The `cjson.safe` module behaves identically to the `cjson` module, except when
+--- errors are encountered during JSON conversion. On error, the `cjson.safe.encode`
+--- and `cjson.safe.decode` functions will return `nil` followed by the error message.
+---
+--- @see cjson
+---
+---@class cjson.safe : cjson
+local cjson_safe = {}
+
+
+--- unserialize a json string to a lua value
+---
+--- Returns `nil` and an error string when the input cannot be decoded.
+---
+--- ```lua
+--- local value, err = cjson_safe.decode(some_json_string)
+--- ```
+---@param json string
+---@return any? decoded
+---@return string? error
+function cjson_safe.decode(json) end
+
+
+--- serialize a lua value to a json string
+---
+--- Returns `nil` and an error string when the input cannot be encoded.
+---
+--- ```lua
+--- local json, err = cjson_safe.encode(some_lua_value)
+--- ```
+---@param value any
+---@return string? encoded
+---@return string? error
+function cjson_safe.encode(value) end
+
+
+--- instantiate an independent copy of the Lua CJSON module
+---
+--- The new module has a separate persistent encoding buffer, and default settings
+---@return cjson.safe
+function cjson_safe.new() end
+
+
+return cjson_safe
diff --git a/meta/3rd/OpenResty/library/resty.dns.resolver.lua b/meta/3rd/OpenResty/library/resty.dns.resolver.lua
index fc43a4cc..1ddc1b5b 100644
--- a/meta/3rd/OpenResty/library/resty.dns.resolver.lua
+++ b/meta/3rd/OpenResty/library/resty.dns.resolver.lua
@@ -1,26 +1,424 @@
 ---@meta
-resty_dns_resolver={}
-resty_dns_resolver.SECTION_NS=2
-resty_dns_resolver.SECTION_AN=1
-resty_dns_resolver.TYPE_AAAA=28
-function resty_dns_resolver.new(class, opts) end
-resty_dns_resolver.TYPE_NS=2
-function resty_dns_resolver.query(self, qname, opts, tries) end
-resty_dns_resolver.TYPE_A=1
-function resty_dns_resolver.compress_ipv6_addr(addr) end
-resty_dns_resolver.TYPE_SRV=33
-resty_dns_resolver.TYPE_PTR=12
-function resty_dns_resolver.reverse_query(self, addr) end
-resty_dns_resolver.TYPE_SPF=99
-resty_dns_resolver._VERSION="0.21"
-function resty_dns_resolver.expand_ipv6_addr() end
-function resty_dns_resolver.set_timeout(self, timeout) end
-function resty_dns_resolver.tcp_query(self, qname, opts) end
-resty_dns_resolver.TYPE_TXT=16
-resty_dns_resolver.TYPE_SOA=6
-resty_dns_resolver.TYPE_MX=15
-resty_dns_resolver.CLASS_IN=1
-function resty_dns_resolver.arpa_str(addr) end
-resty_dns_resolver.SECTION_AR=3
-resty_dns_resolver.TYPE_CNAME=5
-return resty_dns_resolver
\ No newline at end of file
+
+---
+--- lua-resty-dns - Lua DNS resolver for the ngx_lua based on the cosocket API
+---
+--- https://github.com/openresty/lua-resty-dns
+---
+---# Description
+---
+--- This Lua library provides a DNS resolver for the ngx_lua nginx module:
+---
+--- https://github.com/openresty/lua-nginx-module/#readme
+---
+--- This Lua library takes advantage of ngx_lua's cosocket API, which ensures
+--- 100% nonblocking behavior.
+---
+--- Note that at least [ngx_lua 0.5.12](https://github.com/openresty/lua-nginx-module/tags) or [OpenResty 1.2.1.11](http://openresty.org/#Download) is required.
+---
+--- Also, the [bit library](http://bitop.luajit.org/) is also required. If you're using LuaJIT 2.0 with ngx_lua, then the `bit` library is already available by default.
+---
+--- Note that, this library is bundled and enabled by default in the [OpenResty bundle](http://openresty.org/).
+---
+--- IMPORTANT: to be able to generate unique ids, the random generator must be properly seeded using `math.randomseed` prior to using this module.
+---
+---# Automatic Error Logging
+---
+--- By default, the underlying [ngx_lua](https://github.com/openresty/lua-nginx-module/#readme) module does error logging when socket errors happen. If you are already doing proper error handling in your own Lua code, then you are recommended to disable this automatic error logging by turning off [ngx_lua](https://github.com/openresty/lua-nginx-module/#readme)'s [lua_socket_log_errors](https://github.com/openresty/lua-nginx-module/#lua_socket_log_errors) directive, that is:
+---
+---```nginx
+---    lua_socket_log_errors off;
+---```
+---
+---# Limitations
+---
+--- * This library cannot be used in code contexts like `set_by_lua*`, `log_by_lua*`, and `header_filter_by_lua*` where the ngx_lua cosocket API is not available.
+--- * The `resty.dns.resolver` object instance cannot be stored in a Lua variable at the Lua module level, because it will then be shared by all the concurrent requests handled by the same nginx worker process (see https://github.com/openresty/lua-nginx-module/#data-sharing-within-an-nginx-worker ) and result in bad race conditions when concurrent requests are trying to use the same `resty.dns.resolver` instance. You should always initiate `resty.dns.resolver` objects in function local variables or in the `ngx.ctx` table. These places all have their own data copies for each request.
+---
+---@class resty.dns.resolver
+---@field _VERSION string
+---
+--- undocumented/private fields--use at your own risk
+---
+---@field cur         integer
+---@field socks       udpsock[]
+---@field tcp_sock    tcpsock
+---@field servers     resty.dns.resolver.nameserver_tuple[]
+---@field retrans     integer
+---@field no_recurse  boolean
+local resolver = {}
+
+
+--- The `A` resource record type, equal to the decimal number 1.
+---@class resty.dns.resolver.TYPE_A
+resolver.TYPE_A = 1
+
+--- The `NS` resource record type, equal to the decimal number `2`.
+---@class resty.dns.resolver.TYPE_NS
+resolver.TYPE_NS = 2
+
+--- The `CNAME` resource record type, equal to the decimal number `5`.
+---@class resty.dns.resolver.TYPE_CNAME
+resolver.TYPE_CNAME = 5
+
+--- The `SOA` resource record type, equal to the decimal number `6`.
+---@class resty.dns.resolver.TYPE_SOA
+resolver.TYPE_SOA = 6
+
+--- The `PTR` resource record type, equal to the decimal number `12`.
+---@class resty.dns.resolver.TYPE_PTR
+resolver.TYPE_PTR = 12
+
+--- The `MX` resource record type, equal to the decimal number `15`.
+---@class resty.dns.resolver.TYPE_MX
+resolver.TYPE_MX = 15
+
+--- The `TXT` resource record type, equal to the decimal number `16`.
+---@class resty.dns.resolver.TYPE_TXT
+resolver.TYPE_TXT = 16
+
+--- The `AAAA` resource record type, equal to the decimal number `28`.
+---@class resty.dns.resolver.TYPE_AAAA
+resolver.TYPE_AAAA = 28
+
+--- The `SRV` resource record type, equal to the decimal number `33`.
+---
+--- See RFC 2782 for details.
+---@class resty.dns.resolver.TYPE_SRV
+resolver.TYPE_SRV = 33
+
+--- The `SPF` resource record type, equal to the decimal number `99`.
+---
+--- See RFC 4408 for details.
+---@class resty.dns.resolver.TYPE_SPF
+resolver.TYPE_SPF = 99
+
+
+---@alias resty.dns.resolver.TYPE integer
+---| `resolver.TYPE_A`     # A
+---| 1                     # A
+---| `resolver.TYPE_NS`    # NS
+---| 2                     # NS
+---| `resolver.TYPE_CNAME` # CNAME
+---| 5                     # CNAME
+---| `resolver.TYPE_SOA`   # SOA
+---| 6                     # SOA
+---| `resolver.TYPE_PTR`   # PTR
+---| 12                    # PTR
+---| `resolver.TYPE_MX`    # MX
+---| 15                    # MX
+---| `resolver.TYPE_TXT`   # TXT
+---| 16                    # TXT
+---| `resolver.TYPE_AAAA`  # AAAA
+---| 28                    # AAAA
+---| `resolver.TYPE_SRV`   # SRV
+---| 33                    # SRV
+---| `resolver.TYPE_SPF`   # SPF
+---| 99                    # SPF
+
+
+---@alias resty.dns.resolver.CLASS integer
+---| `resolver.CLASS_IN`
+---| 1
+
+--- The `Internet` resource record type
+---@class resty.dns.resolver.CLASS_IN
+resolver.CLASS_IN = 1
+
+
+---@alias resty.dns.resolver.SECTION integer
+---| `resolver.SECTION_AN` # Answer section
+---| 1                     # Answer section
+---| `resolver.SECTION_NS` # Authority section
+---| 2                     # Authority section
+---| `resolver.SECTION_AR` # Additional section
+---| 3                     # Additional section
+
+
+--- Identifier of the `Answer` section in the DNS response.
+---@class resty.dns.resolver.SECTION_AN
+resolver.SECTION_AN = 1
+
+
+--- Identifier of the `Authority` section in the DNS response.
+---@class resty.dns.resolver.SECTION_NS
+resolver.SECTION_NS = 2
+
+
+--- Identifier of the `Additional` section in the DNS response.
+---@class resty.dns.resolver.SECTION_AR
+resolver.SECTION_AR = 3
+
+
+---@alias resty.dns.resolver.ERRCODE integer
+---| 1  # format error
+---| 2  # server failure
+---| 3  # name error
+---| 4  # not implemented
+---| 5  # refused
+
+
+---@alias resty.dns.resolver.ERRSTR
+---| "format error"    # errcode 1
+---| "server failure"  # errcode 2
+---| "name error"      # errcode 3
+---| "not implemented" # errcode 4
+---| "refused"         # errcode 5
+---| "unknown"         # errcode unknown
+
+
+--- Creates a dns.resolver object.
+---
+--- On error, returns `nil` and an error string.
+---
+---@param opts resty.dns.resolver.new.opts
+---@return resty.dns.resolver? resolver
+---@return string? error
+function resolver:new(opts) end
+
+
+---@class resty.dns.resolver.nameserver_tuple
+---@field [1] string  # hostname or addr
+---@field [2] integer # port number
+
+---@alias resty.dns.resolver.nameserver
+---| string
+---| resty.dns.resolver.nameserver_tuple
+
+
+--- Options for `resty.dns.resolver:new()`
+---
+---@class resty.dns.resolver.new.opts : table
+---
+---@field nameservers resty.dns.resolver.nameserver[] # a list of nameservers to be used. Each nameserver entry can be either a single hostname string or a table holding both the hostname string and the port number. The nameserver is picked up by a simple round-robin algorithm for each `query` method call. This option is required.
+---
+---@field retrans? number # (default: `5`) the total number of times of retransmitting the DNS request when receiving a DNS response times out according to the `timeout` setting. When trying to retransmit the query, the next nameserver according to the round-robin algorithm will be picked up.
+---
+---@field timeout? number # (default: `2000`) the time in milliseconds for waiting for the response for a single attempt of request transmission. note that this is ''not'' the maximal total waiting time before giving up, the maximal total waiting time can be calculated by the expression `timeout x retrans`. The `timeout` setting can also be changed by calling the `set_timeout` method.
+---
+---@field no_recurse? boolean # (default: `false`) a boolean flag controls whether to disable the "recursion desired" (RD) flag in the UDP request.
+---
+---@field no_random? boolean # (default: `false`) a boolean flag controls whether to randomly pick the nameserver to query first, if `true` will always start with the first nameserver listed.
+
+
+--- Performs a DNS standard query.
+---
+--- The query is sent to the nameservers specified by the `new` method, and
+---
+--- Returns all the answer records in an array-like Lua table.
+---
+--- In case of errors, it will return nil and a string describing the error instead.
+---
+--- If the server returns a non-zero error code, the fields `errcode` and `errstr` will be set accordingly in the Lua table returned.
+---
+--- The optional parameter `tries` can be provided as an empty table, and will be returned as a third result. The table will be an array with the error message for each (if any) failed try.
+---
+--- When data truncation happens, the resolver will automatically retry using the TCP transport mode to query the current nameserver. All TCP connections are short lived.
+---
+---@param qname string
+---@param opts? resty.dns.resolver.query.opts
+---@param tries? string[]
+---@return resty.dns.resolver.query.answer[] results
+---@return string? error
+---@return string[]? tries
+function resolver:query(qname, opts, tries) end
+
+
+---@class resty.dns.resolver.answer : table
+---
+---@field name string # The resource record name.
+---
+---@field type resty.dns.resolver.TYPE # The current resource record type, possible values are 1 (TYPE_A), 5 (TYPE_CNAME), 28 (TYPE_AAAA), and any other values allowed by RFC 1035.
+---
+---@field section resty.dns.resolver.SECTION # The identifier of the section that the current answer record belongs to. Possible values are 1 (SECTION_AN), 2 (SECTION_NS), and 3 (SECTION_AR).
+---
+---@field ttl number # The time-to-live (TTL) value in seconds for the current resource record.
+---
+---@field class resty.dns.resolver.CLASS # The current resource record class, possible values are 1 (CLASS_IN) or any other values allowed by RFC 1035.
+---
+---@field rdata string # The raw resource data (RDATA) for resource records that are not recognized.
+---
+---@field errcode? resty.dns.resolver.ERRCODE # Error code returned by the DNS server
+---
+---@field errstr? resty.dns.resolver.ERRSTR # Error string returned by the DNS server
+
+
+--- A-type answer
+---
+---@class resty.dns.resolver.answer.A : resty.dns.resolver.answer
+---
+---@field address string # The IPv4 address.
+
+--- AAAA-type answer
+---
+---@class resty.dns.resolver.answer.AAAA : resty.dns.resolver.answer
+---
+---@field address string # The IPv6 address. Successive 16-bit zero groups in IPv6 addresses will not be compressed by default, if you want that, you need to call the compress_ipv6_addr static method instead.
+
+
+--- CNAME-type answer
+---
+---@class resty.dns.resolver.answer.CNAME : resty.dns.resolver.answer
+---
+---@field cname? string # The (decoded) record data value for CNAME resource records.
+
+
+--- MX-type answer
+---
+---@class resty.dns.resolver.answer.MX : resty.dns.resolver.answer
+---
+---@field preference integer # The preference integer number for MX resource records.
+---
+---@field exchange? string # The exchange domain name for MX resource records.
+
+
+--- SRV-type answer
+---
+---@class resty.dns.resolver.answer.SRV : resty.dns.resolver.answer
+---
+---@field priority number
+---
+---@field weight number
+---
+---@field port integer
+---
+---@field target string
+
+
+--- NS-type answer
+---
+---@class resty.dns.resolver.answer.NS : resty.dns.resolver.answer
+---
+---@field nsdname string # A domain-name which specifies a host which should be authoritative for the specified class and domain. Usually present for NS type records.
+---
+
+
+--- TXT-type answer
+---
+---@class resty.dns.resolver.answer.TXT : resty.dns.resolver.answer
+---
+---@field txt? string|string[] # The record value for TXT records. When there is only one character string in this record, then this field takes a single Lua string. Otherwise this field takes a Lua table holding all the strings.
+
+
+--- SPF-type answer
+---
+---@class resty.dns.resolver.answer.SPF : resty.dns.resolver.answer
+---
+---@field spf? string|string[] # The record value for SPF records. When there is only one character string in this record, then this field takes a single Lua string. Otherwise this field takes a Lua table holding all the strings.
+
+
+--- PTR-type answer
+---
+---@class resty.dns.resolver.answer.PTR : resty.dns.resolver.answer
+---
+---@field ptrdname string # The record value for PTR records.
+
+
+--- SOA-type answer
+---
+---@class resty.dns.resolver.answer.SOA : resty.dns.resolver.answer
+---
+---@field serial   integer # SOA serial
+---@field refresh  integer # SOA refresh
+---@field retry    integer # SOA retry
+---@field expire   integer # SOA expire
+---@field minimum  integer # SOA minimum
+
+
+---@alias resty.dns.resolver.query.answer
+---| resty.dns.resolver.answer
+---| resty.dns.resolver.answer.A
+---| resty.dns.resolver.answer.AAAA
+---| resty.dns.resolver.answer.CNAME
+---| resty.dns.resolver.answer.MX
+---| resty.dns.resolver.answer.NS
+---| resty.dns.resolver.answer.PTR
+---| resty.dns.resolver.answer.SOA
+---| resty.dns.resolver.answer.SPF
+---| resty.dns.resolver.answer.SRV
+---| resty.dns.resolver.answer.TXT
+
+
+--- Options for `resty.dns.resolver:query()`
+---
+---@class resty.dns.resolver.query.opts : table
+---
+---@field qtype? resty.dns.resolver.TYPE # (default: `1`) The type of the question. Possible values are 1 (TYPE_A), 5 (TYPE_CNAME), 28 (TYPE_AAAA), or any other QTYPE value specified by RFC 1035 and RFC 3596.
+---
+---@field authority_section? boolean # (default: `false`) When `true`, the answers return value includes the `Authority` section of the DNS response.
+---
+---@field additional_section? boolean # (default: `false`) When `true`, the answers return value includes the `Additional` section of the DNS response.
+
+
+--- Just like the query method, but enforce the TCP transport mode instead of UDP.
+---
+--- All TCP connections are short lived.
+---
+---@param qname string
+---@param opts? resty.dns.resolver.query.opts
+---@return resty.dns.resolver.query.answer[] results
+---@return string? error
+function resolver:tcp_query(qname, opts) end
+
+
+--- Performs a PTR lookup for both IPv4 and IPv6 addresses.
+---
+--- This function is basically a wrapper for the query command which uses the `arpa_str` function to convert the IP address on the fly.
+---
+---@param addr string
+---@return resty.dns.resolver.query.answer[] results
+---@return string? error
+function resolver:reverse_query(addr) end
+
+
+--- Overrides the current timeout setting for all nameserver peers.
+---
+---@param timeout number # timeout in milliseconds
+function resolver:set_timeout(timeout) end
+
+--- Compresses the successive 16-bit zero groups in the textual format of the IPv6 address.
+---
+--- For example, the following will yield `FF01::101` in the new_addr return value:
+---
+---```lua
+---  local resolver = require "resty.dns.resolver"
+---  local compress = resolver.compress_ipv6_addr
+---  local new_addr = compress("FF01:0:0:0:0:0:0:101")
+---```
+---
+---@param addr string
+---@return string compressed
+function resolver.compress_ipv6_addr(addr) end
+
+--- Expands the successive 16-bit zero groups in the textual format of the IPv6 address.
+---
+--- For example, the following will yield `FF01:0:0:0:0:0:0:101` in the new_addr return value:
+---
+---```lua
+---  local resolver = require "resty.dns.resolver"
+---  local expand = resolver.expand_ipv6_addr
+---  local new_addr = expand("FF01::101")
+---```
+---
+---@param addr string
+---@return string expanded
+function resolver.expand_ipv6_addr(addr) end
+
+--- Generates the reverse domain name for PTR lookups for both IPv4 and IPv6 addresses.
+---
+--- Compressed IPv6 addresses will be automatically expanded.
+---
+--- For example, the following will yield `4.3.2.1.in-addr.arpa` for `ptr4` and `1.0.1.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.0.1.0.F.F.ip6.arpa` for `ptr6`:
+---
+---```lua
+---  local resolver = require "resty.dns.resolver"
+---  local ptr4 = resolver.arpa_str("1.2.3.4")
+---  local ptr6 = resolver.arpa_str("FF01::101")
+---```
+---
+---@param addr string
+---@return string
+function resolver.arpa_str(addr) end
+
+
+return resolver
\ No newline at end of file
diff --git a/meta/3rd/OpenResty/library/string.buffer.lua b/meta/3rd/OpenResty/library/string.buffer.lua
new file mode 100644
index 00000000..70ecc6d8
--- /dev/null
+++ b/meta/3rd/OpenResty/library/string.buffer.lua
@@ -0,0 +1,352 @@
+---@meta
+
+
+--- The string buffer library allows high-performance manipulation of string-like data.
+---
+--- Unlike Lua strings, which are constants, string buffers are mutable sequences of 8-bit (binary-transparent) characters. Data can be stored, formatted and encoded into a string buffer and later converted, extracted or decoded.
+---
+--- The convenient string buffer API simplifies common string manipulation tasks, that would otherwise require creating many intermediate strings. String buffers improve performance by eliminating redundant memory copies, object creation, string interning and garbage collection overhead. In conjunction with the FFI library, they allow zero-copy operations.
+---
+--- The string buffer libary also includes a high-performance serializer for Lua objects.
+---
+---
+---## Streaming Serialization
+---
+--- In some contexts, it's desirable to do piecewise serialization of large datasets, also known as streaming.
+---
+--- This serialization format can be safely concatenated and supports streaming. Multiple encodings can simply be appended to a buffer and later decoded individually:
+---
+--- ```lua
+--- local buf = buffer.new()
+--- buf:encode(obj1)
+--- buf:encode(obj2)
+--- local copy1 = buf:decode()
+--- local copy2 = buf:decode()
+--- ```
+---
+--- Here's how to iterate over a stream:
+---
+--- ```lua
+--- while #buf ~= 0 do
+---   local obj = buf:decode()
+---   -- Do something with obj.
+--- end
+--- ```
+---
+--- Since the serialization format doesn't prepend a length to its encoding, network applications may need to transmit the length, too.
+--- Serialization Format Specification
+---
+--- This serialization format is designed for internal use by LuaJIT applications. Serialized data is upwards-compatible and portable across all supported LuaJIT platforms.
+---
+--- It's an 8-bit binary format and not human-readable. It uses e.g. embedded zeroes and stores embedded Lua string objects unmodified, which are 8-bit-clean, too. Encoded data can be safely concatenated for streaming and later decoded one top-level object at a time.
+---
+--- The encoding is reasonably compact, but tuned for maximum performance, not for minimum space usage. It compresses well with any of the common byte-oriented data compression algorithms.
+---
+--- Although documented here for reference, this format is explicitly not intended to be a 'public standard' for structured data interchange across computer languages (like JSON or MessagePack). Please do not use it as such.
+---
+--- The specification is given below as a context-free grammar with a top-level object as the starting point. Alternatives are separated by the | symbol and * indicates repeats. Grouping is implicit or indicated by {…}. Terminals are either plain hex numbers, encoded as bytes, or have a .format suffix.
+---
+--- ```
+--- object    → nil | false | true
+---           | null | lightud32 | lightud64
+---           | int | num | tab | tab_mt
+---           | int64 | uint64 | complex
+---           | string
+---
+--- nil       → 0x00
+--- false     → 0x01
+--- true      → 0x02
+---
+--- null      → 0x03                            // NULL lightuserdata
+--- lightud32 → 0x04 data.I                   // 32 bit lightuserdata
+--- lightud64 → 0x05 data.L                   // 64 bit lightuserdata
+---
+--- int       → 0x06 int.I                                 // int32_t
+--- num       → 0x07 double.L
+---
+--- tab       → 0x08                                   // Empty table
+---           | 0x09 h.U h*{object object}          // Key/value hash
+---           | 0x0a a.U a*object                    // 0-based array
+---           | 0x0b a.U a*object h.U h*{object object}      // Mixed
+---           | 0x0c a.U (a-1)*object                // 1-based array
+---           | 0x0d a.U (a-1)*object h.U h*{object object}  // Mixed
+--- tab_mt    → 0x0e (index-1).U tab          // Metatable dict entry
+---
+--- int64     → 0x10 int.L                             // FFI int64_t
+--- uint64    → 0x11 uint.L                           // FFI uint64_t
+--- complex   → 0x12 re.L im.L                         // FFI complex
+---
+--- string    → (0x20+len).U len*char.B
+---           | 0x0f (index-1).U                 // String dict entry
+---
+--- .B = 8 bit
+--- .I = 32 bit little-endian
+--- .L = 64 bit little-endian
+--- .U = prefix-encoded 32 bit unsigned number n:
+---      0x00..0xdf   → n.B
+---      0xe0..0x1fdf → (0xe0|(((n-0xe0)>>8)&0x1f)).B ((n-0xe0)&0xff).B
+---    0x1fe0..       → 0xff n.I
+--- ```
+---
+---## Error handling
+---
+--- Many of the buffer methods can throw an error. Out-of-memory or usage errors are best caught with an outer wrapper for larger parts of code. There's not much one can do after that, anyway.
+---
+--- OTOH you may want to catch some errors individually. Buffer methods need to receive the buffer object as the first argument. The Lua colon-syntax `obj:method()` does that implicitly. But to wrap a method with `pcall()`, the arguments need to be passed like this:
+---
+--- ```lua
+--- local ok, err = pcall(buf.encode, buf, obj)
+--- if not ok then
+---   -- Handle error in err.
+--- end
+--- ```
+---
+---## FFI caveats
+---
+--- The string buffer library has been designed to work well together with the FFI library. But due to the low-level nature of the FFI library, some care needs to be taken:
+---
+--- First, please remember that FFI pointers are zero-indexed. The space returned by `buf:reserve()` and `buf:ref()` starts at the returned pointer and ends before len bytes after that.
+---
+--- I.e. the first valid index is `ptr[0]` and the last valid index is `ptr[len-1]`. If the returned length is zero, there's no valid index at all. The returned pointer may even be `NULL`.
+---
+--- The space pointed to by the returned pointer is only valid as long as the buffer is not modified in any way (neither append, nor consume, nor reset, etc.). The pointer is also not a GC anchor for the buffer object itself.
+---
+--- Buffer data is only guaranteed to be byte-aligned. Casting the returned pointer to a data type with higher alignment may cause unaligned accesses. It depends on the CPU architecture whether this is allowed or not (it's always OK on x86/x64 and mostly OK on other modern architectures).
+---
+--- FFI pointers or references do not count as GC anchors for an underlying object. E.g. an array allocated with `ffi.new()` is anchored by `buf:set(array, len)`, but not by `buf:set(array+offset, len)`. The addition of the offset creates a new pointer, even when the offset is zero. In this case, you need to make sure there's still a reference to the original array as long as its contents are in use by the buffer.
+---
+--- Even though each LuaJIT VM instance is single-threaded (but you can create multiple VMs), FFI data structures can be accessed concurrently. Be careful when reading/writing FFI cdata from/to buffers to avoid concurrent accesses or modifications. In particular, the memory referenced by `buf:set(cdata, len)` must not be modified while buffer readers are working on it. Shared, but read-only memory mappings of files are OK, but only if the file does not change.
+local buffer = {}
+
+--- A buffer object is a garbage-collected Lua object. After creation with `buffer.new()`, it can (and should) be reused for many operations. When the last reference to a buffer object is gone, it will eventually be freed by the garbage collector, along with the allocated buffer space.
+---
+--- Buffers operate like a FIFO (first-in first-out) data structure. Data can be appended (written) to the end of the buffer and consumed (read) from the front of the buffer. These operations may be freely mixed.
+---
+--- The buffer space that holds the characters is managed automatically — it grows as needed and already consumed space is recycled. Use `buffer.new(size)` and `buf:free()`, if you need more control.
+---
+--- The maximum size of a single buffer is the same as the maximum size of a Lua string, which is slightly below two gigabytes. For huge data sizes, neither strings nor buffers are the right data structure — use the FFI library to directly map memory or files up to the virtual memory limit of your OS.
+---
+---@class string.buffer : table
+local buf = {}
+
+--- A string, number, or any object obj with a __tostring metamethod to the buffer.
+---
+---@alias string.buffer.data string|number|table
+
+
+--- Appends a string str, a number num or any object obj with a `__tostring` metamethod to the buffer. Multiple arguments are appended in the given order.
+---
+--- Appending a buffer to a buffer is possible and short-circuited internally. But it still involves a copy. Better combine the buffer writes to use a single buffer.
+---
+---@param data string.buffer.data
+---@param ...? string.buffer.data
+---@return string.buffer
+function buf:put(data, ...) end
+
+
+--- Appends the formatted arguments to the buffer. The format string supports the same options as string.format().
+---
+---@param format string
+---@param ...    string.buffer.data
+---@return string.buffer
+function buf:putf(format, ...) end
+
+
+--- Appends the given len number of bytes from the memory pointed to by the FFI cdata object to the buffer. The object needs to be convertible to a (constant) pointer.
+---
+---@param cdata ffi.cdata*
+---@param len   integer
+---@return string.buffer
+function buf:putcdata(cdata, len) end
+
+
+--- This method allows zero-copy consumption of a string or an FFI cdata object as a buffer. It stores a reference to the passed string str or the FFI cdata object in the buffer. Any buffer space originally allocated is freed. This is not an append operation, unlike the `buf:put*()` methods.
+---
+--- After calling this method, the buffer behaves as if `buf:free():put(str)` or `buf:free():put(cdata, len)` had been called. However, the data is only referenced and not copied, as long as the buffer is only consumed.
+---
+--- In case the buffer is written to later on, the referenced data is copied and the object reference is removed (copy-on-write semantics).
+---
+--- The stored reference is an anchor for the garbage collector and keeps the originally passed string or FFI cdata object alive.
+---
+---@param str string.buffer.data
+---@return string.buffer
+---@overload fun(self:string.buffer, cdata:ffi.cdata*, len:integer):string.buffer
+function buf:set(str) end
+
+--- Reset (empty) the buffer. The allocated buffer space is not freed and may be reused.
+---@return string.buffer
+function buf:reset() end
+
+
+--- The buffer space of the buffer object is freed. The object itself remains intact, empty and may be reused.
+---
+--- Note: you normally don't need to use this method. The garbage collector automatically frees the buffer space, when the buffer object is collected. Use this method, if you need to free the associated memory immediately.
+function buf:free() end
+
+
+--- The reserve method reserves at least size bytes of write space in the buffer. It returns an uint8_t * FFI cdata pointer ptr that points to this space.
+---
+--- The available length in bytes is returned in len. This is at least size bytes, but may be more to facilitate efficient buffer growth. You can either make use of the additional space or ignore len and only use size bytes.
+---
+--- This, along with `buf:commit()` allow zero-copy use of C read-style APIs:
+---
+--- ```lua
+--- local MIN_SIZE = 65536
+--- repeat
+---   local ptr, len = buf:reserve(MIN_SIZE)
+---   local n = C.read(fd, ptr, len)
+---   if n == 0 then break end -- EOF.
+---   if n < 0 then error("read error") end
+---   buf:commit(n)
+--- until false
+--- ```
+---
+--- The reserved write space is not initialized. At least the used bytes must be written to before calling the commit method. There's no need to call the commit method, if nothing is added to the buffer (e.g. on error).
+---@param size integer
+---@return ffi.cdata* ptr # an uint8_t * FFI cdata pointer that points to this space
+---@return integer len    # available length (bytes)
+function buf:reserve(size) end
+
+
+--- Appends the used bytes of the previously returned write space to the buffer data.
+---@param used integer
+---@return string.buffer
+function buf:commit(used) end
+
+
+--- Skips (consumes) len bytes from the buffer up to the current length of the buffer data.
+---@param len integer
+---@return string.buffer
+function buf:skip(len) end
+
+--- Consumes the buffer data and returns one or more strings. If called without arguments, the whole buffer data is consumed. If called with a number, up to `len` bytes are consumed. A `nil` argument consumes the remaining buffer space (this only makes sense as the last argument). Multiple arguments consume the buffer data in the given order.
+---
+--- Note: a zero length or no remaining buffer data returns an empty string and not `nil`.
+---
+---@param len? integer
+---@param ... integer|nil
+---@return string ...
+function buf:get(len, ...) end
+
+--- Creates a string from the buffer data, but doesn't consume it. The buffer remains unchanged.
+---
+--- Buffer objects also define a `__tostring metamethod`. This means buffers can be passed to the global `tostring()` function and many other functions that accept this in place of strings. The important internal uses in functions like `io.write()` are short-circuited to avoid the creation of an intermediate string object.
+---@return string
+function buf:tostring() end
+
+
+--- Returns an uint8_t * FFI cdata pointer ptr that points to the buffer data. The length of the buffer data in bytes is returned in len.
+---
+--- The returned pointer can be directly passed to C functions that expect a buffer and a length. You can also do bytewise reads (`local x = ptr[i]`) or writes (`ptr[i] = 0x40`) of the buffer data.
+---
+--- In conjunction with the `buf:skip()` method, this allows zero-copy use of C write-style APIs:
+---
+--- ```lua
+--- repeat
+---   local ptr, len = buf:ref()
+---   if len == 0 then break end
+---   local n = C.write(fd, ptr, len)
+---   if n < 0 then error("write error") end
+---   buf:skip(n)
+--- until n >= len
+--- ```
+---
+--- Unlike Lua strings, buffer data is not implicitly zero-terminated. It's not safe to pass ptr to C functions that expect zero-terminated strings. If you're not using len, then you're doing something wrong.
+---
+---@return ffi.cdata* ptr # an uint8_t * FFI cdata pointer that points to the buffer data.
+---@return integer len # length of the buffer data in bytes
+function buf:ref() end
+
+--- Serializes (encodes) the Lua object to the buffer
+---
+--- This function may throw an error when attempting to serialize unsupported object types, circular references or deeply nested tables.
+---@param obj string.buffer.data
+---@return string.buffer
+function buf:encode(obj) end
+
+
+--- De-serializes one object from the buffer.
+---
+--- The returned object may be any of the supported Lua types — even `nil`.
+---
+--- This function may throw an error when fed with malformed or incomplete encoded data.
+---
+--- Leaves any left-over data in the buffer.
+---
+--- Attempting to de-serialize an FFI type will throw an error, if the FFI library is not built-in or has not been loaded, yet.
+---
+---@return string.buffer.data|nil obj
+function buf:decode() end
+
+
+--- Serializes (encodes) the Lua object obj
+---
+--- This function may throw an error when attempting to serialize unsupported object types, circular references or deeply nested tables.
+---@param obj string.buffer.data
+---@return string
+function buffer.encode(obj) end
+
+--- De-serializes (decodes) the string to a Lua object
+---
+--- The returned object may be any of the supported Lua types — even `nil`.
+---
+--- Throws an error when fed with malformed or incomplete encoded data.
+--- Throws an error when there's left-over data after decoding a single top-level object.
+---
+--- Attempting to de-serialize an FFI type will throw an error, if the FFI library is not built-in or has not been loaded, yet.
+---
+---@param str string
+---@return string.buffer.data|nil obj
+function buffer.decode(str) end
+
+
+
+
+--- Creates a new buffer object.
+---
+--- The optional size argument ensures a minimum initial buffer size. This is strictly an optimization when the required buffer size is known beforehand. The buffer space will grow as needed, in any case.
+---
+--- The optional table options sets various serialization options.
+---
+---@param size? integer
+---@param options? string.buffer.serialization.opts
+---@return string.buffer
+function buffer.new(size, options) end
+
+--- Serialization Options
+---
+--- The options table passed to buffer.new() may contain the following members (all optional):
+---
+--- * `dict` is a Lua table holding a dictionary of strings that commonly occur as table keys of objects you are serializing. These keys are compactly encoded as indexes during serialization. A well chosen dictionary saves space and improves serialization performance.
+---
+--- * `metatable` is a Lua table holding a dictionary of metatables for the table objects you are serializing.
+---
+--- dict needs to be an array of strings and metatable needs to be an array of tables. Both starting at index 1 and without holes (no nil inbetween). The tables are anchored in the buffer object and internally modified into a two-way index (don't do this yourself, just pass a plain array). The tables must not be modified after they have been passed to buffer.new().
+---
+--- The dict and metatable tables used by the encoder and decoder must be the same. Put the most common entries at the front. Extend at the end to ensure backwards-compatibility — older encodings can then still be read. You may also set some indexes to false to explicitly drop backwards-compatibility. Old encodings that use these indexes will throw an error when decoded.
+---
+--- Metatables that are not found in the metatable dictionary are ignored when encoding. Decoding returns a table with a nil metatable.
+---
+--- Note: parsing and preparation of the options table is somewhat expensive. Create a buffer object only once and recycle it for multiple uses. Avoid mixing encoder and decoder buffers, since the buf:set() method frees the already allocated buffer space:
+---
+--- ```lua
+--- local options = {
+---   dict = { "commonly", "used", "string", "keys" },
+--- }
+--- local buf_enc = buffer.new(options)
+--- local buf_dec = buffer.new(options)
+---
+--- local function encode(obj)
+---   return buf_enc:reset():encode(obj):get()
+--- end
+---
+--- local function decode(str)
+---   return buf_dec:set(str):decode()
+--- end
+--- ```
+---@class string.buffer.serialization.opts
+---@field dict string[]
+---@field metatable table[]
+
+
+return buffer