Event Listeners Reference

Relevant source files

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

• guest-js/index.ts
• README.md
• src/lib.rs
• examples/tauri-app/src/App.svelte
• CHANGELOG.md

The Tauri Plugin Centrifugo utilizes an event-driven architecture to facilitate real-time communication between the Rust backend and the JavaScript frontend. This system allows developers to react to connection state changes, subscription updates, and incoming message publications via WebSocket.

The plugin emits specific events prefixed with centrifugo:, which are handled through a dedicated API in the guest-js layer. This ensures that frontend applications stay synchronized with the underlying Centrifugo client state maintained in the Rust core.

Sources: src/lib.rs:16-19, guest-js/index.ts:168-173, README.md:15-19

Event Architecture

The event system flows from the Centrifugo server through the Rust backend plugin, which then emits Tauri events to the frontend. The guest-js API provides typed wrappers for these events to simplify listener registration.

Data Flow Model

The following diagram illustrates how an event originating from the server reaches the frontend application.

The plugin uses tauri::plugin::Builder to manage state and provides command handlers that trigger these flows.
Sources: src/lib.rs:90-112, guest-js/index.ts:168-173

Connection Events

These listeners monitor the lifecycle of the WebSocket connection to the Centrifugo server. They provide feedback on the current connectivity status and any errors encountered during the connection process.

Primary Connection Listeners

Function	Event Name	Description
onConnecting	centrifugo:connecting	Triggered when a connection attempt starts.
onConnected	centrifugo:connected	Triggered when the WebSocket connection is established.
onDisconnected	centrifugo:disconnected	Triggered when the connection is closed.
onError	centrifugo:error	Triggered when a connection or protocol error occurs.

Sources: guest-js/index.ts:175-186, README.md:144-154

Connection Event Payloads

All connection events (except errors) use the ConnectionStatus interface, while errors use ErrorData.

export interface ConnectionStatus {
  ts: number; // Timestamp of the event
}

export interface ErrorData {
  error: string; // Error message description
}

Sources: guest-js/index.ts:58-60, guest-js/index.ts:66-68

Subscription Events

Subscription events manage the state of specific channels. The plugin notifies the frontend when a subscription is being attempted, has succeeded, or has been removed.

Subscription Lifecycle Flow

This sequence shows the typical progression of events when a user adds a subscription.

Subscription Listeners Reference

Function	Event Name	Payload Type
onSubscribing	centrifugo:subscribing	ChannelStatus
onSubscribed	centrifugo:subscribed	ChannelStatus
onUnsubscribed	centrifugo:unsubscribed	ChannelStatus

The ChannelStatus interface simply contains the channel: string identifying the target of the event.
Sources: guest-js/index.ts:62-64, guest-js/index.ts:188-195

Message & Publication Events

Publications are the primary way data is received from Centrifugo channels. The plugin provides several levels of abstraction for handling these messages, from raw base64 data to automatically decoded JSON objects.

Publication Handling

The onPublication listener returns the raw PublicationData, which includes the channel and the base64 encoded data string.

export interface PublicationData {
  channel: string;
  data: string; // base64 encoded string
}

Sources: guest-js/index.ts:53-56, guest-js/index.ts:197-198

Convenience Listeners

The API provides high-level helpers that handle decoding and filtering automatically:

• onMessage: Listens to all publications and attempts to decode the data as JSON. If decoding fails, it returns the raw string.
• onChannelMessage: Filters publications for a specific channel and returns the decoded data directly to the callback.
• onAnyMessage: Similar to onMessage but adds a local timestamp to the payload.

// Example: Listening to a specific chat channel
const unlisten = await onChannelMessage('chat', (data) => {
  console.log('Received message:', data.text);
});

Sources: guest-js/index.ts:201-237, README.md:155-158

Event Wrapper Structure

Every event received from the Rust backend is wrapped in a standard TauriEventWrapper. This ensures consistency across all types of notifications.

Field	Type	Description
event	string	The full event name (e.g., "centrifugo:publication").
payload	T	The event-specific data (e.g., PublicationData).
id	number	A unique identifier for the specific event instance.

Sources: guest-js/index.ts:71-75, README.md:308-312

Summary

The event listener system in tauri-plugin-centrifugo provides a comprehensive way to build reactive real-time applications. By separating connection lifecycle, subscription state, and data publications into distinct, typed events, the plugin allows for granular control over the application's real-time behavior. Developers should utilize the helpers and convenience listeners (like onChannelMessage) to reduce boilerplate code associated with base64 decoding and channel filtering.

Sources: guest-js/index.ts:241-300, CHANGELOG.md:8-15