ws

The ws namespace: 6 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 request id that ws.poll answers once the dial settles. 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 — Request id for ws.poll()

ws/liveness

ws.liveness(handle) -> table | nil

What an open connection has carried lately: {idleMs, inbound, keepaliveMs?}. idleMs is how long nothing has arrived, inbound how many frames have. keepaliveMs is the interval at which the transport asks the peer to prove it is there: present on native, where the engine sends a protocol ping and sees the pong, and absent in a browser, whose WebSocket answers pings itself and exposes neither direction to script. Silence says the peer is gone only against that interval. Returns nil for a handle no connection holds.

Parameters

• handle number — Connection handle

Returns table | nil — Liveness reading, or nil if the handle is unknown

ws/poll

ws.poll(promise_id) -> table | nil

Poll one ws.connect / ws.recv request. Returns nil while pending. Once it settles, returns one of {kind='connected', handle}, {kind='connect_failed', error}, {kind='frame', text|bytes}, {kind='closed', reason}, {kind='recv_failed', error}, and the request is spent.

Parameters

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

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

ws/recv

ws.recv(handle) -> string

Ask for one frame on an open connection. Returns a request id; ws.poll answers it 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 — Request 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)