WebsocketConnection

class WebsocketConnection(**properties: Any)

Superclasses: Object

The WebSocket Protocol

Provides support for the WebSocket protocol.

To connect to a WebSocket server, create a Session and call websocket_connect_async. To accept WebSocket connections, create a Server and add a handler to it with add_websocket_handler.

(Lower-level support is available via websocket_client_prepare_handshake and websocket_client_verify_handshake, for handling the client side of the WebSocket handshake, and websocket_server_process_handshake for handling the server side.)

WebsocketConnection handles the details of WebSocket communication. You can use send_text and send_binary to send data, and the message signal to receive data. (WebsocketConnection currently only supports asynchronous I/O.)

Constructors

class WebsocketConnection

classmethod new(stream: IOStream, uri: Uri, type: WebsocketConnectionType, origin: str | None, protocol: str | None, extensions: list[WebsocketExtension]) → WebsocketConnection

Creates a WebsocketConnection on stream with the given active extensions.

This should be called after completing the handshake to begin using the WebSocket protocol.

Parameters:

stream – a IOStream connected to the WebSocket server
uri – the URI of the connection
type – the type of connection (client/side)
origin – the Origin of the client
protocol – the subprotocol in use
extensions – a List of WebsocketExtension objects

Methods

class WebsocketConnection

close(code: int, data: str | None = None) → None

Close the connection in an orderly fashion.

Note that until the closed signal fires, the connection is not yet completely closed. The close message is not even sent until the main loop runs.

The code and data are sent to the peer along with the close request. If code is NO_STATUS a close message with no body (without code and data) is sent. Note that the data must be UTF-8 valid.

Parameters:

code – close code
data – close data

get_close_code() → int

Get the close code received from the WebSocket peer.

This only becomes valid once the WebSocket is in the CLOSED state. The value will often be in the WebsocketCloseCode enumeration, but may also be an application defined close code.

get_close_data() → str

Get the close data received from the WebSocket peer.

This only becomes valid once the WebSocket is in the CLOSED state. The data may be freed once the main loop is run, so copy it if you need to keep it around.

get_connection_type() → WebsocketConnectionType: Get the connection type (client/server) of the connection.

get_extensions() → list[WebsocketExtension]: Get the extensions chosen via negotiation with the peer.

get_io_stream() → IOStream: Get the I/O stream the WebSocket is communicating over.

get_keepalive_interval() → int: Gets the keepalive interval in seconds or 0 if disabled.

get_max_incoming_payload_size() → int: Gets the maximum payload size allowed for incoming packets.

get_origin() → str | None: Get the origin of the WebSocket.

get_protocol() → str | None: Get the protocol chosen via negotiation with the peer.

get_state() → WebsocketState: Get the current state of the WebSocket.

get_uri() → Uri

Get the URI of the WebSocket.

For servers this represents the address of the WebSocket, and for clients it is the address connected to.

send_binary(data: Sequence[int] | None = None) → None

Send a binary message to the peer.

If length is 0, data may be None.

The message is queued to be sent and will be sent when the main loop is run.

Parameters:: data – the message contents

send_message(type: WebsocketDataType, message: Bytes) → None

Send a message of the given type to the peer. Note that this method, allows to send text messages containing None characters.

The message is queued to be sent and will be sent when the main loop is run.

Parameters:

type – the type of message contents
message – the message data as Bytes

send_text(text: str) → None

Send a None-terminated text (UTF-8) message to the peer.

If you need to send text messages containing None characters use send_message instead.

The message is queued to be sent and will be sent when the main loop is run.

Parameters:: text – the message contents

set_keepalive_interval(interval: int) → None

Sets the interval in seconds on when to send a ping message which will serve as a keepalive message.

If set to 0 the keepalive message is disabled.

Parameters:: interval – the interval to send a ping message or 0 to disable it

set_max_incoming_payload_size(max_incoming_payload_size: int) → None

Sets the maximum payload size allowed for incoming packets.

It does not limit the outgoing packet size.

Parameters:: max_incoming_payload_size – the maximum payload size

Properties

class WebsocketConnection

props.connection_type: WebsocketConnectionType: The type of connection (client/server).

props.extensions: None: List of WebsocketExtension objects that are active in the connection.

props.io_stream: IOStream

The underlying IO stream the WebSocket is communicating over.

The input and output streams must be pollable streams.

props.keepalive_interval: int

Interval in seconds on when to send a ping message which will serve as a keepalive message.

If set to 0 the keepalive message is disabled.

props.max_incoming_payload_size: int

The maximum payload size for incoming packets.

The protocol expects or 0 to not limit it.

props.origin: str: The client’s Origin.

props.protocol: str: The chosen protocol, or None if a protocol was not agreed upon.

props.state: WebsocketState: The current state of the WebSocket.

props.uri: Uri

The URI of the WebSocket.

For servers this represents the address of the WebSocket, and for clients it is the address connected to.

Signals

class WebsocketConnection.signals

closed() → None

Emitted when the connection has completely closed.

This happens either due to an orderly close from the peer, one initiated via close or a fatal error condition that caused a close.

This signal will be emitted once.

closing() → None: This signal will be emitted during an orderly close.

error(error: GError) → None

Emitted when an error occurred on the WebSocket.

This may be fired multiple times. Fatal errors will be followed by the closed signal being emitted.

Parameters:: error – the error that occured

message(type: int, message: Bytes) → None

Emitted when we receive a message from the peer.

As a convenience, the message data will always be None-terminated, but the NUL byte will not be included in the length count.

Parameters:

type – the type of message contents
message – the message data

pong(message: Bytes) → None

Emitted when we receive a Pong frame (solicited or unsolicited) from the peer.

As a convenience, the message data will always be None-terminated, but the NUL byte will not be included in the length count.

Parameters:: message – the application data (if any)