lua-resty-websocket

To avoid race conditions in concurrent requests, never store a resty.websocket object in a Lua module-level variable. Because Nginx workers handle multiple concurrent requests, a module-level variable would be shared across them, leading to data corruption.

Best Practice: Always initiate WebSocket objects in function local variables or within the ngx.ctx table. These locations provide request-specific data copies.

The resty.websocket.client supports a connection pool to improve performance by reusing idle connections.

When calling client:connect, you can provide a pool name and pool_size. To actually put a connection into the pool for reuse, you must call client:set_keepalive(max_idle_timeout, pool_size) instead of client:close().

Advanced Pooling with backlog: If you specify the backlog option in connect, the module limits the total number of opened connections for that pool. If the pool is full, new connection attempts are queued. If the queue reaches the backlog size, subsequent attempts fail with "too many waiting connect operations".

The easiest way to use this library is to use the latest OpenResty bundle, where it is bundled and enabled by default. Requires OpenResty 1.4.2.9+ and LuaJIT.

If using a custom Nginx build with ngx_lua, ensure you have ngx_lua 0.9.0+ (and lua-bitop if not using LuaJIT). You must add the library path to your Nginx configuration using the lua_package_path directive.

# nginx.conf
http {
    lua_package_path "/path/to/lua-resty-websocket/lib/?.lua;;";
    ...
}

By default, ngx_lua logs errors when socket operations fail. If you are implementing custom error handling in your Lua code, you should disable this to avoid duplicate logs by setting the following in your nginx.conf:

lua_socket_log_errors off;

The recv_frame() method reads the next frame from the WebSocket connection.

Returns:

• data: The payload of the frame.
• typ: The opcode/type of the frame.
• err: An error message if the operation failed.

If a fatal error occurs (e.g., connection closed or protocol error), subsequent calls to recv_frame() will return a fatal error message. Note that a timeout is not considered a fatal error.

local data, typ, err = ws:recv_frame()
if not data and err ~= ": timeout" then
    -- handle fatal error
    return
end

To gracefully terminate the connection, call close(). This method sends a WebSocket close frame (opcode 0x8) if the connection is not already closed, and then closes the underlying TCP socket.

Alternatively, you can use send_close(code, msg) to send a specific close code and reason before closing the socket manually.

Close Codes:

• code: A numeric status code (up to 0x7fff).
• msg: An optional string message explaining the closure.

-- Graceful close
local ok, err = wb:close()
if not ok then
    ngx.log(ngx.ERR, "close failed: ", err)
end

Manage the WebSocket lifecycle and heartbeat using control frames.

• send_close(code, msg): Sends a close frame. code must be a number $\le$ 0x7fff. msg is an optional string.
• send_ping(data): Sends a ping frame (opcode 0x9).
• send_pong(data): Sends a pong frame (opcode 0xa).

-- Close the connection with a specific status code
ws:send_close(1000, "Normal Closure")

-- Send a ping for heartbeat
ws:send_ping()

Use resty.websocket.server.new(opts) to upgrade an HTTP request to a WebSocket connection. This function validates the handshake headers (Upgrade, Connection, Sec-WebSocket-Key, and Sec-WebSocket-Version) and sends the 101 Switching Protocols response.

Options (opts)

• max_payload_len: Maximum payload length (default: 65535).
• max_recv_len: Maximum length for receiving frames (defaults to max_payload_len).
• max_send_len: Maximum length for sending frames (defaults to max_payload_len).
• send_masked: Boolean indicating if frames should be masked (default: nil).
• timeout: Socket timeout in seconds.

local server = require "resty.websocket.server"

local ok, ws = server.new({
    max_payload_len = 65535,
    timeout = 10
})

if not ok then
    ngx.log(ngx.ERR, "failed to initialize websocket: ", ws)
    return
end

To use the WebSocket client, first create an instance using new(opts). This initializes the underlying TCP socket.

Options (opts):

• max_payload_len: Maximum payload length (default: 65535).
• max_recv_len: Maximum length for receiving frames (defaults to max_payload_len).
• max_send_len: Maximum length for sending frames (defaults to max_payload_len).
• send_unmasked: Boolean. If true, frames are sent without masking.
• timeout: Socket timeout in seconds.

Returns the client object or nil, err.

local client = require "resty.websocket.client"
local wb, err = client.new({
    max_payload_len = 65535,
    timeout = 10
})
if not wb then
    ngx.log(ngx.ERR, "failed to create client: ", err)
    return
end