Backend Error Handling

Relevant source files

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

• src/error.rs
• src/core.rs
• src/models.rs
• src/lib.rs
• guest-js/index.ts
• examples/tauri-app/src/App.svelte

Backend error handling in the Tauri Centrifugo plugin is designed to provide a type-safe, serialized communication bridge between the Rust core logic and the JavaScript frontend. It centralizes all potential failure points—ranging from connection issues and protocol violations to serialization errors—into a unified Error enum that implements serde::Serialize for seamless cross-process communication.

The system ensures that errors occurring within the asynchronous Tokio runtime are captured and emitted back to the Tauri window via the centrifugo:error event, or returned directly as Result types for synchronous command invocations. Sources: src/error.rs:1-15, src/core.rs:17-25

Error Architecture and Definitions

The core of the error handling system resides in src/error.rs, which utilizes the thiserror crate to define a custom Error enum. This enum categorizes all possible failure states within the plugin.

Centralized Error Enum

The Error enum provides specific variants for different failure domains:

Error Variant	Description	Source Mapping
NotConnected	Attempted operation without an active WebSocket connection.	src/error.rs:31
NotImplemented	Feature requested is not supported by the underlying tokio-centrifuge library.	src/error.rs:35
SerializationError	Failures during JSON encoding or decoding.	src/error.rs:39
CentrifugoError	Errors received directly from the Centrifugo server logic.	src/error.rs:43
Base64Error	Failures during Base64 decoding of incoming/outgoing payloads.	src/error.rs:47
RequestError	General errors arising from tokio-centrifuge client operations.	src/error.rs:51

Sources: src/error.rs:27-52

Error Flow Visualization

The following diagram illustrates how an error propagates from the underlying Rust client through the plugin core to the frontend.

The plugin captures errors from various sources and maps them to a consistent format. Sources: src/core.rs:125-132, src/error.rs:54-70

Implementation Details

Automatic Type Conversions

The plugin implements the From trait for several external error types to automatically wrap them in the local Error enum. This ensures that errors from serde_json, base64, and tokio-centrifuge are handled consistently.

impl From<serde_json::Error> for Error {
    fn from(err: serde_json::Error) -> Self {
        Error::SerializationError(err.to_string())
    }
}

impl From<base64::DecodeError> for Error {
    fn from(err: base64::DecodeError) -> Self {
        Error::Base64Error(err.to_string())
    }
}

Sources: src/error.rs:54-70

Error Data Model

When errors are transmitted to the frontend (especially via events), they use the ErrorData structure to ensure the frontend receives a clear string representation of the issue.

#[derive(Debug, Deserialize, Serialize, Clone)]
#[serde(rename_all = "camelCase")]
pub struct ErrorData {
    pub error: String,
}

Sources: src/models.rs:159-164

Event-Based Error Reporting

In addition to returning errors from commands, the Centrifugo core manages a background task that listens for connection-level errors. When the underlying tokio-centrifuge client encounters a protocol or connection error, the plugin emits a centrifugo:error event.

Connection Error Handling Logic

Within src/core.rs, an error callback is registered during the client setup:

let app_clone = app.clone();
cf_client.on_error(move |err| {
    let _ = app_clone.emit(
        "centrifugo:error",
        serde_json::json!({"error": format!("{:?}", err)}),
    );
});

Sources: src/core.rs:125-132

Frontend Consumption

The JavaScript API provides an onError helper that allows developers to subscribe to these backend-emitted errors.

export const onError = async (callback: (data: TauriEventWrapper<ErrorData>) => void): Promise<UnlistenFn> => 
  await onCentrifugoEvent('error', callback)

Sources: guest-js/index.ts:192-193

Summary of Error-Prone Operations

The following table identifies key operations and the specific errors they are likely to trigger:

Operation	Possible Errors	Logic Source
publish	NotConnected, Base64Error, RequestError	src/core.rs:265-288
rpc	NotConnected, Base64Error, RequestError	src/core.rs:439-458
add_subscription	NotConnected, RequestError	src/core.rs:364-411
set_token	NotConnected	src/core.rs:237-252
presence/history	NotImplemented	src/core.rs:460-475

Sources: src/core.rs:237-475

Backend error handling ensures that even in a multi-threaded, asynchronous environment, the state of the Centrifugo connection remains transparent to the developer, providing actionable feedback for connection failures or unsupported operations. Sources: src/error.rs:1-10, examples/tauri-app/src/App.svelte:92-97