Struct WebSocketClient 

pub struct WebSocketClient { /* private fields */ }

WebSocket client with automatic reconnection.

Handles connection state, callbacks, and rate limiting. See module docs for architecture details.

Implementations

impl WebSocketClient

pub async fn connect_stream( config: WebSocketConfig, keyed_quotas: Vec<(String, Quota)>, default_quota: Option<Quota>, post_reconnect: Option<Arc<dyn Fn() + Send + Sync>>, ) -> Result<(MessageReader, Self), Error>

Creates a websocket client in stream mode that returns a MessageReader.

Returns a stream that the caller owns and reads from directly. Automatic reconnection is disabled because the reader cannot be replaced internally. On disconnection, the client transitions to CLOSED state and the caller must manually reconnect by calling connect_stream again.

Use stream mode when you need custom reconnection logic, direct control over message reading, or fine-grained backpressure handling.

See WebSocketConfig documentation for comparison with handler mode.

Errors

Returns an error if the connection cannot be established.

pub async fn connect( config: WebSocketConfig, message_handler: Option<MessageHandler>, ping_handler: Option<PingHandler>, post_reconnection: Option<Arc<dyn Fn() + Send + Sync>>, keyed_quotas: Vec<(String, Quota)>, default_quota: Option<Quota>, ) -> Result<Self, Error>

Creates a websocket client in handler mode with automatic reconnection.

The handler is called for each incoming message on an internal task. Automatic reconnection is enabled with exponential backoff. On disconnection, the client automatically attempts to reconnect and replaces the internal reader (the handler continues working seamlessly).

Use handler mode for simplified connection management, automatic reconnection, Python bindings, or callback-based message handling.

See WebSocketConfig documentation for comparison with stream mode.

Errors

Returns an error if:

• The connection cannot be established.
• message_handler is None (use connect_stream instead).

pub fn connection_mode(&self) -> ConnectionMode

Returns the current connection mode.

pub fn connection_mode_atomic(&self) -> Arc<AtomicU8>

Returns a clone of the connection mode atomic for external state tracking.

This allows adapter clients to track connection state across reconnections without message-passing delays.

pub fn is_active(&self) -> bool

Check if the client connection is active.

Returns true if the client is connected and has not been signalled to disconnect. The client will automatically retry connection based on its configuration.

pub fn is_disconnected(&self) -> bool

Check if the client is disconnected.

pub fn is_reconnecting(&self) -> bool

Check if the client is reconnecting.

Returns true if the client lost connection and is attempting to reestablish it. The client will automatically retry connection based on its configuration.

pub fn is_disconnecting(&self) -> bool

Check if the client is disconnecting.

Returns true if the client is in disconnect mode.

pub fn is_closed(&self) -> bool

Check if the client is closed.

Returns true if the client has been explicitly disconnected or reached maximum reconnection attempts. In this state, the client cannot be reused and a new client must be created for further connections.

pub fn notify_closed(&self)

Signals that the caller’s reader has observed EOF or a fatal error.

In stream mode the controller has no visibility into the caller-owned reader. Call this method when reader.next().await returns None or an unrecoverable error so the controller transitions to Closed and dependent tasks shut down.

For peer-initiated close frames (Message::Close), use disconnect instead so the writer can send the close reply before shutting down.

This is a no-op if the connection is already closed or disconnecting.

pub async fn disconnect(&self)

Set disconnect mode to true.

Controller task will periodically check the disconnect mode and shutdown the client if it is alive

pub async fn send_text( &self, data: String, keys: Option<&[Ustr]>, ) -> Result<(), SendError>

Sends the given text data to the server.

Returns Ok(()) when the message is enqueued to the writer channel. This does NOT guarantee delivery: if a disconnect occurs concurrently, the writer task may drop the message. During reconnection, messages are buffered and replayed on the new connection.

Errors

Returns a websocket error if unable to send.

pub async fn send_pong(&self, data: Vec<u8>) -> Result<(), SendError>

Sends a pong frame back to the server.

Errors

Returns a websocket error if unable to send.

pub async fn send_bytes( &self, data: Vec<u8>, keys: Option<&[Ustr]>, ) -> Result<(), SendError>

Sends the given bytes data to the server.

Returns Ok(()) when the message is enqueued to the writer channel. This does NOT guarantee delivery: if a disconnect occurs concurrently, the writer task may drop the message. During reconnection, messages are buffered and replayed on the new connection.

Errors

Returns a websocket error if unable to send.

pub async fn send_close_message(&self) -> Result<(), SendError>

Sends a close message to the server.

Errors

Returns a websocket error if unable to send.

Trait Implementations

impl Debug for WebSocketClient

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Drop for WebSocketClient

fn drop(&mut self)

Executes the destructor for this type.

impl<'py> IntoPyObject<'py> for WebSocketClient

type Target = WebSocketClient

The Python output type

type Output = Bound<'py, <WebSocketClient as IntoPyObject<'py>>::Target>

The smart pointer type to use.

type Error = PyErr

The type returned in the event of a conversion error.

fn into_pyobject( self, py: Python<'py>, ) -> Result<<Self as IntoPyObject<'_>>::Output, <Self as IntoPyObject<'_>>::Error>

Performs the conversion.

impl PyClass for WebSocketClient

const NAME: &str = "WebSocketClient"

Name of the class.

type Frozen = False

Whether the pyclass is frozen.

impl PyClassImpl for WebSocketClient

const MODULE: Option<&str>

Module which the class will be associated with.

const IS_BASETYPE: bool = false

#[pyclass(subclass)]

const IS_SUBCLASS: bool = false

#[pyclass(extends=…)]

const IS_MAPPING: bool = false

#[pyclass(mapping)]

const IS_SEQUENCE: bool = false

#[pyclass(sequence)]

const IS_IMMUTABLE_TYPE: bool = false

#[pyclass(immutable_type)]

const RAW_DOC: &'static CStr = /// WebSocket client with automatic reconnection. /// /// Handles connection state, callbacks, and rate limiting. /// See module docs for architecture details.

Docstring for the class provided on the struct or enum.

const DOC: &'static CStr

Fully rendered class doc, including the text_signature if a constructor is defined.

type Layout = <<WebSocketClient as PyClassImpl>::BaseNativeType as PyClassBaseType>::Layout<WebSocketClient>

Description of how this class is laid out in memory

type BaseType = PyAny

Base class

type ThreadChecker = NoopThreadChecker

This handles following two situations:

type Inventory = Pyo3MethodsInventoryForWebSocketClient

type PyClassMutability = <<PyAny as PyClassBaseType>::PyClassMutability as PyClassMutability>::MutableChild

Immutable or mutable

type Dict = PyClassDummySlot

Specify this class has #[pyclass(dict)] or not.

type WeakRef = PyClassDummySlot

Specify this class has #[pyclass(weakref)] or not.

type BaseNativeType = PyAny

The closest native ancestor. This is PyAny by default, and when you declare #[pyclass(extends=PyDict)], it’s PyDict.

fn items_iter() -> PyClassItemsIter

fn lazy_type_object() -> &'static LazyTypeObject<Self>

fn dict_offset() -> Option<PyObjectOffset>

Used to provide the dictoffset slot (equivalent to tp_dictoffset)

fn weaklist_offset() -> Option<PyObjectOffset>

Used to provide the weaklistoffset slot (equivalent to tp_weaklistoffset

impl PyStubType for WebSocketClient

fn type_output() -> TypeInfo

The type to be used in the output signature, i.e. return type of the Python function or methods.

fn type_input() -> TypeInfo

The type to be used in the input signature, i.e. the arguments of the Python function or methods.

impl PyTypeInfo for WebSocketClient

const NAME: &str = <Self as ::pyo3::PyClass>::NAME

👎Deprecated since 0.28.0:

prefer using ::type_object(py).name() to get the correct runtime value

Class name.

const MODULE: Option<&str> = <Self as ::pyo3::impl_::pyclass::PyClassImpl>::MODULE

👎Deprecated since 0.28.0:

prefer using ::type_object(py).module() to get the correct runtime value

Module name, if any.

fn type_object_raw(py: Python<'_>) -> *mut PyTypeObject

Returns the PyTypeObject instance for this type.

fn type_object(py: Python<'_>) -> Bound<'_, PyType>

Returns the safe abstraction over the type object.

fn is_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type or a subclass of this type.

fn is_exact_type_of(object: &Bound<'_, PyAny>) -> bool

Checks if object is an instance of this type.

impl DerefToPyAny for WebSocketClient

impl ExtractPyClassWithClone for WebSocketClient