ws

The ws namespace — 5 functions.

ws/close

ws.close(handle)

Close the connection. Pending ws.recv promises resolve with {kind='closed'}.

Parameters

• handle number — Connection handle

ws/connect

ws.connect(url, headers?) -> string

Open a WebSocket. Returns a promise id — use task.await + ws.poll. Headers is an optional table of {name=value} string pairs.

Parameters

• url string — WebSocket URL (ws:// or wss://)
• headers table (optional) — Request headers (string→string)

Returns string — Promise id for ws.poll()

ws/poll

ws.poll(promise_id) -> table | nil

Poll one ws.connect / ws.recv promise. Returns nil while pending. On resolution returns one of {kind='connected', handle}, {kind='connect_failed', error}, {kind='frame', text|bytes}, {kind='closed', reason}, {kind='recv_failed', error}.

Parameters

• promise_id string — Promise id from ws.connect() or ws.recv()

Returns table | nil — Resolved result, or nil if still pending

ws/recv

ws.recv(handle) -> string

Async-wait for one frame on an open connection. Returns a promise id — ws.poll resolves with {kind='frame', text|bytes} or {kind='closed', reason} or {kind='recv_failed', error}.

Parameters

• handle number — Connection handle from ws.poll on a previous ws.connect

Returns string — Promise id for ws.poll()

ws/send

ws.send(handle, text)

Send a text frame on an open connection. Silent no-op if the handle is unknown / closed. Binary frames not yet supported by this surface.

Parameters

• handle number — Connection handle
• text string — Frame payload (UTF-8)