Struct ClientRunner 

pub struct ClientRunner<S: AppState> { /* private fields */ }

Implementation of the ClientRunner for managing WebSocket client connections and session lifecycle.

Type Parameters

• S: The application state type, which must implement the AppState trait.

Methods

new

Constructs a new ClientRunner instance.

Arguments

• connector: An Arc to a type implementing the Connector trait, responsible for establishing connections.
• state: An Arc to the application state.
• router: An Arc to the message Router.
• to_ws_sender: An asynchronous sender for outgoing WebSocket messages.
• to_ws_receiver: An asynchronous receiver for outgoing WebSocket messages.
• runner_command_rx: An asynchronous receiver for runner commands (e.g., disconnect, shutdown).
• connection_callback: Callbacks to execute on connect and reconnect events.

run

Asynchronously runs the main client loop, managing connection cycles, message routing, and command handling.

• Continuously attempts to connect or reconnect to the WebSocket server until a shutdown is requested.
• On successful connection, executes the appropriate connection callback (on_connect or on_reconnect).
• Spawns writer and reader tasks for handling outgoing and incoming WebSocket messages.
• Listens for runner commands (e.g., disconnect, shutdown) and manages session state accordingly.
• Handles unexpected connection loss and retries connection as needed.
• Cleans up resources and tasks on disconnect or shutdown.

Behavior

• Uses a hard connect or reconnect based on the internal state.
• Retries connection attempts with a delay on failure.
• Ensures proper cleanup of tasks and state on disconnect or shutdown.
• Prints status messages for key events and errors.

Implementations

impl<S: AppState> ClientRunner<S>

pub async fn run(&mut self)

Main client runner loop that manages WebSocket connections and message processing.

Middleware Integration Points

This method integrates middleware at four key points:

1. Connection Establishment (on_connect): Called after successful connection
2. Message Sending (on_send): Called before each message is sent to WebSocket
3. Message Receiving (on_receive): Called for each incoming message (in Router::route)
4. Disconnection (on_disconnect): Called on manual disconnect, shutdown, or connection loss

Connection Lifecycle

• Connection: Middleware on_connect is called after successful WebSocket connection
• Active Session: Middleware on_send/on_receive called for each message
• Disconnection: Middleware on_disconnect called before cleanup

Examples found in repository

examples/echo_client.rs (line 306)

    pub async fn new(url: String) -> CoreResult<Self> {
        // Use a simple connector (implement your own if needed)
        let connector = DummyConnector::new(url);

        let mut builder = ClientBuilder::new(connector, ());
        builder =
            builder.with_lightweight_handler(|msg, state, _| Box::pin(print_handler(msg, state)));
        let (client, mut runner) = builder
            .with_module::<EchoModule>()
            .with_module::<StreamModule>()
            .with_module::<PeriodicSenderModule>()
            .build()
            .await?;

        // let echo_handle = client.get_handle::<EchoModule>().await.unwrap();
        // let stream_handle = client.get_handle::<StreamModule>().await.unwrap();

        // Start runner in background
        let _runner = tokio::spawn(async move { runner.run().await });

        Ok(Self { client, _runner })
    }