Binds the socket to a local address and port.
Must be called before Socket.listen for server sockets. Use host
"0.0.0.0" or "" to bind to all interfaces.
@eryx/_socket Module
JSON
Low-level BSD socket API for Luau.
This module exposes the platform's native socket interface, providing
TCP and UDP networking with non-blocking I/O support. All data transfer
uses Luau buffer objects for zero-copy efficiency.
Caution
This is a low-level API. For HTTP, prefer using @eryx/http,
which handle framing, TLS, and connection management automatically.
local sock = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
sock:connect("127.0.0.1", 8080)
sock:sendAll(buffer.fromstring("GET / HTTP/1.0\r\n\r\n"))
local data = sock:recv(4096)
print(buffer.tostring(data))
sock:close()
Summary
Classes
recvFrom: ((self: Socket, bufsize: number) → (buffer, string, number)) | ((self: Socket, bufsize: number) → (nil, nil, nil))
Functions
_socket.getAddrInfo(host: string?, service: (string | number)?, family: number?, type: number?, proto: number?, flags: number?) → { AddrInfo }
API Reference
Classes
Socket
Properties
Accepts an incoming connection, returning a new socket for the client along with the remote address and port.
Caution
This call blocks the current thread until a connection arrives (unless the socket is set to non-blocking mode via Socket.setblocking).
A nil return value indicates a non-blocking operation that would have blocked.
recvFrom: ((self: Socket, bufsize: number) → (buffer, string, number)) | ((self: Socket, bufsize: number) → (nil, nil, nil))
Receives a datagram of up to bufsize bytes along with the
sender's address (UDP).
A nil return value indicates a non-blocking operation that would have blocked.
Socket:bind
Socket:bind(host: string, port: number) → ()
Parameters
host: string
The local address to bind to.
port: number
The port number to bind to.
Socket:listen
Starts listening for incoming connections.
The socket must have been bound first. After calling this, use Socket.accept to accept individual connections.
Socket:listen(backlog: number?) → ()
Parameters
backlog: number?
Maximum number of queued connections. Defaults to a system-defined value (usually 128) when omitted.
Socket:connect
Opens a connection to a remote host.
For TCP sockets this performs the full three-way handshake. In non-blocking mode the call may return before the connection is fully established.
Socket:connect(host: string, port: number) → ()
Parameters
host: string
The remote address to connect to.
port: number
The remote port number.
Socket:close
Closes the socket, releasing all associated OS resources.
After closing, no further operations may be performed on this socket.
It is safe to call close multiple times.
Socket:close() → ()
Socket:shutdown
Shuts down one or both halves of the connection without closing the socket descriptor.
Use SHUT_RD (0) to stop reads, SHUT_WR (1) to stop writes,
or SHUT_RDWR (2) to stop both.
Socket:shutdown(how: number) → ()
Parameters
how: number
The shutdown mode - one of SHUT_RD, SHUT_WR, or SHUT_RDWR.
Socket:send
Sends data over the socket. Returns the number of bytes actually sent, which may be less than the full buffer length.
For guaranteed delivery of the entire buffer, use Socket.sendall instead.
A nil return value indicates a non-blocking operation that would have blocked.
Socket:send(data: buffer) → number?
Parameters
data: buffer
The data to send.
Returns
number?
Number of bytes sent.
Socket:sendAll
Sends all data in the buffer, retrying internally until every byte has been transmitted or an error occurs.
In blocking operation, this function always returns true.
In non-blocking operation, this function returns false is the
operation would have blocked.
Socket:sendAll(data: buffer) → boolean
Parameters
data: buffer
The data to send.
Socket:sendTo
Sends data to a specific destination address (UDP).
Primarily used with SOCK_DGRAM sockets. Returns the number of
bytes actually sent.
A nil return value indicates a non-blocking operation that would have blocked.
Socket:sendTo(data: buffer, host: string, port: number) → number?
Parameters
data: buffer
The datagram payload to send.
host: string
The destination address.
port: number
The destination port.
Returns
number?
Number of bytes sent.
Socket:recv
Receives up to bufsize bytes from the socket.
Returns a buffer containing the received data, which may be shorter
than bufsize. An empty buffer (length 0) typically indicates the
remote end has closed the connection.
A nil return value indicates a non-blocking operation that would have blocked.
Socket:recv(bufsize: number) → buffer?
Parameters
bufsize: number
Maximum number of bytes to receive.
Returns
buffer?
The received data.
Socket:setSockOpt
Sets a socket option.
Common combinations:
SOL_SOCKET, SO_REUSEADDR, true- allow port reuseSOL_SOCKET, SO_KEEPALIVE, true- enable keep-aliveIPPROTO_TCP, TCP_NODELAY, true- disable Nagle's algorithm
Socket:setSockOpt(level: number, optname: number, value: number | boolean) → ()
Parameters
level: number
The protocol level (e.g. SOL_SOCKET, IPPROTO_TCP).
optname: number
The option identifier.
value: number | boolean
The value to set - a number or boolean depending on the option.
Socket:getSockOpt
Gets the current value of a socket option.
Socket:getSockOpt(level: number, optname: number) → number
Parameters
level: number
The protocol level (e.g. SOL_SOCKET, IPPROTO_TCP).
optname: number
The option identifier.
Returns
number
The current option value.
Socket:setBlocking
Switches the socket between blocking and non-blocking mode.
In non-blocking mode, operations like Socket.recv and Socket.send will raise an error instead of waiting when no data is available.
Socket:setBlocking(flag: boolean) → ()
Parameters
flag: boolean
true for blocking, false for non-blocking.
Socket:setTimeout
Sets a timeout (in seconds) for blocking socket operations.
Pass nil or 0 to disable the timeout (wait indefinitely).
Socket:setTimeout(seconds: number?) → ()
Parameters
seconds: number?
Timeout duration, or nil for no timeout.
Socket:getPeerName
Returns the remote address and port of the connected peer.
Socket:getPeerName() → (string, number)
Returns
string
The remote IP address.
number
The remote port.
Socket:getSockName
Returns the local address and port the socket is bound to.
Socket:getSockName() → (string, number)
Returns
string
The local IP address.
number
The local port.
Socket:fileNo
Returns the underlying OS file descriptor / handle number for this socket. Useful for advanced I/O multiplexing.
Socket:fileNo() → number
Returns
number
The file descriptor.
Functions
_socket.poll
Drives the async I/O scheduler.
Call this once per frame, before task.step, to resume any coroutines that are waiting on socket I/O (recv, send, accept, connect).
while running do
_socket.poll()
task.step()
end
_socket.poll(timeout: number?) → number
Parameters
timeout: number?
How long to wait for I/O readiness, in seconds. 0 (default) returns immediately if nothing is ready. -1 blocks until at least one fd is ready.
Returns
number
Number of coroutines that were resumed this call.
_socket.socket
Creates a new socket.
local tcp = _socket.socket(_socket.AF_INET, _socket.SOCK_STREAM)
local udp = _socket.socket(_socket.AF_INET, _socket.SOCK_DGRAM)
Parameters
family: number
Address family - AF_INET (IPv4) or AF_INET6 (IPv6).
type: number
Socket type - SOCK_STREAM (TCP) or SOCK_DGRAM (UDP).
proto: number?
Protocol number, or nil to auto-select (usually 0).
Returns
The newly created socket.
_socket.getAddrInfo
Resolves a host/service pair into a list of address records suitable for creating and connecting sockets.
local results = _socket.getaddrinfo("example.com", 443, _socket.AF_INET, _socket.SOCK_STREAM)
for _, info in results do
print(info.addr, info.port)
end
_socket.getAddrInfo(host: string?, service: (string | number)?, family: number?, type: number?, proto: number?, flags: number?) → { AddrInfo }
Parameters
host: string?
Hostname or numeric address, or nil for the wildcard address.
service: (string | number)?
Service name (e.g. "http") or port number.
family: number?
Desired address family, or AF_UNSPEC to allow any.
type: number?
Desired socket type (e.g. SOCK_STREAM), or nil for any.
proto: number?
Desired protocol, or nil for any.
flags: number?
Bitwise OR of AI_* flags (e.g. AI_PASSIVE).
Returns
An array of resolved address records.
_socket.getNameInfo
Reverse-resolves a numeric address and port into a hostname and service name.
_socket.getNameInfo(host: string, port: number, flags: number?) → (string, string)
Parameters
host: string
The numeric IP address to look up.
port: number
The port number.
flags: number?
Bitwise OR of NI_* flags to control name resolution.
Returns
string
The resolved hostname.
string
The resolved service name.
_socket.htons
Converts a 16-bit value from host byte order to network byte order.
_socket.htons(x: number) → number
_socket.ntohs
Converts a 16-bit value from network byte order to host byte order.
_socket.ntohs(x: number) → number
_socket.htonl
Converts a 32-bit value from host byte order to network byte order.
_socket.htonl(x: number) → number
_socket.ntohl
Converts a 32-bit value from network byte order to host byte order.
_socket.ntohl(x: number) → number
Types
AddrInfo
Result record from getAddrInfo, representing a single resolved address with its protocol metadata.
family: number
type: number
proto: number
canonname: string
addr: string
port: number