classDocs / WebSocket

WebSocket

classsharedsource

Object → WebSocket

A WebSocket client. Backends are tried in order: gwsockets, tungstenite, then a WebClient / browser fallback on client and menu.

A socket stays alive while it is connecting, open or waiting for a reconnect, even without references to it, call close to release it.

Constructor

WebSocket(url: string | URL, options: WebSocket.Options?): WebSocket

Fields

Name	Type	Description
`url`	`string`	The WebSocket URL. Read-only.
`BackendName`	`"tungstenite" \| "gwsockets" \| "webclient" \| ""`	The loaded WebSocket backend, empty if none was found.
`Capabilities`	`dreamwork.engine.websocket.Capabilities`	Features supported by the loaded backend. Read-only.

Methods

`attach`	Attaches a handler for the given event.
`await`	Waits until the given event fires, then resumes with that event's arguments.
`clear`	Removes every handler for event, or every handler of every event when omitted.
`close`	Closes the connection and cancels a pending reconnect; a locally closed socket never reconnects.
`detach`	Detaches a previously attached handler from the given event.
`getStatus`	Returns the current connection status as a string.
`isClosed`	Returns true when the socket is not connected, also while waiting for a reconnect.
`isClosing`	Returns true while a graceful close is in progress.
`isConnected`	Alias of WebSocket:isOpen.
`isConnecting`	Returns true while the handshake is in progress.
`isOpen`	Returns true when the socket is open and ready to send / receive.
`isReconnecting`	Returns true while a reconnect attempt is scheduled.
`once`	Attaches a one-shot handler for the given event.
`open`	Opens the connection, cancelling a pending reconnect and resetting its attempt counter.
`send`	Sends a message. Binary frames need Capabilities.binary, otherwise the payload is sent as text.
`write`	Alias of WebSocket:send.

#WebSocket:attach

sharedsource

function WebSocket:attach(event: WebSocket.Event, handler: function)

Attaches a handler for the given event.

Parameters

Name	Type	Description
`event`	`WebSocket.Event`	The event to listen to: `"open"`, `"message"`, `"close"`, `"error"` or `"reconnect"`.
`handler`	`function`	The callback; signature depends on `event` (see overloads).

Overloads

function WebSocket:attach(self: WebSocket, event: "open", handler: WebSocket.OpenHandler)

function WebSocket:attach(self: WebSocket, event: "message", handler: WebSocket.MessageHandler)

function WebSocket:attach(self: WebSocket, event: "close", handler: WebSocket.CloseHandler)

function WebSocket:attach(self: WebSocket, event: "error", handler: WebSocket.ErrorHandler)

function WebSocket:attach(self: WebSocket, event: "reconnect", handler: WebSocket.ReconnectHandler)

#WebSocket:await

sharedasyncsource

async function WebSocket:await(event: WebSocket.Event): any

Waits until the given event fires, then resumes with that event's arguments.

"open" returns at once when the socket is already open;
"close" returns the last close at once when the socket is closed and no reconnect is pending;
anything else throws when the socket is closed with no reconnect pending, or when the socket closes first (a failed reconnect attempt counts as a close).

Parameters

Name	Type	Description
`event`	`WebSocket.Event`	The event to wait for: `"open"`, `"message"`, `"close"`, `"error"` or `"reconnect"`.

Returns

Type	Name	Description
`any`	`...`	The arguments that event's handlers receive.

Overloads

function WebSocket:await(self: WebSocket, event: "open"): WebSocket

function WebSocket:await(self: WebSocket, event: "message"): WebSocket, string

function WebSocket:await(self: WebSocket, event: "close"): WebSocket, string | nil, integer | nil, boolean

function WebSocket:await(self: WebSocket, event: "error"): WebSocket, string

function WebSocket:await(self: WebSocket, event: "reconnect"): WebSocket, integer, number

#WebSocket:clear

sharedsource

function WebSocket:clear(event?: WebSocket.Event)

Removes every handler for event, or every handler of every event when omitted.

Parameters

Name	Type	Description
`event`optional	`WebSocket.Event`	The event to clear, or `nil` to clear all events.

#WebSocket:close

sharedsource

function WebSocket:close(force?: boolean)

Closes the connection and cancels a pending reconnect; a locally closed socket never reconnects.

With force, terminates immediately (code 1006) and discards queued outbound messages when possible; otherwise flushes first when the backend supports it, and terminates when the peer does not finish the close within close_timeout seconds.

Parameters

Name	Type	Description
`force`optional	`boolean`	Immediately terminate instead of a graceful close. Defaults to `false`.

#WebSocket:detach

sharedsource

function WebSocket:detach(event: WebSocket.Event, handler: function)

Detaches a previously attached handler from the given event.

Parameters

Name	Type	Description
`event`	`WebSocket.Event`	The event the handler was attached to.
`handler`	`function`	The exact callback previously passed to `attach` or `once`.

Overloads

function WebSocket:detach(self: WebSocket, event: "open", handler: WebSocket.OpenHandler)

function WebSocket:detach(self: WebSocket, event: "message", handler: WebSocket.MessageHandler)

function WebSocket:detach(self: WebSocket, event: "close", handler: WebSocket.CloseHandler)

function WebSocket:detach(self: WebSocket, event: "error", handler: WebSocket.ErrorHandler)

function WebSocket:detach(self: WebSocket, event: "reconnect", handler: WebSocket.ReconnectHandler)

#WebSocket:getStatus

sharednodiscardsource

function WebSocket:getStatus(): WebSocket.Status

Returns the current connection status as a string.

Returns

Type	Name	Description
`WebSocket.Status`	`status`	`"connecting"`, `"open"`, `"closing"` or `"closed"`.

#WebSocket:isClosed

sharednodiscardsource

function WebSocket:isClosed(): boolean

Returns true when the socket is not connected, also while waiting for a reconnect.

Returns

Type	Name	Description
`boolean`	`is_closed`	`true` if status is `"closed"`.

#WebSocket:isClosing

sharednodiscardsource

function WebSocket:isClosing(): boolean

Returns true while a graceful close is in progress.

Returns

Type	Name	Description
`boolean`	`is_closing`	`true` if status is `"closing"`.

#WebSocket:isConnected

sharednodiscardsource

function WebSocket:isConnected(): boolean

Alias of WebSocket:isOpen.

Returns

Type	Name	Description
`boolean`	`is_connected`	`true` if status is `"open"`.

#WebSocket:isConnecting

sharednodiscardsource

function WebSocket:isConnecting(): boolean

Returns true while the handshake is in progress.

Returns

Type	Name	Description
`boolean`	`is_connecting`	`true` if status is `"connecting"`.

#WebSocket:isOpen

sharednodiscardsource

function WebSocket:isOpen(): boolean

Returns true when the socket is open and ready to send / receive.

Returns

Type	Name	Description
`boolean`	`is_open`	`true` if status is `"open"`.

#WebSocket:isReconnecting

sharednodiscardsource

function WebSocket:isReconnecting(): boolean

Returns true while a reconnect attempt is scheduled.

Returns

Type	Name	Description
`boolean`	`is_reconnecting`

#WebSocket:once

sharedsource

function WebSocket:once(event: WebSocket.Event, handler: function)

Attaches a one-shot handler for the given event.

The handler is detached automatically right before it runs.

Parameters

Name	Type	Description
`event`	`WebSocket.Event`	The event to listen to: `"open"`, `"message"`, `"close"`, `"error"` or `"reconnect"`.
`handler`	`function`	The callback; signature depends on `event` (see overloads).

Overloads

function WebSocket:once(self: WebSocket, event: "open", handler: WebSocket.OpenHandler)

function WebSocket:once(self: WebSocket, event: "message", handler: WebSocket.MessageHandler)

function WebSocket:once(self: WebSocket, event: "close", handler: WebSocket.CloseHandler)

function WebSocket:once(self: WebSocket, event: "error", handler: WebSocket.ErrorHandler)

function WebSocket:once(self: WebSocket, event: "reconnect", handler: WebSocket.ReconnectHandler)

#WebSocket:open

sharedsource

function WebSocket:open()

Opens the connection, cancelling a pending reconnect and resetting its attempt counter.

Throws if the socket is already connecting, open or closing, or if the backend fails to create the socket.

#WebSocket:send

sharedsource

function WebSocket:send(message: string, is_binary?: boolean)

Sends a message. Binary frames need Capabilities.binary, otherwise the payload is sent as text.

Parameters

Name	Type	Description
`message`	`string`	The payload to send.
`is_binary`optional	`boolean`	Send as a binary frame. Defaults to `false`.

#WebSocket:write

sharedsource

function WebSocket:write(message: string, is_binary?: boolean)

Alias of WebSocket:send.

Parameters

Name	Type	Description
`message`	`string`	The payload to send.
`is_binary`optional	`boolean`	Send as a binary frame. Defaults to `false`.