Introduction and Features
Relevant source files
The following files were used as context for generating this wiki page:
The Tauri Plugin Centrifugo is a specialized extension for the Tauri framework designed to enable real-time, bidirectional communication between a Tauri desktop/mobile application and a Centrifugo server. By leveraging the tokio-centrifuge Rust library, the plugin provides a robust bridge between the frontend JavaScript/TypeScript environment and the high-performance asynchronous capabilities of the Rust backend.
This system is built with an event-driven architecture that allows developers to handle connection states, manage channel subscriptions, and process real-time message publications with minimal overhead. The plugin supports both JSON and Protobuf protocols, ensuring flexibility for different data serialization requirements and performance needs.
Sources: README.md:12-20, src/lib.rs:1-12, package.json:4-15
Core Features
The plugin provides a comprehensive suite of tools for real-time application development:
- Real-time Communication: Persistent WebSocket-based connectivity with the Centrifugo server.
- Protocol Flexibility: Native support for both JSON and Protobuf serialization protocols.
- Event-driven Architecture: A built-in system for broadcasting connection states (Connecting, Connected, Disconnected, Error) and data publications from the Rust core to the frontend.
- Channel Management: Dynamic subscription and unsubscription capabilities that allow for granular message filtering.
- Secure Authentication: Integrated support for JWT (JSON Web Token) for secure client authentication and channel-specific authorization.
- Cross-platform Compatibility: Support for Linux, Windows, macOS, Android, and iOS.
Sources: README.md:22-30, CHANGELOG.md:8-16, src/lib.rs:5-12
Feature Comparison Matrix
| Feature | Description | Support Status |
|---|---|---|
| WebSocket | Core transport for real-time messaging | Fully Supported |
| JSON Protocol | Human-readable data interchange | Fully Supported |
| Protobuf | Binary serialization for performance | Fully Supported |
| Channel Subscription | Dynamically join/leave messaging topics | Fully Supported |
| RPC Calls | Execute remote procedures on the server | Fully Supported |
| Presence | Client list for a channel | Partial (Rust implementation present) |
| History | Message retrieval from channel history | Partial (Rust implementation present) |
Sources: README.md:22-30, README.md:213-228, src/lib.rs:88-105
Architecture and Data Flow
The plugin architecture is divided into three primary layers: the Frontend API (JavaScript/TypeScript), the Rust Command Layer (Bridge), and the Core Logic.
The diagram shows the bidirectional flow between the Tauri frontend and the external Centrifugo server mediated by the Rust plugin.
Sources: src/lib.rs:17-22, src/lib.rs:108-111, README.md:43-55
Data Flow for Connection
When a connection is initiated, the StartConfig object is passed from the frontend to the Rust backend. The plugin then initializes the tokio-centrifuge client and establishes a WebSocket connection.
The sequence diagram illustrates the lifecycle of establishing a connection through the plugin.
Sources: src/models.rs:43-61, src/lib.rs:108-111, README.md:58-71
Key Components and Models
Configuration (StartConfig)
The StartConfig structure is the primary configuration object used to establish a connection. It dictates the protocol, authentication, and initial channel subscriptions.
| Field | Type | Description |
|---|---|---|
url | String | WebSocket URL for the Centrifugo server. |
token | Option<String> | JWT authentication token for secure sessions. |
name | Option<String> | Client name identifier for server-side tracking. |
channels | Vec<String> | List of channels to join immediately upon connection. |
useProtobuf | bool | Toggle between JSON and Protobuf protocols. |
readTimeout | Option<u64> | Timeout in milliseconds for read operations. |
Sources: src/models.rs:43-61, README.md:241-251
Command API
The plugin exposes several Rust commands that are accessible via the Tauri invoke system. These commands manage the lifecycle of the connection and interactions with the server.
// In src/lib.rs:88-105
.invoke_handler(tauri::generate_handler![
commands::connect,
commands::disconnect,
commands::set_token,
commands::publish,
commands::rpc,
commands::presence,
commands::presence_stats,
commands::history,
commands::send,
commands::refresh,
commands::sub_refresh,
commands::ping,
commands::is_connected,
commands::get_subscriptions,
commands::get_connection_state,
commands::add_subscription,
commands::remove_subscription,
])
Sources: src/lib.rs:88-105
Permissions System
The plugin follows Tauri's security model, requiring explicit permission grants for access to its commands. By default, all commands are blocked until enabled in the application's capabilities configuration.
Default Permission Set
The centrifugo:default permission provides a sensible baseline for standard application usage, enabling the most common real-time messaging functions.
| Permission Identifier | Enabled Commands |
|---|---|
allow-connect | connect |
allow-disconnect | disconnect |
allow-publish | publish |
allow-rpc | rpc |
allow-add-subscription | add_subscription |
allow-remove-subscription | remove_subscription |
allow-is-connected | is_connected |
Sources: permissions/schemas/schema.json:421-443, README.md:415-425
Conclusion
The Tauri Plugin Centrifugo provides a powerful, type-safe interface for integrating real-time features into Tauri applications. By abstracting the complexities of WebSocket management and protocol serialization into a clean Rust backend and JavaScript frontend API, it allows developers to focus on application logic while ensuring performance and cross-platform reliability.