Merge pull request #867 from flrgh/chore/update-lua-resty-websocket-annotations

chore: update lua-resty-websocket library annotations

4 files changed, 246 insertions, 29 deletions

diff --git a/meta/3rd/OpenResty/library/resty.websocket.client.lua b/meta/3rd/OpenResty/library/resty.websocket.client.lua
index f933c941..c722faf9 100644
--- a/meta/3rd/OpenResty/library/resty.websocket.client.lua
+++ b/meta/3rd/OpenResty/library/resty.websocket.client.lua
@@ -1,16 +1,63 @@
 ---@meta
-resty_websocket_client={}
-function resty_websocket_client.send_text(self, data) end
-function resty_websocket_client.new(self, opts) end
-function resty_websocket_client.send_ping(self, data) end
-function resty_websocket_client.connect(self, uri, opts) end
-function resty_websocket_client.set_timeout(self, time) end
-function resty_websocket_client.set_keepalive(self, ...) end
-function resty_websocket_client.send_binary(self, data) end
-function resty_websocket_client.send_close() end
-function resty_websocket_client.send_frame() end
-function resty_websocket_client.recv_frame(self) end
-function resty_websocket_client.close(self) end
-resty_websocket_client._VERSION="0.07"
-function resty_websocket_client.send_pong(self, data) end
+
+---@class resty.websocket.client : resty.websocket
+resty_websocket_client = {
+  _VERSION = "0.09"
+}
+
+---Instantiates a WebSocket client object.
+---
+---In case of error, it returns nil and a string describing the error.
+---
+---An optional options table can be specified.
+---
+---@param  opts?                   resty.websocket.new.opts
+---@return resty.websocket.client? client
+---@return string?                 error
+function resty_websocket_client:new(opts) end
+
+---Connects to the remote WebSocket service port and performs the websocket
+---handshake process on the client side.
+---
+---Before actually resolving the host name and connecting to the remote backend,
+---this method will always look up the connection pool for matched idle
+---connections created by previous calls of this method.
+---
+---@param  url     string
+---@param  opts?   resty.websocket.client.connect.opts
+---@return boolean ok
+---@return string? error
+function resty_websocket_client:connect(uri, opts) end
+
+--- Puts the current WebSocket connection immediately into the ngx_lua cosocket connection pool.
+---
+--- You can specify the max idle timeout (in ms) when the connection is in the pool and the maximal size of the pool every nginx worker process.
+---
+--- In case of success, returns 1. In case of errors, returns nil with a string describing the error.
+---
+--- Only call this method in the place you would have called the close method instead. Calling this method will immediately turn the current WebSocket object into the closed state. Any subsequent operations other than connect() on the current object will return the closed error.
+----
+---@param  max_idle_timeout number
+---@param  pool_size        integer
+---@return boolean          ok
+---@return string?          error
+function resty_websocket_client:set_keepalive(max_idle_timeout, pool_size) end
+
+---Closes the current WebSocket connection.
+---
+---If no close frame is sent yet, then the close frame will be automatically sent.
+---
+---@return boolean ok
+---@return string? error
+function resty_websocket_client:close() end
+
+---@class resty.websocket.client.connect.opts : table
+---
+---@field protocols  string|string[]  subprotocol(s) used for the current WebSocket session
+---@field origin     string           the value of the Origin request header
+---@field pool       string           custom name for the connection pool being used. If omitted, then the connection pool name will be generated from the string template <host>:<port>.
+---@field ssl_verify boolean          whether to perform SSL certificate verification during the SSL handshake if the wss:// scheme is used.
+---@field headers    string[]         custom headers to be sent in the handshake request. The table is expected to contain strings in the format {"a-header: a header value", "another-header: another header value"}.
+
+
 return resty_websocket_client
\ No newline at end of file
diff --git a/meta/3rd/OpenResty/library/resty.websocket.lua b/meta/3rd/OpenResty/library/resty.websocket.lua
new file mode 100644
index 00000000..9ddd4921
--- /dev/null
+++ b/meta/3rd/OpenResty/library/resty.websocket.lua
@@ -0,0 +1,116 @@
+---@meta
+
+--- websocket object
+--- https://github.com/openresty/lua-resty-websocket
+---
+---@class resty.websocket : table
+---@field sock            tcpsock
+---@field fatal           boolean
+---@field max_payload_len number
+---@field send_masked     boolean
+resty_websocket = {}
+
+---@param ms integer sets the timeout delay (in milliseconds) for the network-related operations
+function resty_websocket:set_timeout(ms) end
+
+---Sends the text argument out as an unfragmented data frame of the text type.
+---
+---Returns the number of bytes that have actually been sent on the TCP level.
+---
+---In case of errors, returns nil and a string describing the error.
+---
+---@param  text     string
+---@return integer? bytes
+---@return string?  error
+function resty_websocket:send_text(text) end
+
+---Sends the data argument out as an unfragmented data frame of the binary type.
+---
+---Returns the number of bytes that have actually been sent on the TCP level.
+---
+---In case of errors, returns nil and a string describing the error.
+---
+---@param  data     string
+---@return integer? bytes
+---@return string?  error
+function resty_websocket:send_binary(data) end
+
+---Sends out a ping frame with an optional message specified by the msg argument.
+---Returns the number of bytes that have actually been sent on the TCP level.
+---
+---In case of errors, returns nil and a string describing the error.
+---
+---Note that this method does not wait for a pong frame from the remote end.
+---
+---@param  msg?     string
+---@return integer? bytes
+---@return string?  error
+function resty_websocket:send_ping(msg) end
+
+---Sends out a pong frame with an optional message specified by the msg argument.
+---Returns the number of bytes that have actually been sent on the TCP level.
+---
+---In case of errors, returns nil and a string describing the error.
+---@param  msg?     string
+---@return integer? bytes
+---@return string?  error
+function resty_websocket:send_pong(msg) end
+
+---Sends out a close frame with an optional status code and a message.
+---
+---In case of errors, returns nil and a string describing the error.
+---
+---For a list of valid status code, see the following document:
+---
+---http://tools.ietf.org/html/rfc6455#section-7.4.1
+---
+---Note that this method does not wait for a close frame from the remote end.
+---@param  code?    integer
+---@param  msg?     string
+---@return integer? bytes
+---@return string?  error
+function resty_websocket:send_close(code, msg) end
+
+---Sends out a raw websocket frame by specifying the fin field (boolean value), the opcode, and the payload.
+---
+---For a list of valid opcode, see
+---
+---http://tools.ietf.org/html/rfc6455#section-5.2
+---
+---In case of errors, returns nil and a string describing the error.
+---
+---To control the maximal payload length allowed, you can pass the max_payload_len option to the new constructor.
+---
+---To control whether to send masked frames, you can pass true to the send_masked option in the new constructor method. By default, unmasked frames are sent.
+---@param  fin      boolean
+---@param  opcode   resty.websocket.protocol.opcode
+---@param  payload  string
+---@return integer? bytes
+---@return string?  error
+function resty_websocket:send_frame(fin, opcode, payload) end
+
+---Receives a WebSocket frame from the wire.
+---
+---In case of an error, returns two nil values and a string describing the error.
+---
+---The second return value is always the frame type, which could be one of continuation, text, binary, close, ping, pong, or nil (for unknown types).
+---
+---For close frames, returns 3 values: the extra status message (which could be an empty string), the string "close", and a Lua number for the status code (if any). For possible closing status codes, see
+---
+---http://tools.ietf.org/html/rfc6455#section-7.4.1
+---
+---For other types of frames, just returns the payload and the type.
+---
+---For fragmented frames, the err return value is the Lua string "again".
+---
+---@return string?                        data
+---@return resty.websocket.protocol.type? typ
+---@return string|integer?                error_or_status_code
+function resty_websocket:recv_frame() end
+
+---@class resty.websocket.new.opts : table
+---@field max_payload_len  integer  maximal length of payload allowed when sending and receiving WebSocket frames
+---@field send_masked      boolean  whether to send out masked WebSocket frames
+---@field timeout          integer  network timeout threshold in milliseconds
+
+return resty_websocket
diff --git a/meta/3rd/OpenResty/library/resty.websocket.protocol.lua b/meta/3rd/OpenResty/library/resty.websocket.protocol.lua
index 9ef52bbb..c3455969 100644
--- a/meta/3rd/OpenResty/library/resty.websocket.protocol.lua
+++ b/meta/3rd/OpenResty/library/resty.websocket.protocol.lua
@@ -1,8 +1,59 @@
 ---@meta
-resty_websocket_protocol={}
-function resty_websocket_protocol.build_frame() end
-function resty_websocket_protocol.new_tab() end
+
+---@class resty.websocket.protocol
+resty_websocket_protocol = {
+  _VERSION = "0.09",
+}
+
+--- Websocket op code
+---
+--- Defines the interpretation of the payload data.
+---
+--- See RFC 6455 section 5.2
+---
+---@alias resty.websocket.protocol.opcode
+---| '0x0' # continuation
+---| '0x1' # text
+---| '0x2' # binary
+---| '0x8' # close
+---| '0x9' # ping
+---| '0xa' # pong
+
+---@alias resty.websocket.protocol.type
+---| '"continuation"'
+---| '"text"'
+---| '"binary"'
+---| '"close"'
+---| '"ping"'
+---| '"pong"'
+
+--- Builds a raw WebSocket frame.
+---@param  fin         boolean
+---@param  opcode      resty.websocket.protocol.opcode
+---@param  payload_len integer
+---@param  payload     string
+---@param  masking     boolean
+---@return string
+function resty_websocket_protocol.build_frame(fin, opcode, payload_len, payload, masking) end
+
+--- Sends a raw WebSocket frame.
+---@param  sock            tcpsock
+---@param  fin             boolean
+---@param  opcode          resty.websocket.protocol.opcode
+---@param  payload         string
+---@param  max_payload_len interger
+---@param  masking         boolean
+---@return bytes?          number
+---@return string?         error
 function resty_websocket_protocol.send_frame(sock, fin, opcode, payload, max_payload_len, masking) end
-resty_websocket_protocol._VERSION="0.07"
+
+--- Receives a WebSocket frame from the wire.
+---@param  sock                           tcpsock
+---@param  max_payload_len                interger
+---@param  force_masking                  boolean
+---@return string?                        data
+---@return resty.websocket.protocol.type? typ
+---@return string?                        error
 function resty_websocket_protocol.recv_frame(sock, max_payload_len, force_masking) end
+
 return resty_websocket_protocol
\ No newline at end of file
diff --git a/meta/3rd/OpenResty/library/resty.websocket.server.lua b/meta/3rd/OpenResty/library/resty.websocket.server.lua
index c9041a96..f590fcc8 100644
--- a/meta/3rd/OpenResty/library/resty.websocket.server.lua
+++ b/meta/3rd/OpenResty/library/resty.websocket.server.lua
@@ -1,13 +1,16 @@
 ---@meta
-resty_websocket_server={}
-function resty_websocket_server.send_text(self, data) end
-function resty_websocket_server.new(self, opts) end
-function resty_websocket_server.send_ping(self, data) end
-function resty_websocket_server.set_timeout(self, time) end
-function resty_websocket_server.send_binary(self, data) end
-function resty_websocket_server.send_frame() end
-function resty_websocket_server.recv_frame(self) end
-function resty_websocket_server.send_close(self, code, msg) end
-resty_websocket_server._VERSION="0.07"
-function resty_websocket_server.send_pong(self, data) end
+
+---@class resty.websocket.server : resty.websocket
+resty_websocket_server = {
+  _VERSION = "0.09"
+}
+
+---Performs the websocket handshake process on the server side and returns a WebSocket server object.
+---
+---In case of error, it returns nil and a string describing the error.
+---@param  opts?                   resty.websocket.new.opts
+---@return resty.websocket.server? server
+---@return string?                 error
+function resty_websocket_server:new(opts) end
+
 return resty_websocket_server
\ No newline at end of file