Module `eco.websocket`

WebSocket client/server helpers.

This module implements basic WebSocket framing and the HTTP upgrade handshake.

It can be used in two ways:

Server side: call websocket.upgrade from an eco.http.server request handler.
Client side: call websocket.connect to perform the upgrade handshake and obtain a WebSocket connection.

The returned connection object supports sending and receiving individual WebSocket frames. Fragmented messages are not automatically reassembled; see connection:recv_frame for the err == 'again' convention.

Functions

upgrade (con, req[, opts])	Upgrade an eco.http.server connection to WebSocket.
connect (uri[, opts])	Connect to a WebSocket server.

Tables

WebSocketOptions	Options table for WebSocket connections.
ConnectOptions	Options table for websocket.connect.

Class connection

connection:recv_frame ([timeout])	Receive a single WebSocket frame.
connection:send_frame (fin, opcode[, payload])	Send a raw WebSocket frame.
connection:send_text ([data])	Send a text frame.
connection:send_binary ([data])	Send a binary frame.
connection:send_close ([code[, msg]])	Send a close frame.
connection:send_ping ([data])	Send a ping frame.
connection:send_pong ([data])	Send a pong frame.

Functions

upgrade (con, req[, opts])

Upgrade an eco.http.server connection to WebSocket.

This performs server-side validation of the WebSocket handshake and sends the 101 Switching Protocols response.

Parameters:

con connection HTTP server connection (from eco.http.server).
req table HTTP request table (from eco.http.server).
opts WebSocketOptions Options. (optional)

Returns:

connection

Or

nil On failure.
string Error message.

Usage:

local websocket = require 'eco.websocket'
local http = require 'eco.http.server'
local eco = require 'eco'

local function handler(con, req)
  if req.path == '/ws' then
    local ws, err = websocket.upgrade(con, req, { max_payload_len = 65535 })
    if not ws then return nil, err end
    local data, typ = ws:recv_frame()
    if typ == 'ping' then ws:send_pong(data) end
  end
end

eco.run(function()
    assert(http.listen(nil, 8080, { reuseaddr = true }, handler))
end)

eco.loop()

connect (uri[, opts])

Connect to a WebSocket server.

This performs an HTTP upgrade handshake for ws:// or wss:// URIs and returns a WebSocket connection on success.

Parameters:

uri string WebSocket URI.
opts ConnectOptions Options. (optional)

Returns:

connection

Or

nil On failure.
string err Error message.

Usage:

local websocket = require 'eco.websocket'
local eco = require 'eco'

eco.run(function()
    local ws, err = websocket.connect('ws://127.0.0.1:8080/ws')
    assert(ws, err)
    ws:send_text('hello')
end)

eco.loop()

Tables

WebSocketOptions

Options table for WebSocket connections.

Fields:

max_payload_len integer Maximum payload length accepted/sent. (default 65535)

ConnectOptions

Options table for websocket.connect.

Fields:

headers table Extra HTTP headers to send during handshake. (optional)
protocols string or table Sec-WebSocket-Protocol value. If a table is provided, it will be joined using commas. (optional)
origin string Origin header value. (optional)
insecure boolean Passed to eco.http.client (TLS verify control). (optional)
timeout number Request timeout in seconds (passed to HTTP client). (optional)
max_payload_len integer Maximum payload length accepted/sent. (default 65535)

Class connection

UBus connection returned by ubus.connect.

This object manages an ubus connection and dispatches events/call replies in a background coroutine.

connection:recv_frame ([timeout])

Receive a single WebSocket frame.

Return convention:

On success: data, typ, err
On failure: nil, nil, err

typ is one of: 'text', 'binary', 'continuation', 'close', 'ping', 'pong'.

For typ == 'close', err carries the close status code (number) when present, and data carries the close reason string.

For fragmented messages, err == 'again' indicates that more frames are expected to complete the message.

Parameters:

timeout number Timeout in seconds. (optional)

Returns:

string data Frame payload.
string typ Frame type.
any err Extra information ('again' for fragmentation, or close code).

Or

nil On failure.
nil On failure.
string err Error message.

connection:send_frame (fin, opcode[, payload])

Send a raw WebSocket frame.

opcode values follow RFC 6455:

0x1 text
0x2 binary
0x8 close
0x9 ping
0xA pong

Parameters:

fin boolean Whether this is the final fragment.
opcode integer Frame opcode.
payload string Frame payload (will be converted to string if not already). (optional)

Returns:

integer

Or

nil On failure.
string Error message.

connection:send_text ([data])

Send a text frame.

Parameters:

data string Text payload. (optional)

Returns:

integer

Or

nil On failure.
string Error message.

connection:send_binary ([data])

Send a binary frame.

Parameters:

data string Binary payload. (optional)

Returns:

integer

Or

nil On failure.
string Error message.

connection:send_close ([code[, msg]])

Send a close frame.

Parameters:

code integer Close status code. (optional)
msg string Close reason. (optional)

Returns:

integer

Or

nil On failure.
string Error message.

connection:send_ping ([data])

Send a ping frame.

Parameters:

data string Payload. (optional)

Returns:

integer

Or

nil On failure.
string Error message.

connection:send_pong ([data])

Send a pong frame.

Parameters:

data string Payload. (optional)

Returns:

integer

Or

nil On failure.
string Error message.

lua-eco

Contents

Modules

Topics

Examples

Module eco.websocket

Functions

Tables

Class connection

Functions

Parameters:

Returns:

Or

Usage:

Parameters:

Returns:

Or

Usage:

Tables

Fields:

Fields:

Class connection

Parameters:

Returns:

Or

Parameters:

Returns:

Or

Parameters:

Returns:

Or

Parameters:

Returns:

Or

Parameters:

Returns:

Or

Parameters:

Returns:

Or

Parameters:

Returns:

Or

Module `eco.websocket`