From ddaf74b1fab93b16ff4f875e4bf648c503e022a8 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 15:21:42 +1300
Subject: [PATCH 01/35] Fix params and return of socket.bind

---
 library/socket.lua | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/library/socket.lua b/library/socket.lua
index 8f8ce92..03b4376 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -48,7 +48,8 @@ socket.headers.canonic = {}
 ---
 ---@param address string
 ---@param port integer
----@param backlog? any
+---@param backlog? integer
+---@return TCPSocket
 ---
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
 function socket.bind(address, port, backlog) end

From ff4509c230bd74eefa480e7d281ad88815ca40ff Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 15:26:20 +1300
Subject: [PATCH 02/35] Fix documentation of socket.connect4 and connect6

These functions don't have a family argument
---
 library/socket.lua | 30 ++++++++----------------------
 1 file changed, 8 insertions(+), 22 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index 03b4376..64f4b63 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -76,46 +76,32 @@ function socket.bind(address, port, backlog) end
 function socket.connect(address, port, locaddr, locport, family) end
 
 ---
----This function is a shortcut that creates and returns a TCP client object
----connected to a remote `address` at a given `port`. Optionally,
+---This function is a shortcut that creates and returns an IPv4 TCP client
+---object connected to a remote `address` at a given `port`. Optionally,
 ---the user can also specify the local address and port to bind
----(`locaddr` and `locport`), or restrict the socket family
----to "`inet`" or "`inet6`".
----
----Without specifying `family` to `connect`, whether a tcp or tcp6
----connection is created depends on your system configuration. Two variations
----of connect are defined as simple helper functions that restrict the
----`family`, `socket.connect4` and `socket.connect6`.
+---(`locaddr` and `locport`)
 ---
 ---@param address string
 ---@param port integer
 ---@param locaddr? string
 ---@param locport? integer
----@param family? 'inet'|'inet6'
 ---
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
-function socket.connect4(address, port, locaddr, locport, family) end
+function socket.connect4(address, port, locaddr, locport) end
 
 ---
----This function is a shortcut that creates and returns a TCP client object
----connected to a remote `address` at a given `port`. Optionally,
+---This function is a shortcut that creates and returns an IPv6 TCP client
+---object connected to a remote `address` at a given `port`. Optionally,
 ---the user can also specify the local address and port to bind
----(`locaddr` and `locport`), or restrict the socket family
----to "`inet`" or "`inet6`".
----
----Without specifying `family` to `connect`, whether a tcp or tcp6
----connection is created depends on your system configuration. Two variations
----of connect are defined as simple helper functions that restrict the
----`family`, `socket.connect4` and `socket.connect6`.
+---(`locaddr` and `locport`)
 ---
 ---@param address string
 ---@param port integer
 ---@param locaddr? string
 ---@param locport? integer
----@param family? 'inet'|'inet6'
 ---
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
-function socket.connect6(address, port, locaddr, locport, family) end
+function socket.connect6(address, port, locaddr, locport) end
 
 ---
 ---This constant is set to `true` if the library was compiled

From 85689d84fa99201c21d1037fbccfc99b126ba1a9 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 15:50:48 +1300
Subject: [PATCH 03/35] Add fold markers for the TCP stuff

This is purely for the annotations dev experience
---
 library/socket.lua | 7 +++++++
 1 file changed, 7 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 64f4b63..6c350f6 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -371,6 +371,9 @@ function socket.try(...) end
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
 socket._VERSION = ""
 
+--{{{ TCP
+--#region TCP
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
@@ -448,4 +451,8 @@ function tcp_socket:send(data, i, j) end
 ---Garbage-collected objects are automatically closed before destruction, though.
 function tcp_socket:close() end
 
+
+--#endregion
+--}}}
+
 return socket

From 0a513ed93bc58a1e705ac4b237a317a9c4df1ca6 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:01:07 +1300
Subject: [PATCH 04/35] Add the three tcp socket types

luasocket splits them into master, client, and server
---
 library/socket.lua | 17 ++++++++++++++---
 1 file changed, 14 insertions(+), 3 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index 6c350f6..ed72d42 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -374,20 +374,31 @@ socket._VERSION = ""
 --{{{ TCP
 --#region TCP
 
+---
+---@class TCPSocketMaster
+local tcp_master = {}
+
+---
+---@class TCPSocketServer : TCPSocketMaster
+local tcp_server = {}
+
+---
+---@class TCPSocketClient : TCPSocketMaster
+local tcp_client = {}
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
 ---Note: The choice between IPv4 and IPv6 happens during a call to bind or connect, depending on the address family obtained from the resolver.
 ---Note: Before the choice between IPv4 and IPv6 happens, the internal socket object is invalid and therefore setoption will fail.
 ---
----@return TCPSocket
+---@return TCPSocketMaster
 function socket.tcp() end
 
 ---
 ---Creates and returns an IPv4 TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
 ---
----@return TCPSocket
+---@return TCPSocketMaster
 function socket.tcp4() end
 
 ---
@@ -395,7 +406,7 @@ function socket.tcp4() end
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
 ---Note: The TCP object returned will have the option "ipv6-v6only" set to true.
 ---
----@return TCPSocket
+---@return TCPSocketMaster
 function socket.tcp6() end
 
 ---

From 8f022c2f3592842916797cd6063f7d5afa2dc573 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:01:44 +1300
Subject: [PATCH 05/35] Add server:accept() docs

---
 library/socket.lua | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index ed72d42..8614bf9 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -385,6 +385,17 @@ local tcp_server = {}
 ---
 ---@class TCPSocketClient : TCPSocketMaster
 local tcp_client = {}
+
+---
+---Waits for a remote connection on the server object and returns a client object representing that connection.
+---
+---If a connection is successfully initiated, a client object is returned. If a timeout condition is met, the method returns `nil` followed by the error string 'timeout'. Other errors are reported by `nil` followed by a message describing the error.
+---
+---Note: calling `socket.select` with a server object in the recvt parameter before a call to accept does not guarantee accept will return immediately. Use the `settimeout` method or accept might block until another client shows up.
+---
+---@return TCPSocketClient | nil, "timeout" | string
+function tcp_server:accept() end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From b8e348d65e33bb2445f5e214a7ade779f9370f28 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:06:43 +1300
Subject: [PATCH 06/35] Add docs for master:bind(address, port)

---
 library/socket.lua | 14 ++++++++++++++
 1 file changed, 14 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 8614bf9..c095709 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -396,6 +396,20 @@ local tcp_client = {}
 ---@return TCPSocketClient | nil, "timeout" | string
 function tcp_server:accept() end
 
+---
+---Binds a master object to address and port on the local host.
+---
+---Address can be an IP address or a host name. Port must be an integer number in the range [0..64K). If address is `'*'`, the system binds to all local interfaces using the `INADDR_ANY` constant or `IN6ADDR_ANY_INIT`, according to the family. If `port` is `0`, the system automatically chooses an ephemeral port.
+---
+---In case of success, the method returns `1`. In case of error, the method returns `nil` followed by an error message.
+---
+---Note: The function `socket.bind` is available and is a shortcut for the creation of server sockets.
+---
+---@param address string
+---@param port integer
+---@return 1|nil, nil|string
+function tcp_master:bind(address, port) end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From ba8d40398241732641e04101e071fa2966a6e817 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:08:08 +1300
Subject: [PATCH 07/35] Add master:close() docs

---
 library/socket.lua | 23 ++++++++++-------------
 1 file changed, 10 insertions(+), 13 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index c095709..5045cf8 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -410,6 +410,16 @@ function tcp_server:accept() end
 ---@return 1|nil, nil|string
 function tcp_master:bind(address, port) end
 
+---
+---Closes a TCP object.
+---The internal socket used by the object is closed and the local address to which the object was bound is made available to other applications.
+---No further operations (except for further calls to the close method) are allowed on a closed socket.
+---
+---Note: It is important to close all used sockets once they are not needed, since, in many systems,
+---each socket uses a file descriptor, which are limited system resources.
+---Garbage-collected objects are automatically closed before destruction, though.
+function tcp_master:close() end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
@@ -434,10 +444,6 @@ function socket.tcp4() end
 ---@return TCPSocketMaster
 function socket.tcp6() end
 
----
----@class TCPSocket
-local tcp_socket = {}
-
 ---
 ---Attempts to connect a master object to a remote host, transforming it into a client object.
 ---Client objects support methods send, receive, getsockname, getpeername, settimeout, and close.
@@ -477,15 +483,6 @@ function tcp_socket:receive(pattern, prefix) end
 ---@return nil | number, nil | string # If successful, the method returns the index of the last byte within [i, j] that has been sent. Notice that, if i is 1 or absent, this is effectively the total number of bytes sent. In case of error, the method returns nil, followed by an error message, followed by the index of the last byte within [i, j] that has been sent. You might want to try again from the byte following that. The error message can be 'closed' in case the connection was closed before the transmission was completed or the string 'timeout' in case there was a timeout during the operation.
 function tcp_socket:send(data, i, j) end
 
----
----Closes a TCP object.
----The internal socket used by the object is closed and the local address to which the object was bound is made available to other applications.
----No further operations (except for further calls to the close method) are allowed on a closed socket.
----
----Note: It is important to close all used sockets once they are not needed, since, in many systems,
----each socket uses a file descriptor, which are limited system resources.
----Garbage-collected objects are automatically closed before destruction, though.
-function tcp_socket:close() end
 
 
 --#endregion

From 4eb4433275715159c429c80571aa1d1ebaea201d Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:20:43 +1300
Subject: [PATCH 08/35] Note which type master:bind() transforms into

---
 library/socket.lua | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 5045cf8..de6d008 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -403,6 +403,8 @@ function tcp_server:accept() end
 ---
 ---In case of success, the method returns `1`. In case of error, the method returns `nil` followed by an error message.
 ---
+---On success, the type changes to `TCPSocketServer`, and you should cast it as such.
+---
 ---Note: The function `socket.bind` is available and is a shortcut for the creation of server sockets.
 ---
 ---@param address string

From 5e44b04cfde7af97665da2674f3e5e5357c1cc33 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:21:07 +1300
Subject: [PATCH 09/35] Add master:connect() docs

---
 library/socket.lua | 28 +++++++++++++++-------------
 1 file changed, 15 insertions(+), 13 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index de6d008..2f55874 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -422,6 +422,21 @@ function tcp_master:bind(address, port) end
 ---Garbage-collected objects are automatically closed before destruction, though.
 function tcp_master:close() end
 
+---
+---Attempts to connect a master object to a remote host, transforming it into a client object.
+---Client objects support methods `send`, `receive`, `getsockname`, `getpeername`, `settimeout`, and `close`.
+---
+---On success, the type changes to `TCPClient`, and you should cast it as such.
+---
+---Note: The function `socket.connect` is available and is a shortcut for the creation of client sockets.
+---Note: Starting with LuaSocket 2.0, the `settimeout` method affects the behavior of connect, causing it to return with an error in case of a timeout. If that happens, you can still call socket.select with the socket in the sendt table. The socket will be writable when the connection is established.
+---Note: Starting with LuaSocket 3.0, the host name resolution depends on whether the socket was created by socket.tcp, socket.tcp4 or socket.tcp6. Addresses from the appropriate family (or both) are tried in the order returned by the resolver until the first success or until the last failure. If the timeout was set to zero, only the first address is tried.
+---
+---@param address string # IP address or a host name
+---@param port integer # TCP port, in the range [1..64K)
+---@return nil | 1, nil | string # In case of error, the method returns nil followed by a string describing the error. In case of success, the method returns 1.
+function tcp_master:connect(address, port) end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
@@ -446,19 +461,6 @@ function socket.tcp4() end
 ---@return TCPSocketMaster
 function socket.tcp6() end
 
----
----Attempts to connect a master object to a remote host, transforming it into a client object.
----Client objects support methods send, receive, getsockname, getpeername, settimeout, and close.
----
----Note: The function socket.connect is available and is a shortcut for the creation of client sockets.
----Note: Starting with LuaSocket 2.0, the settimeout method affects the behavior of connect, causing it to return with an error in case of a timeout. If that happens, you can still call socket.select with the socket in the sendt table. The socket will be writable when the connection is established.
----Note: Starting with LuaSocket 3.0, the host name resolution depends on whether the socket was created by socket.tcp, socket.tcp4 or socket.tcp6. Addresses from the appropriate family (or both) are tried in the order returned by the resolver until the first success or until the last failure. If the timeout was set to zero, only the first address is tried.
----
----@param address string # IP address or a host name
----@param port integer # TCP port, in the range [1..64K)
----@return nil | 1, nil | string # In case of error, the method returns nil followed by a string describing the error. In case of success, the method returns 1.
-function tcp_socket:connect(address, port) end
-
 ---
 ---@alias PatternMode
 ---| '*a' # Reads from the socket until the connection is closed. No end-of-line translation is performed

From 64d6aa3477a57f80c3a344498c9c2de1f9b70e7b Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:27:09 +1300
Subject: [PATCH 10/35] Add master:getfd() docs

---
 library/socket.lua | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 2f55874..1b1a7da 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -437,6 +437,14 @@ function tcp_master:close() end
 ---@return nil | 1, nil | string # In case of error, the method returns nil followed by a string describing the error. In case of success, the method returns 1.
 function tcp_master:connect(address, port) end
 
+
+---
+---Get the underling socket descriptor or handle associated to the object.
+---
+---**Note: This is an internal method. Unlikely to be portable. use at your own risk.**
+---@return integer # The descriptor or handle. `-1` if the object has been closed. `_SOCKETINVALID` if it is an invalid socket.
+function tcp_master:getfd() end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From 068cacfc07d4e3a2752ee516245e96f23e2b029b Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:27:21 +1300
Subject: [PATCH 11/35] Add master:dirty() docs

---
 library/socket.lua | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 1b1a7da..cb2ed77 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -437,6 +437,12 @@ function tcp_master:close() end
 ---@return nil | 1, nil | string # In case of error, the method returns nil followed by a string describing the error. In case of success, the method returns 1.
 function tcp_master:connect(address, port) end
 
+---
+---Check the read buffer status.
+---
+---**Note: This is an internal method, use at your own risk.**
+---@return boolean # `true` if there is any data in the read buffer, `false` otherwise.
+function tcp_master:dirty() end
 
 ---
 ---Get the underling socket descriptor or handle associated to the object.

From 3dbba80bec3676fcccf07fbd88f93de58ec8bb55 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:38:54 +1300
Subject: [PATCH 12/35] Add {client,server}:getoption() docs

---
 library/socket.lua | 12 ++++++++++++
 1 file changed, 12 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index cb2ed77..86faf1b 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -451,6 +451,18 @@ function tcp_master:dirty() end
 ---@return integer # The descriptor or handle. `-1` if the object has been closed. `_SOCKETINVALID` if it is an invalid socket.
 function tcp_master:getfd() end
 
+---@alias TCPOption "keepalive" | "linger" | "reuseaddr" | "tcp-nodelay"
+
+---Gets options for the TCP object. See `setoption` for description of the option names and values.
+---@param option TCPOption
+---@return any | nil, nil | string # The option value in case of success, or nil followed by an error message otherwise.
+function tcp_client:getoption(option) end
+
+---Gets options for the TCP object. See `setoption` for description of the option names and values.
+---@param option TCPOption
+---@return any | nil, nil | string # The option value in case of success, or nil followed by an error message otherwise.
+function tcp_server:getoption(option) end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From e1b1370ac8510a1b61b84e64e16422204f7d1b14 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:45:30 +1300
Subject: [PATCH 13/35] Add client:getpeername() docs

---
 library/socket.lua | 9 +++++++++
 1 file changed, 9 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 86faf1b..7ff40fc 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -463,6 +463,15 @@ function tcp_client:getoption(option) end
 ---@return any | nil, nil | string # The option value in case of success, or nil followed by an error message otherwise.
 function tcp_server:getoption(option) end
 
+---
+---Returns information about the remote side of a connected client object.
+---
+---Note: It makes no sense to call this method on server objects. 
+---
+---@return string | nil, integer | nil, "inet" | "inet6" | "unspec" | "unknown" | nil # The IP address of the peer, the port number that the peer is using for the connection, and the family. In case of error, returns `nil`.
+---
+function tcp_client:getpeername() end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From 9cceae202f9e58f2180873158c8410ee0c2669a8 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:46:24 +1300
Subject: [PATCH 14/35] Formatting

---
 library/socket.lua | 2 ++
 1 file changed, 2 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 7ff40fc..2f23008 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -453,11 +453,13 @@ function tcp_master:getfd() end
 
 ---@alias TCPOption "keepalive" | "linger" | "reuseaddr" | "tcp-nodelay"
 
+---
 ---Gets options for the TCP object. See `setoption` for description of the option names and values.
 ---@param option TCPOption
 ---@return any | nil, nil | string # The option value in case of success, or nil followed by an error message otherwise.
 function tcp_client:getoption(option) end
 
+---
 ---Gets options for the TCP object. See `setoption` for description of the option names and values.
 ---@param option TCPOption
 ---@return any | nil, nil | string # The option value in case of success, or nil followed by an error message otherwise.

From 4e0dd4cd0fb28f9791564879b43b8014d326d50d Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 16:47:56 +1300
Subject: [PATCH 15/35] Add master:getsockname() docs

---
 library/socket.lua | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 2f23008..ca4f1a2 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -474,6 +474,12 @@ function tcp_server:getoption(option) end
 ---
 function tcp_client:getpeername() end
 
+---
+---Returns the local address information associated to the object.
+---
+---@return string | nil, integer | nil, "inet" | "inet6" | "unspec" | "unknown" | nil # The IP address of the peer, the port number that the peer is using for the connection, and the family. In case of error, returns `nil`.
+function tcp_master:getsockname() end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From bfbcbe393a25e66db2ed530275ed2bc77fe2dcfc Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 17:02:01 +1300
Subject: [PATCH 16/35] Add some more docs

---
 library/socket.lua | 17 +++++++++++++++++
 1 file changed, 17 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index ca4f1a2..704cc50 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -480,6 +480,23 @@ function tcp_client:getpeername() end
 ---@return string | nil, integer | nil, "inet" | "inet6" | "unspec" | "unknown" | nil # The IP address of the peer, the port number that the peer is using for the connection, and the family. In case of error, returns `nil`.
 function tcp_master:getsockname() end
 
+---
+---Returns the current block timeout followed by the current total timeout.
+---
+---@return number, number # Current block timeout, current total timeout.
+function tcp_master:gettimeout() end
+
+---
+---Specifies the socket is willing to receive connections, transforming the object into a server object. Server objects support the `accept`, `getsockname`, `setoption`, `settimeout`, and `close` methods.
+---
+---On success, the type changes to `TCPSocketServer`, and you should cast it as such.
+---
+---@param backlog integer The number number of client connections that can be queued waiting for service. If the queue is full and another client attempts connection, the connection is refused.
+---
+---@return 1 | nil, nil | string # Returns 1 on success, nil and an error on failure.
+---
+function tcp_master:listen(backlog) end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From f366b712c4aa836fee0fa6747945d9b34e86002e Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 17:02:39 +1300
Subject: [PATCH 17/35] Formatting

---
 library/socket.lua | 4 +---
 1 file changed, 1 insertion(+), 3 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index 704cc50..d6facbb 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -468,7 +468,7 @@ function tcp_server:getoption(option) end
 ---
 ---Returns information about the remote side of a connected client object.
 ---
----Note: It makes no sense to call this method on server objects. 
+---Note: It makes no sense to call this method on server objects.
 ---
 ---@return string | nil, integer | nil, "inet" | "inet6" | "unspec" | "unknown" | nil # The IP address of the peer, the port number that the peer is using for the connection, and the family. In case of error, returns `nil`.
 ---
@@ -547,8 +547,6 @@ function tcp_socket:receive(pattern, prefix) end
 ---@return nil | number, nil | string # If successful, the method returns the index of the last byte within [i, j] that has been sent. Notice that, if i is 1 or absent, this is effectively the total number of bytes sent. In case of error, the method returns nil, followed by an error message, followed by the index of the last byte within [i, j] that has been sent. You might want to try again from the byte following that. The error message can be 'closed' in case the connection was closed before the transmission was completed or the string 'timeout' in case there was a timeout during the operation.
 function tcp_socket:send(data, i, j) end
 
-
-
 --#endregion
 --}}}
 

From 13a668255779db0f0ccbc7a939c3e6dd040ef6ac Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 17:11:28 +1300
Subject: [PATCH 18/35] Use alias for socket families

---
 library/socket.lua | 10 ++++++++--
 1 file changed, 8 insertions(+), 2 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index d6facbb..bc41c12 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -465,19 +465,25 @@ function tcp_client:getoption(option) end
 ---@return any | nil, nil | string # The option value in case of success, or nil followed by an error message otherwise.
 function tcp_server:getoption(option) end
 
+---@alias SocketFamily
+---| "inet" IPv4
+---| "inet6" IPv6
+---| "unspec" Unspecified
+---| "unknown" Unknown
+
 ---
 ---Returns information about the remote side of a connected client object.
 ---
 ---Note: It makes no sense to call this method on server objects.
 ---
----@return string | nil, integer | nil, "inet" | "inet6" | "unspec" | "unknown" | nil # The IP address of the peer, the port number that the peer is using for the connection, and the family. In case of error, returns `nil`.
+---@return string | nil, integer | nil, SocketFamily | nil # The IP address of the peer, the port number that the peer is using for the connection, and the family. In case of error, returns `nil`.
 ---
 function tcp_client:getpeername() end
 
 ---
 ---Returns the local address information associated to the object.
 ---
----@return string | nil, integer | nil, "inet" | "inet6" | "unspec" | "unknown" | nil # The IP address of the peer, the port number that the peer is using for the connection, and the family. In case of error, returns `nil`.
+---@return string | nil, integer | nil, SocketFamily | nil # The IP address of the peer, the port number that the peer is using for the connection, and the family. In case of error, returns `nil`.
 function tcp_master:getsockname() end
 
 ---

From 513435d01879cb8d2747b477846ab4f393097979 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 17:26:26 +1300
Subject: [PATCH 19/35] Add client:receive() docs

---
 library/socket.lua | 25 ++++++++++++++++++++-----
 1 file changed, 20 insertions(+), 5 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index bc41c12..16b9d30 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -503,6 +503,26 @@ function tcp_master:gettimeout() end
 ---
 function tcp_master:listen(backlog) end
 
+-- HACK: For some reason number doesn't show up in the completion if it's
+--       defined as part of this union. It should be defined in-place.
+
+---
+---@alias ReceivePatternMode
+---| '*a' # Reads from the socket until the connection is closed. No end-of-line translation is performed
+---| '*l' # Reads a line of text from the socket. The line is terminated by a LF character (ASCII 10), optionally preceded by a CR character (ASCII 13). The CR and LF characters are not included in the returned line. In fact, all CR characters are ignored by the pattern.
+
+---
+---Reads data from a client object, according to the specified read pattern. Patterns follow the Lua file I/O format, and the difference in performance between all patterns is negligible.
+---
+---**Important note:** This function was changed severely. It used to support multiple patterns (but I have never seen this feature used) and now it doesn't anymore. Partial results used to be returned in the same way as successful results. This last feature violated the idea that all functions should return nil on error. Thus it was changed too.
+---
+---@param pattern ReceivePatternMode | number | nil The default is "*l"
+---@param prefix string | nil Optional string to be concatenated to the beginning of any received data before return.
+---
+---@return string | nil, "timeout" | "closed" | string | nil # Returns the received pattern when successful, otherwise nil and an error message. It may be "closed" in case the connection was closed before the transmission was completed, or "timeout" in case there was a timeout during the operation.
+function tcp_client:receive(pattern, prefix) end
+
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
@@ -527,11 +547,6 @@ function socket.tcp4() end
 ---@return TCPSocketMaster
 function socket.tcp6() end
 
----
----@alias PatternMode
----| '*a' # Reads from the socket until the connection is closed. No end-of-line translation is performed
----| '*l' # Reads a line of text from the socket. The line is terminated by a LF character (ASCII 10), optionally preceded by a CR character (ASCII 13). The CR and LF characters are not included in the returned line. In fact, all CR characters are ignored by the pattern. This is the default pattern;
----| number # Causes the method to read a specified number of bytes from the socket.
 
 ---Reads data from a client object, according to the specified read pattern.
 ---Patterns follow the Lua file I/O format,

From 597458f2c46563dbb9d8eafa0d76acb40990d94d Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 17:59:22 +1300
Subject: [PATCH 20/35] Add client:send() docs

---
 library/socket.lua | 19 ++++++++++++++++++-
 1 file changed, 18 insertions(+), 1 deletion(-)

diff --git a/library/socket.lua b/library/socket.lua
index 16b9d30..79aba9b 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -503,6 +503,11 @@ function tcp_master:gettimeout() end
 ---
 function tcp_master:listen(backlog) end
 
+---@alias SocketError
+---| "timeout" If there was a timeout during the operation.
+---| "closed" If the connection was closed before the transmission was completed.
+
+
 -- HACK: For some reason number doesn't show up in the completion if it's
 --       defined as part of this union. It should be defined in-place.
 
@@ -519,9 +524,21 @@ function tcp_master:listen(backlog) end
 ---@param pattern ReceivePatternMode | number | nil The default is "*l"
 ---@param prefix string | nil Optional string to be concatenated to the beginning of any received data before return.
 ---
----@return string | nil, "timeout" | "closed" | string | nil # Returns the received pattern when successful, otherwise nil and an error message. It may be "closed" in case the connection was closed before the transmission was completed, or "timeout" in case there was a timeout during the operation.
+---@return string | nil, SocketError | string | nil # Returns the received pattern when successful, otherwise nil and an error message.
 function tcp_client:receive(pattern, prefix) end
 
+---
+---Sends data through client object.
+---
+---The optional arguments `i` and `j` work exactly like the standard `string.sub` Lua function to allow the selection of a substring to be sent.
+---
+---**Note:** Output is not buffered. For small strings, it is always better to concatenate them in Lua (with the '..' operator) and send the result in one call instead of calling the method several times.
+---
+---@param data string The string to be sent.
+---@param i integer | nil
+---@param j integer | nil
+---@return integer | nil, SocketError | string | nil, integer | nil # On success the number of bytes sent, otherwise nil followed by an error message, followed by the index of the last byte within `[i, j]` that has been sent. You might want to try again from the byte following that.
+function tcp_client:send(data, i, j) end
 
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.

From 25bcef71e70d52e81f3be3a93e5c2cd841dea4eb Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:05:30 +1300
Subject: [PATCH 21/35] Update TCPOptions with info from docs

---
 library/socket.lua | 14 +++++++++++++-
 1 file changed, 13 insertions(+), 1 deletion(-)

diff --git a/library/socket.lua b/library/socket.lua
index 79aba9b..ffe9dbb 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -451,7 +451,19 @@ function tcp_master:dirty() end
 ---@return integer # The descriptor or handle. `-1` if the object has been closed. `_SOCKETINVALID` if it is an invalid socket.
 function tcp_master:getfd() end
 
----@alias TCPOption "keepalive" | "linger" | "reuseaddr" | "tcp-nodelay"
+---@alias TCPOption
+---| "keepalive" Setting this option to `true` enables the periodic transmission of messages on a connected socket. Should the connected party fail to respond to these messages, the connection is considered broken and processes using the socket are notified;
+---| "linger" Controls the action taken when unsent data are queued on a socket and a close is performed. The value is a table with a boolean entry `on` and a numeric entry for the time interval `timeout` in seconds. If the `on` field is set to `true`, the system will block the process on the close attempt until it is able to transmit the data or until `timeout` has passed. If `on` is `false` and a `close` is issued, the system will process the `close` in a manner that allows the process to continue as quickly as possible. I do not advise you to set this to anything other than zero;
+---| "reuseaddr" Setting this option indicates that the rules used in validating addresses supplied in a call to bind should allow reuse of local addresses;
+---| "tcp-nodelay" Setting this option to `true` disables the Nagle's algorithm for the connection;
+---| "tcp-keepidle" value in seconds for `TCP_KEEPIDLE` **Linux only!!**
+---| "tcp-keepcnt" value for `TCP_KEEPCNT` **Linux only!!**
+---| "tcp-keepintvl" value for `TCP_KEEPINTVL` **Linux only!!**
+---| "tcp-defer-accept" value for `TCP_DEFER_ACCEPT` **Linux only!!**
+---| "tcp-fastopen" value for `TCP_FASTOPEN` **Linux only!!**
+---| "tcp-fastopen-connect" value for `TCP_FASTOPEN_CONNECT` **Linux only!!**
+---| "ipv6-v6only" Setting this option to `true` restricts an inet6 socket to sending and receiving only IPv6 packets.
+--- The descriptions above come from the man pages.
 
 ---
 ---Gets options for the TCP object. See `setoption` for description of the option names and values.

From aa7d8555f80071b1265595087f31475cab702db2 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:05:40 +1300
Subject: [PATCH 22/35] Remove old function

---
 library/socket.lua | 21 ---------------------
 1 file changed, 21 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index ffe9dbb..4949673 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -576,27 +576,6 @@ function socket.tcp4() end
 ---@return TCPSocketMaster
 function socket.tcp6() end
 
-
----Reads data from a client object, according to the specified read pattern.
----Patterns follow the Lua file I/O format,
----and the difference in performance between all patterns is negligible.
----
----@param pattern? PatternMode # read everything, one line or a specific number of bytes. Default to reading one line.
----@param prefix? string # prefix is an optional string to be concatenated to the beginning of any received data before return.
----@return nil | string, nil | string, nil | string # if successful, the method returns the received pattern. In case of error, the method returns nil followed by an error message, followed by a (possibly empty) string containing the partial that was received. The error message can be the string 'closed' in case the connection was closed before the transmission was completed or the string 'timeout' in case there was a timeout during the operation.
-function tcp_socket:receive(pattern, prefix) end
-
----
----Sends data through client object.
----
----Note: Output is not buffered. For small strings, it is always better to concatenate them in Lua (with the '..' operator) and send the result in one call instead of calling the method several times.
----
----@param data string # data to be send on the client socket
----@param i? integer # behave like the standard string:sub(i) function
----@param j? integer # behave like the standard string:sub(i, j) function
----@return nil | number, nil | string # If successful, the method returns the index of the last byte within [i, j] that has been sent. Notice that, if i is 1 or absent, this is effectively the total number of bytes sent. In case of error, the method returns nil, followed by an error message, followed by the index of the last byte within [i, j] that has been sent. You might want to try again from the byte following that. The error message can be 'closed' in case the connection was closed before the transmission was completed or the string 'timeout' in case there was a timeout during the operation.
-function tcp_socket:send(data, i, j) end
-
 --#endregion
 --}}}
 

From ae3ab1027be91221f1c1c8e1207a46cb716e07f5 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:08:58 +1300
Subject: [PATCH 23/35] Use ? instead of | nil

---
 library/socket.lua | 8 ++++----
 1 file changed, 4 insertions(+), 4 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index 4949673..f1a5037 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -533,8 +533,8 @@ function tcp_master:listen(backlog) end
 ---
 ---**Important note:** This function was changed severely. It used to support multiple patterns (but I have never seen this feature used) and now it doesn't anymore. Partial results used to be returned in the same way as successful results. This last feature violated the idea that all functions should return nil on error. Thus it was changed too.
 ---
----@param pattern ReceivePatternMode | number | nil The default is "*l"
----@param prefix string | nil Optional string to be concatenated to the beginning of any received data before return.
+---@param pattern? ReceivePatternMode | number The default is "*l"
+---@param prefix? string Optional string to be concatenated to the beginning of any received data before return.
 ---
 ---@return string | nil, SocketError | string | nil # Returns the received pattern when successful, otherwise nil and an error message.
 function tcp_client:receive(pattern, prefix) end
@@ -547,8 +547,8 @@ function tcp_client:receive(pattern, prefix) end
 ---**Note:** Output is not buffered. For small strings, it is always better to concatenate them in Lua (with the '..' operator) and send the result in one call instead of calling the method several times.
 ---
 ---@param data string The string to be sent.
----@param i integer | nil
----@param j integer | nil
+---@param i? integer
+---@param j? integer
 ---@return integer | nil, SocketError | string | nil, integer | nil # On success the number of bytes sent, otherwise nil followed by an error message, followed by the index of the last byte within `[i, j]` that has been sent. You might want to try again from the byte following that.
 function tcp_client:send(data, i, j) end
 

From 2ea27a6a51961d1ea33056235fd2fd9baa7e19a1 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:10:20 +1300
Subject: [PATCH 24/35] Add {server,client}:setoption() docs

---
 library/socket.lua | 16 ++++++++++++++++
 1 file changed, 16 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index f1a5037..3a25ba3 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -552,6 +552,22 @@ function tcp_client:receive(pattern, prefix) end
 ---@return integer | nil, SocketError | string | nil, integer | nil # On success the number of bytes sent, otherwise nil followed by an error message, followed by the index of the last byte within `[i, j]` that has been sent. You might want to try again from the byte following that.
 function tcp_client:send(data, i, j) end
 
+---
+---Sets options for the TCP object. Options are only needed by low-level or time-critical applications. You should only modify an option if you are sure you need it.
+---
+---@param option TCPOption A string with the option name
+---@param value? any Depends on the option being set
+---@return 1 | nil, string | nil # 1 on success, nil and an error message otherwise.
+function tcp_client:setoption(option, value) end
+
+---
+---Sets options for the TCP object. Options are only needed by low-level or time-critical applications. You should only modify an option if you are sure you need it.
+---
+---@param option TCPOption A string with the option name
+---@param value? any Depends on the option being set
+---@return 1 | nil, string | nil # 1 on success, nil and an error message otherwise.
+function tcp_server:setoption(option, value) end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From ef85ec7185eab59c8962144d6d04be282473bcdd Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:17:57 +1300
Subject: [PATCH 25/35] Add master:settimeout() docs

---
 library/socket.lua | 24 ++++++++++++++++++++++++
 1 file changed, 24 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 3a25ba3..fd0a426 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -568,6 +568,30 @@ function tcp_client:setoption(option, value) end
 ---@return 1 | nil, string | nil # 1 on success, nil and an error message otherwise.
 function tcp_server:setoption(option, value) end
 
+---
+---Resets accounting information on the socket, useful for throttling of bandwidth.
+---
+---@param received number Bytes received
+---@param sent number Byte sent
+---@param age number Age in seconds
+---@return 1 | nil # 1 on success, nil otherwise.
+function tcp_master:setstats(received, sent, age) end
+
+---@alias TCPTimeoutMode
+---| "b" block timeout. Specifies the upper limit on the amount of time LuaSocket can be blocked by the operating system while waiting for completion of any single I/O operation.
+---| "t" total timeout. Specifies the upper limit on the amount of time LuaSocket can block a Lua script before returning from a call.
+
+---
+---Changes the timeout values for the object. By default, all I/O operations are blocking. That is, any call to the methods `send`, `receive`, and `accept` will block indefinitely, until the operation completes. The `settimeout` method defines a limit on the amount of time the I/O methods can block. When a timeout is set and the specified amount of time has elapsed, the affected methods give up and fail with an error code.
+---
+---**Note:** although timeout values have millisecond precision in LuaSocket, large blocks can cause I/O functions not to respect timeout values due to the time the library takes to transfer blocks to and from the OS and to and from the Lua interpreter. Also, function that accept host names and perform automatic name resolution might be blocked by the resolver for longer than the specified timeout value.
+---
+---**Note:** The old timeout method is deprecated. The name has been changed for sake of uniformity, since all other method names already contained verbs making their imperative nature obvious. 
+---
+---@param value number | nil Time to wait, in seconds. Use `nil` or negative to block indefinitely.
+---@param mode? TCPTimeoutMode The default mode is "b"
+function tcp_master:settimeout(value, mode) end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From 017bd82205512ea56ee2d3c399dbb690a2ffb369 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:21:25 +1300
Subject: [PATCH 26/35] Add client:shutdown() docs

---
 library/socket.lua | 11 +++++++++++
 1 file changed, 11 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index fd0a426..3915c30 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -592,6 +592,17 @@ function tcp_master:setstats(received, sent, age) end
 ---@param mode? TCPTimeoutMode The default mode is "b"
 function tcp_master:settimeout(value, mode) end
 
+---@alias TCPShutdownMode
+---| "both" Disallow further sends and receives on the object.
+---| "send" Disallow further sends on the object.
+---| "receive" Disallow further receives on the object.
+
+---
+---Shuts down part of a full-duplex connection. 
+---@param mode TCPShutdownMode Determines which way of the connection should be shut down.
+---@return 1 # Always returns 1.
+function tcp_client:shutdown(mode) end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From e90f50573b76f06e1334768ccef2627f8d54e8e4 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:23:20 +1300
Subject: [PATCH 27/35] Add master:setfd() docs

---
 library/socket.lua | 8 ++++++++
 1 file changed, 8 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index 3915c30..9cd7df4 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -603,6 +603,14 @@ function tcp_master:settimeout(value, mode) end
 ---@return 1 # Always returns 1.
 function tcp_client:shutdown(mode) end
 
+---
+---Sets the underling socket descriptor or handle associated to the object. The current one is simply replaced, not closed, and no other change to the object state is made. To set it as invalid use `_SOCKETINVALID`.
+---
+---**Note: This is an internal method. Unlikely to be portable. Use at your own risk.**
+---
+---@param fd integer
+function tcp_master:setfd(fd) end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.

From 0253455b63ea40b33609f729fe8845766231cbd5 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:26:27 +1300
Subject: [PATCH 28/35] Formatting for socket.tcp[46]

---
 library/socket.lua | 22 ++++++++++++++--------
 1 file changed, 14 insertions(+), 8 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index 9cd7df4..1d6f1d8 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -612,25 +612,31 @@ function tcp_client:shutdown(mode) end
 function tcp_master:setfd(fd) end
 
 ---
----Creates and returns an TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
----In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
----Note: The choice between IPv4 and IPv6 happens during a call to bind or connect, depending on the address family obtained from the resolver.
----Note: Before the choice between IPv4 and IPv6 happens, the internal socket object is invalid and therefore setoption will fail.
+---Creates and returns an TCP master object. A master object can be transformed into a server object with the method `listen` (after a call to `bind`) or into a client object with the method `connect`. The only other method supported by a master object is the close method.
+---
+---In case of success, a new master object is returned. In case of error, `nil` is returned, followed by an error message.
+---
+---Note: The choice between IPv4 and IPv6 happens during a call to `bind` or `connect`, depending on the address family obtained from the resolver.
+---
+---Note: Before the choice between IPv4 and IPv6 happens, the internal socket object is invalid and therefore `setoption` will fail.
 ---
 ---@return TCPSocketMaster
 function socket.tcp() end
 
 ---
----Creates and returns an IPv4 TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
+---Creates and returns an IPv4 TCP master object. A master object can be transformed into a server object with the method `listen` (after a call to `bind`) or into a client object with the method connect. The only other method supported by a master object is the `close` method.
+---
 ---In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
 ---
 ---@return TCPSocketMaster
 function socket.tcp4() end
 
 ---
----Creates and returns an IPv6 TCP master object. A master object can be transformed into a server object with the method listen (after a call to bind) or into a client object with the method connect. The only other method supported by a master object is the close method.
----In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
----Note: The TCP object returned will have the option "ipv6-v6only" set to true.
+---Creates and returns an IPv6 TCP master object. A master object can be transformed into a server object with the method `listen` (after a call to `bind`) or into a client object with the method `connect`. The only other method supported by a master object is the `close` method.
+---
+---In case of success, a new master object is returned. In case of error, `nil` is returned, followed by an error message.
+---
+---Note: The TCP object returned will have the option "ipv6-v6only" set to `true`.
 ---
 ---@return TCPSocketMaster
 function socket.tcp6() end

From 531dae1b241d760bdceeba9911c7015f333cfc29 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:28:53 +1300
Subject: [PATCH 29/35] Fix return types of socket.tcp[46]()

---
 library/socket.lua | 12 +++---------
 1 file changed, 3 insertions(+), 9 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index 1d6f1d8..415b3dd 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -614,31 +614,25 @@ function tcp_master:setfd(fd) end
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method `listen` (after a call to `bind`) or into a client object with the method `connect`. The only other method supported by a master object is the close method.
 ---
----In case of success, a new master object is returned. In case of error, `nil` is returned, followed by an error message.
----
 ---Note: The choice between IPv4 and IPv6 happens during a call to `bind` or `connect`, depending on the address family obtained from the resolver.
 ---
 ---Note: Before the choice between IPv4 and IPv6 happens, the internal socket object is invalid and therefore `setoption` will fail.
 ---
----@return TCPSocketMaster
+---@return TCPSocketMaster | nil, nil | string # New master object if successful, otherwise `nil` followed by an error message.
 function socket.tcp() end
 
 ---
 ---Creates and returns an IPv4 TCP master object. A master object can be transformed into a server object with the method `listen` (after a call to `bind`) or into a client object with the method connect. The only other method supported by a master object is the `close` method.
 ---
----In case of success, a new master object is returned. In case of error, nil is returned, followed by an error message.
----
----@return TCPSocketMaster
+---@return TCPSocketMaster | nil, nil | string # New master object if successful, otherwise `nil` followed by an error message.
 function socket.tcp4() end
 
 ---
 ---Creates and returns an IPv6 TCP master object. A master object can be transformed into a server object with the method `listen` (after a call to `bind`) or into a client object with the method `connect`. The only other method supported by a master object is the `close` method.
 ---
----In case of success, a new master object is returned. In case of error, `nil` is returned, followed by an error message.
----
 ---Note: The TCP object returned will have the option "ipv6-v6only" set to `true`.
 ---
----@return TCPSocketMaster
+---@return TCPSocketMaster | nil, nil | string # New master object if successful, otherwise `nil` followed by an error message.
 function socket.tcp6() end
 
 --#endregion

From 2c28c8eb6273a4c986c161c4b35542a756000b40 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:38:55 +1300
Subject: [PATCH 30/35] Refactor socket.bind docs

Makes it fit with new type, also some stylistic changes
---
 library/socket.lua | 13 ++++---------
 1 file changed, 4 insertions(+), 9 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index 415b3dd..e7342c7 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -37,19 +37,14 @@ socket.headers = {}
 socket.headers.canonic = {}
 
 ---
----This function is a shortcut that creates and returns a TCP server object
----bound to a local `address` and `port`, ready to
----accept client connections. Optionally,
----user can also specify the `backlog` argument to the
----`listen` method (defaults to 32).
+---This function is a shortcut that creates and returns a TCP server object bound to a local `address` and `port`, ready to accept client connections. Optionally, user can also specify the `backlog` argument to the `listen` method.
 ---
----Note: The server object returned will have the option `reuseaddr`
----set to `true`.
+---Note: The server object returned will have the option `reuseaddr` set to `true`.
 ---
 ---@param address string
 ---@param port integer
----@param backlog? integer
----@return TCPSocket
+---@param backlog? integer Defaults to 32.
+---@return TCPSocketServer
 ---
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
 function socket.bind(address, port, backlog) end

From 221cd4aaea84d392340e4ddab4f590038e5d9bf3 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:47:03 +1300
Subject: [PATCH 31/35] Fix return types of socket.connect[46]

---
 library/socket.lua | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/library/socket.lua b/library/socket.lua
index e7342c7..51c59ea 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -67,6 +67,7 @@ function socket.bind(address, port, backlog) end
 ---@param locport? integer
 ---@param family? 'inet'|'inet6'
 ---
+---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
 function socket.connect(address, port, locaddr, locport, family) end
 
@@ -81,6 +82,7 @@ function socket.connect(address, port, locaddr, locport, family) end
 ---@param locaddr? string
 ---@param locport? integer
 ---
+---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
 function socket.connect4(address, port, locaddr, locport) end
 
@@ -95,6 +97,7 @@ function socket.connect4(address, port, locaddr, locport) end
 ---@param locaddr? string
 ---@param locport? integer
 ---
+---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
 function socket.connect6(address, port, locaddr, locport) end
 

From d3ef96637379e888148fce708e1b83cea0a024c2 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:47:40 +1300
Subject: [PATCH 32/35] Stylistic changes to socket.connect[46] docs

---
 library/socket.lua | 24 +++++-------------------
 1 file changed, 5 insertions(+), 19 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index 51c59ea..d0b938c 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -50,32 +50,21 @@ socket.headers.canonic = {}
 function socket.bind(address, port, backlog) end
 
 ---
----This function is a shortcut that creates and returns a TCP client object
----connected to a remote `address` at a given `port`. Optionally,
----the user can also specify the local address and port to bind
----(`locaddr` and `locport`), or restrict the socket family
----to "`inet`" or "`inet6`".
+---This function is a shortcut that creates and returns a TCP client object connected to a remote `address` at a given `port`. Optionally, the user can also specify the local address and port to bind (`locaddr` and `locport`), or restrict the socket family to "`inet`" or "`inet6`".
 ---
----Without specifying `family` to `connect`, whether a tcp or tcp6
----connection is created depends on your system configuration. Two variations
----of connect are defined as simple helper functions that restrict the
----`family`, `socket.connect4` and `socket.connect6`.
+---Two variations of connect are defined as simple helper functions that restrict the `family`, `socket.connect4` and `socket.connect6`.
 ---
 ---@param address string
 ---@param port integer
 ---@param locaddr? string
 ---@param locport? integer
----@param family? 'inet'|'inet6'
----
+---@param family? 'inet'|'inet6' If not specified, the family depends on your system configuration.
 ---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
 function socket.connect(address, port, locaddr, locport, family) end
 
 ---
----This function is a shortcut that creates and returns an IPv4 TCP client
----object connected to a remote `address` at a given `port`. Optionally,
----the user can also specify the local address and port to bind
----(`locaddr` and `locport`)
+---This function is a shortcut that creates and returns an IPv4 TCP client object connected to a remote `address` at a given `port`. Optionally, the user can also specify the local address and port to bind (`locaddr` and `locport`)
 ---
 ---@param address string
 ---@param port integer
@@ -87,10 +76,7 @@ function socket.connect(address, port, locaddr, locport, family) end
 function socket.connect4(address, port, locaddr, locport) end
 
 ---
----This function is a shortcut that creates and returns an IPv6 TCP client
----object connected to a remote `address` at a given `port`. Optionally,
----the user can also specify the local address and port to bind
----(`locaddr` and `locport`)
+---This function is a shortcut that creates and returns an IPv6 TCP client object connected to a remote `address` at a given `port`. Optionally, the user can also specify the local address and port to bind (`locaddr` and `locport`)
 ---
 ---@param address string
 ---@param port integer

From 657b068f81fe66ee67f62d9c5368f04bf164ae16 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:48:53 +1300
Subject: [PATCH 33/35] Add parameter docs inline

---
 library/socket.lua | 12 ++++++------
 1 file changed, 6 insertions(+), 6 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index d0b938c..c240eb0 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -56,8 +56,8 @@ function socket.bind(address, port, backlog) end
 ---
 ---@param address string
 ---@param port integer
----@param locaddr? string
----@param locport? integer
+---@param locaddr? string The local address
+---@param locport? integer The local port
 ---@param family? 'inet'|'inet6' If not specified, the family depends on your system configuration.
 ---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
@@ -68,8 +68,8 @@ function socket.connect(address, port, locaddr, locport, family) end
 ---
 ---@param address string
 ---@param port integer
----@param locaddr? string
----@param locport? integer
+---@param locaddr? string The local address
+---@param locport? integer The local port
 ---
 ---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
@@ -80,8 +80,8 @@ function socket.connect4(address, port, locaddr, locport) end
 ---
 ---@param address string
 ---@param port integer
----@param locaddr? string
----@param locport? integer
+---@param locaddr? string The local address
+---@param locport? integer The local port
 ---
 ---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)

From adbb3e5d8e7a9d72097fe93559a90dfa62a783c2 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 18:50:21 +1300
Subject: [PATCH 34/35] Move socket.* tcp functions to the tcp region

---
 library/socket.lua | 104 +++++++++++++++++++++++----------------------
 1 file changed, 53 insertions(+), 51 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index c240eb0..4b10ab8 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -36,57 +36,6 @@ socket.headers = {}
 ---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
 socket.headers.canonic = {}
 
----
----This function is a shortcut that creates and returns a TCP server object bound to a local `address` and `port`, ready to accept client connections. Optionally, user can also specify the `backlog` argument to the `listen` method.
----
----Note: The server object returned will have the option `reuseaddr` set to `true`.
----
----@param address string
----@param port integer
----@param backlog? integer Defaults to 32.
----@return TCPSocketServer
----
----😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
-function socket.bind(address, port, backlog) end
-
----
----This function is a shortcut that creates and returns a TCP client object connected to a remote `address` at a given `port`. Optionally, the user can also specify the local address and port to bind (`locaddr` and `locport`), or restrict the socket family to "`inet`" or "`inet6`".
----
----Two variations of connect are defined as simple helper functions that restrict the `family`, `socket.connect4` and `socket.connect6`.
----
----@param address string
----@param port integer
----@param locaddr? string The local address
----@param locport? integer The local port
----@param family? 'inet'|'inet6' If not specified, the family depends on your system configuration.
----@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
----😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
-function socket.connect(address, port, locaddr, locport, family) end
-
----
----This function is a shortcut that creates and returns an IPv4 TCP client object connected to a remote `address` at a given `port`. Optionally, the user can also specify the local address and port to bind (`locaddr` and `locport`)
----
----@param address string
----@param port integer
----@param locaddr? string The local address
----@param locport? integer The local port
----
----@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
----😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
-function socket.connect4(address, port, locaddr, locport) end
-
----
----This function is a shortcut that creates and returns an IPv6 TCP client object connected to a remote `address` at a given `port`. Optionally, the user can also specify the local address and port to bind (`locaddr` and `locport`)
----
----@param address string
----@param port integer
----@param locaddr? string The local address
----@param locport? integer The local port
----
----@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
----😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
-function socket.connect6(address, port, locaddr, locport) end
-
 ---
 ---This constant is set to `true` if the library was compiled
 ---with debug support.
@@ -595,6 +544,59 @@ function tcp_client:shutdown(mode) end
 ---@param fd integer
 function tcp_master:setfd(fd) end
 
+-- The following are in the socket namespace --
+
+---
+---This function is a shortcut that creates and returns a TCP server object bound to a local `address` and `port`, ready to accept client connections. Optionally, user can also specify the `backlog` argument to the `listen` method.
+---
+---Note: The server object returned will have the option `reuseaddr` set to `true`.
+---
+---@param address string
+---@param port integer
+---@param backlog? integer Defaults to 32.
+---@return TCPSocketServer
+---
+---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
+function socket.bind(address, port, backlog) end
+
+---
+---This function is a shortcut that creates and returns a TCP client object connected to a remote `address` at a given `port`. Optionally, the user can also specify the local address and port to bind (`locaddr` and `locport`), or restrict the socket family to "`inet`" or "`inet6`".
+---
+---Two variations of connect are defined as simple helper functions that restrict the `family`, `socket.connect4` and `socket.connect6`.
+---
+---@param address string
+---@param port integer
+---@param locaddr? string The local address
+---@param locport? integer The local port
+---@param family? 'inet'|'inet6' If not specified, the family depends on your system configuration.
+---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
+---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
+function socket.connect(address, port, locaddr, locport, family) end
+
+---
+---This function is a shortcut that creates and returns an IPv4 TCP client object connected to a remote `address` at a given `port`. Optionally, the user can also specify the local address and port to bind (`locaddr` and `locport`)
+---
+---@param address string
+---@param port integer
+---@param locaddr? string The local address
+---@param locport? integer The local port
+---
+---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
+---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
+function socket.connect4(address, port, locaddr, locport) end
+
+---
+---This function is a shortcut that creates and returns an IPv6 TCP client object connected to a remote `address` at a given `port`. Optionally, the user can also specify the local address and port to bind (`locaddr` and `locport`)
+---
+---@param address string
+---@param port integer
+---@param locaddr? string The local address
+---@param locport? integer The local port
+---
+---@return TCPSocketClient | nil, nil | string # Returns the client on success, or `nil` and an error message on failure.
+---😱 [Types](https://github.com/LuaCATS/luasocket/blob/main/library/socket.lua) incomplete or incorrect? 🙏 [Please contribute!](https://github.com/LuaCATS/luasocket/pulls)
+function socket.connect6(address, port, locaddr, locport) end
+
 ---
 ---Creates and returns an TCP master object. A master object can be transformed into a server object with the method `listen` (after a call to `bind`) or into a client object with the method `connect`. The only other method supported by a master object is the close method.
 ---

From 9e498c3886c745b99f071d9b45225ad09cd26208 Mon Sep 17 00:00:00 2001
From: sofa <babalark@proton.me>
Date: Tue, 31 Dec 2024 19:11:16 +1300
Subject: [PATCH 35/35] Formatting

---
 library/socket.lua | 5 ++---
 1 file changed, 2 insertions(+), 3 deletions(-)

diff --git a/library/socket.lua b/library/socket.lua
index 4b10ab8..136fe7e 100644
--- a/library/socket.lua
+++ b/library/socket.lua
@@ -452,7 +452,6 @@ function tcp_master:listen(backlog) end
 ---| "timeout" If there was a timeout during the operation.
 ---| "closed" If the connection was closed before the transmission was completed.
 
-
 -- HACK: For some reason number doesn't show up in the completion if it's
 --       defined as part of this union. It should be defined in-place.
 
@@ -519,7 +518,7 @@ function tcp_master:setstats(received, sent, age) end
 ---
 ---**Note:** although timeout values have millisecond precision in LuaSocket, large blocks can cause I/O functions not to respect timeout values due to the time the library takes to transfer blocks to and from the OS and to and from the Lua interpreter. Also, function that accept host names and perform automatic name resolution might be blocked by the resolver for longer than the specified timeout value.
 ---
----**Note:** The old timeout method is deprecated. The name has been changed for sake of uniformity, since all other method names already contained verbs making their imperative nature obvious. 
+---**Note:** The old timeout method is deprecated. The name has been changed for sake of uniformity, since all other method names already contained verbs making their imperative nature obvious.
 ---
 ---@param value number | nil Time to wait, in seconds. Use `nil` or negative to block indefinitely.
 ---@param mode? TCPTimeoutMode The default mode is "b"
@@ -531,7 +530,7 @@ function tcp_master:settimeout(value, mode) end
 ---| "receive" Disallow further receives on the object.
 
 ---
----Shuts down part of a full-duplex connection. 
+---Shuts down part of a full-duplex connection.
 ---@param mode TCPShutdownMode Determines which way of the connection should be shut down.
 ---@return 1 # Always returns 1.
 function tcp_client:shutdown(mode) end