tcpServer Reference

Module defined in lua/common/tcpServer.lua. Non-blocking TCP server with a binary-framed JSON message protocol. Supports both LuaSocket and ASIO (C++ engine) backends.

Exports

The module returns the TCPServer class directly.

Functions

TCPServer:new(listenHost, port)

Creates and starts a new TCP server.

• Parameters:
  • listenHost - string - Host to bind to (e.g., "localhost")
  • port - number - Port to listen on
• Returns: TCPServer|false - Server instance or false on failure

server:send(connection, sendData, recData)

Sends a JSON message to a connected client using the binary framing protocol.

• Parameters:
  • connection - userdata - Client connection handle
  • sendData - table - Data to JSON-encode and send
  • recData - table|nil - If present and has .context, it's copied to sendData

server:receiveData()

Polls for new connections and incoming data. Non-blocking.

• Returns: table - Array of {connection, data} pairs. Data is a decoded Lua table, or the string "disconnect" for disconnected clients.

server:destroy()

Closes all connections and shuts down the server.

Internal Functions

M._onDataRaw(data)

Internal callback for raw data reception. Handles incoming TCP data before processing.

• Parameters:
  • data - string - Raw received data

Internal Notes

Wire Protocol

+-------------------+---------------------+
| 4-byte Identifier | 4-byte Message Size |
| "BN01"            | uint32_t (LE)       |
+-------------------+---------------------+
| JSON Data (variable length)             |
| (Null-terminated)                       |
+-----------------------------------------+

• Identifier: BN01 (4 bytes)
• Length: 32-bit unsigned little-endian integer, includes the null terminator
• Payload: JSON string + \0

Backend Selection

• If createNetworkServer is available (C++ engine), uses ASIO backend
• Otherwise falls back to LuaSocket with non-blocking sockets
• Uses string.buffer for efficient message buffering
• FFI is used for header struct manipulation