Connection Management

Relevant source files

The following files were used as context for generating this wiki page:

• src/core.rs
• src/commands.rs
• guest-js/index.ts
• src/models.rs
• src/lib.rs
• README.md

Connection Management in the Tauri Centrifugo plugin handles the lifecycle of WebSocket-based communication between the Tauri application and a Centrifugo server. It encompasses initializing connections, managing authentication via JWT tokens, handling protocol selection (JSON or Protobuf), and maintaining the state of active channel subscriptions.

The system is designed with an event-driven architecture, ensuring that the frontend is notified of state transitions such as connecting, connected, or disconnected through Tauri's event emission system. This allows for a reactive user interface that responds to real-time network conditions.

Sources: src/core.rs:1-25, src/lib.rs:1-20, README.md:10-25

Connection Lifecycle

The connection lifecycle is managed by the Centrifugo core struct, which utilizes a dedicated Tokio runtime to handle asynchronous WebSocket operations independently of the main Tauri thread.

Connection Process

When a connection is initiated, the system performs the following steps:

1. Cleanup: Aborts any existing connection tasks to prevent resource leaks.
2. Configuration: Formats the WebSocket URL based on whether Protobuf is enabled.
3. Client Initialization: Creates a new tokio_centrifuge client.
4. Event Binding: Attaches internal listeners to emit Tauri events (e.g., centrifugo:connected).
5. Execution: Spawns a background task to maintain the persistent WebSocket connection.

Sources: src/core.rs:88-120, src/commands.rs:43-55

The following sequence diagram illustrates the flow from a frontend connect call to a successful establishment of the WebSocket link:

Configuration and Data Models

Connections are configured using the StartConfig structure, which defines the parameters for the WebSocket session.

StartConfig Parameters

Parameter	Type	Description
url	String	The WebSocket URL of the Centrifugo server.
token	Option<String>	Optional JWT for authentication.
name	Option<String>	Optional client name identifier.
channels	Vec<String>	List of channels to subscribe to immediately upon connection.
useProtobuf	bool	If true, uses binary Protobuf protocol; otherwise uses JSON.
readTimeout	Option<u64>	Timeout in milliseconds for read operations.

Sources: src/models.rs:45-65, guest-js/index.ts:7-15

Connection States

The system tracks three primary states through the tokio_centrifuge::client::State enum, which are exposed to the frontend as strings:

• disconnected: No active connection.
• connecting: Attempting to establish the WebSocket handshake.
• connected: Active session established and ready for data.

Sources: src/core.rs:355-370, guest-js/index.ts:240-245

Internal State Management

The Centrifugo struct serves as the central state manager, using thread-safe primitives to ensure data consistency across asynchronous tasks.

Thread Safety

• Arc (Atomic Reference Counting): Used to share the runtime and state across thread boundaries.
• Mutex: Protects the optional Client and the subscriptions map, allowing safe mutation from background tasks and foreground commands.
• Abort Handles: The client_task stores a JoinHandle that is used to explicitly abort the background thread when disconnect() is called or a new connection replaces an old one.

Sources: src/core.rs:67-85, src/core.rs:245-265

Authentication and Security

The plugin supports JWT-based authentication. This can be provided during initial connection or updated dynamically during an active session using the set_token command.

// Updating the token dynamically in src/core.rs
pub async fn set_token(&self, token: String) -> Result<()> {
    let client = {
        let client_guard = self.client.lock().unwrap_or_else(|e| e.into_inner());
        client_guard.as_ref().map(|c| c.clone())
    };

    if let Some(client) = client {
        client.set_token(token);
        Ok(())
    } else {
        Err(Error::NotConnected)
    }
}

Sources: src/core.rs:275-300, src/commands.rs:88-95

Updating the token does not require a full reconnection; the internal client updates its credentials for subsequent requests like channel subscriptions or RPC calls.

Sources: src/core.rs:290-295, README.md:120-125

Event Emission Flow

Connection management relies heavily on Tauri's event system to bridge the Rust-JavaScript divide. The following table summarizes the events emitted during connection transitions.

Event Name	Trigger	Payload Type
centrifugo:connecting	Connection attempt begins	ConnectionStatus (Timestamp)
centrifugo:connected	WebSocket successfully opened	ConnectionStatus (Timestamp)
centrifugo:disconnected	Connection closed or lost	ConnectionStatus (Timestamp)
centrifugo:error	Connection or protocol error	ErrorData (String)

Sources: src/core.rs:140-175, guest-js/index.ts:265-285, src/models.rs:175-195

Conclusion

Connection management in the tauri-plugin-centrifugo provides a robust, thread-safe implementation for handling real-time WebSocket sessions. By isolating the connection logic in a dedicated Tokio runtime and using Tauri's event-driven architecture, the plugin ensures that the application remains responsive while maintaining a persistent, authenticated link to the Centrifugo server. This architecture allows for seamless transitions between connection states and supports dynamic configuration updates without service interruption.