Backend Command Handlers

Relevant source files

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

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

Backend Command Handlers in the Tauri Centrifugo plugin serve as the bridge between the frontend JavaScript/TypeScript API and the underlying Rust tokio-centrifuge implementation. These handlers facilitate real-time communication, channel management, and server interaction by exposing secure IPC (Inter-Process Communication) endpoints that the frontend can invoke.

The command system is structured to handle asynchronous WebSocket operations, including connection lifecycle management, message publishing, and RPC execution. Each command is mapped to a specific permission within the Tauri security framework, ensuring that only authorized frontend components can trigger sensitive operations like publishing messages or retrieving channel history.

Sources: src/lib.rs:26-31, README.md:164-173

Architecture and Command Registration

The plugin initializes its command handlers during the Tauri builder phase. The init function registers 17 distinct commands that cover the full spectrum of Centrifugo client capabilities.

The diagram above illustrates the request flow from the frontend API through the backend command handlers to the core logic and finally to the Centrifugo server.

The command handlers are registered using tauri::generate_handler!. During the setup phase, the backend also manages the global state for the Centrifugo client using app.manage(core::Centrifugo::new()).

Sources: src/lib.rs:75-103

Connection Management Commands

These commands handle the establishment and termination of the WebSocket connection with the Centrifugo server. They rely on the StartConfig model for initialization parameters.

Command	Data Model	Description
connect	StartConfig	Establishes a WebSocket connection with specified URL, token, and protocol.
disconnect	N/A	Gracefully closes the active connection.
is_connected	N/A	Returns a boolean indicating the current connection status.
get_connection_state	N/A	Returns the detailed internal state of the client.

Sources: src/lib.rs:80-97, src/models.rs:43-58

Connection Configuration Flow

When connect is invoked, the backend processes the StartConfig which includes the WebSocket URL, optional JWT tokens, and protocol preferences (JSON vs Protobuf).

Messaging and Channel Interaction

The plugin provides commands for interacting with specific channels. Data sent through these commands is typically expected to be base64-encoded to ensure safe transmission of arbitrary binary or string data.

Channel Operations

• Publishing: The publish command uses the PublishRequest model to send data to a specific channel.
• Presence: presence and presence_stats retrieve information about active clients and unique users in a specific channel.
• History: history allows retrieval of historical messages based on limits and pagination tokens (since).

Message Data Models

Field	Type	Description
channel	String	The target Centrifugo channel name.
data	String	Base64-encoded message content.
limit	Option<u32>	(History only) Max messages to retrieve.
reverse	Option<bool>	(History only) Whether to sort newest first.

Sources: src/models.rs:74-81, src/models.rs:113-124, permissions/schemas/schema.json:442-452

Remote Procedure Calls (RPC) and Authentication

The backend handles RPC requests and authentication token updates dynamically without requiring a connection restart.

RPC Execution

The rpc command takes an RpcRequest containing a method name and base64-encoded parameters. It returns an RpcResponse which includes the execution results and a server timestamp.

Token Management

Handlers like set_token, refresh, and sub_refresh allow the frontend to update JWT tokens. sub_refresh specifically targets tokens for individual private channel subscriptions using the SubRefreshRequest model.

Sources: src/models.rs:141-158, src/lib.rs:82-93

Permission and Security Scopes

Each command handler is governed by the Tauri permission system. The plugin defines a default permission set that grants access to all core operations.

Permission Mapping

Permission Identifier	Associated Commands
allow-connect	connect
allow-publish	publish
allow-rpc	rpc
allow-history	history
allow-add-subscription	add_subscription

Individual commands can be explicitly denied using the deny- prefix in the capability configuration.

Sources: permissions/schemas/schema.json:344-428, examples/tauri-app/src-tauri/gen/schemas/desktop-schema.json:207-226

Conclusion

Backend Command Handlers in the Centrifugo plugin provide a structured API for real-time features. By abstracting complex WebSocket state management into discrete Rust commands, the plugin ensures that the frontend remains focused on data presentation while the backend handles the technical requirements of the Centrifugo protocol, base64 encoding/decoding, and secure IPC communication.