Tauri Plugin Architecture

Relevant source files

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

• src/lib.rs
• README.md
• src/models.rs
• examples/tauri-app/src/App.svelte
• permissions/schemas/schema.json
• package.json

The Tauri Plugin Centrifugo is designed to provide real-time, bidirectional communication between a Tauri desktop/mobile application and a Centrifugo server. It leverages the tokio-centrifuge Rust library to handle low-level WebSocket connections and protocol management (JSON or Protobuf), while exposing a simplified command-based interface and event-driven system to the frontend.

The architecture follows the standard Tauri plugin pattern, consisting of a Rust backend that manages the persistent connection state and a JavaScript/TypeScript "guest" API that facilitates communication through Tauri's IPC (Inter-Process Communication) layer.

Sources: src/lib.rs:1-15, README.md:10-18

Core Backend Structure

The backend is implemented in Rust and is divided into functional modules that handle command routing, state management, and data modeling.

Plugin Initialization and State

The plugin is initialized via the init() function, which registers command handlers and sets up the internal state management. The core::Centrifugo state is managed by Tauri's state management system, allowing it to persist across different command invocations.

The diagram shows the lifecycle of the plugin initialization during the Tauri application startup.
Sources: src/lib.rs:77-104

Data Models and Serialization

The plugin uses a set of strongly typed Rust structures to handle requests and responses. These models use serde with the camelCase naming convention to ensure compatibility with JavaScript standards.

Model	Purpose	Key Fields
StartConfig	Connection parameters	url, token, channels, useProtobuf
PublishRequest	Sending messages	channel, data (base64)
RpcRequest	RPC execution	method, data (base64)
PublicationData	Incoming messages	channel, data, timestamp

Sources: src/models.rs:1-215

Command and IPC Layer

The plugin exposes a series of commands that the frontend calls via the invoke system. These commands are the primary interface for controlling the Centrifugo client.

Command Workflow

When a frontend component calls a function like connect, the following sequence occurs:

The sequence diagram illustrates how synchronous commands and asynchronous events flow through the Tauri IPC layer.
Sources: src/lib.rs:80-97, README.md:144-152, examples/tauri-app/src/App.svelte:115-135

Available Commands

The plugin registers 17 distinct commands to provide full control over the connection:

• Connection Control: connect, disconnect, is_connected, get_connection_state
• Messaging: publish, send, rpc
• Sub Management: add_subscription, remove_subscription, get_subscriptions
• Server Info: presence, presence_stats, history, ping
• Auth: set_token, refresh, sub_refresh

Sources: src/lib.rs:81-97, permissions/schemas/schema.json:200-340

Event-Driven Architecture

The plugin utilizes Tauri's event system to push real-time updates from the Rust background task to the frontend. This prevents the frontend from needing to poll for new messages or connection status changes.

Event Distribution

Events are wrapped in a standard structure on the frontend to provide consistent access to payloads.

Event Name	Trigger	Payload Type
centrifugo://connecting	Start of connection attempt	ConnectionStatus
centrifugo://connected	WebSocket successfully opened	ConnectionStatus
centrifugo://publication	Message received on a channel	PublicationData
centrifugo://error	Connection or protocol error	ErrorData
centrifugo://subscribed	Channel subscription confirmed	ChannelStatus

Sources: README.md:162-178, src/models.rs:145-165, examples/tauri-app/src/App.svelte:78-144

Security and Permissions

Access to plugin commands is restricted by Tauri's permission system. Developers must explicitly allow commands in their capabilities configuration.

Permission Scema

The plugin defines a comprehensive set of permissions in its schema. The default permission set includes all core functionalities required for a standard real-time application.

{
  "identifier": "default",
  "permissions": [
    "allow-connect",
    "allow-disconnect",
    "allow-publish",
    "allow-rpc",
    "allow-add-subscription"
  ]
}

Sources: permissions/schemas/schema.json:341-360, README.md:280-295

Frontend Integration

The TypeScript API (tauri-plugin-centrifugo-api) provides a high-level wrapper around the IPC calls and event listeners.

Helper and Utility Modules

The frontend API is split into:

1. Core Functions: Direct mapping to Rust commands (e.g., connect()).
2. Helpers: Simplified JSON handling, such as helpers.publishJson() which automatically handles base64 encoding/decoding.
3. Utils: Base64 encoding/decoding logic for raw data transmission.

Sources: package.json:1-15, README.md:144-160, examples/tauri-app/src/App.svelte:13-35

Example Data Flow (Publishing JSON)

1. Frontend calls helpers.publishJson('my-chan', { msg: 'hi' }).
2. The helper converts the object to a JSON string and encodes it to base64.
3. The encoded string is sent via the publish command to Rust.
4. Rust decodes the base64 and forwards the raw bytes to Centrifugo via the tokio-centrifuge client.

Sources: README.md:65-75, examples/tauri-app/src/App.svelte:253-270