Event Data Structures and Types

Relevant source files

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

• guest-js/index.ts
• src/models.rs
• README.md
• examples/tauri-app/src/App.svelte
• permissions/schemas/schema.json
• examples/server/proto/api.proto

The "Event Data Structures and Types" within the Tauri Centrifugo plugin define the contractual interface between the Rust backend, the JavaScript guest API, and the Centrifugo server. This system enables real-time, event-driven communication by standardizing how connection states, channel subscriptions, and message publications are serialized and transmitted across the Tauri bridge.

The architecture relies on a set of core TypeScript interfaces and Rust structs that share a common naming convention (camelCase for frontend compatibility) to ensure type safety. These structures cover the entire lifecycle of a Centrifugo session, from initial handshake configuration to asynchronous message handling and error reporting.

Core Communication Lifecycle

The communication flow is initiated by a StartConfig, which transitions the client through various connection states. As events occur on the Centrifugo server, the Rust backend emits specific event payloads to the frontend.

Connection and Lifecycle Flow

This diagram illustrates the progression from configuration to active event listening.

Data Models and Structures

The plugin defines specific structures for requests (commands sent to the plugin) and responses/events (data received from the plugin).

Request Structures

These structures are used when invoking plugin commands from the frontend.

Interface / Struct	Field	Type	Description
StartConfig	url	string	The WebSocket URL for the Centrifugo server.
	token	string?	Optional JWT for authentication.
	channels	string[]	Initial list of channels to join.
	useProtobuf	boolean	Flag to use Protobuf instead of JSON.
PublishRequest	channel	string	Target channel for the message.
	data	string	Base64-encoded message content.
RpcRequest	method	string	Name of the RPC method to execute.
	data	string	Base64-encoded parameters.

Sources: guest-js/index.ts:7-43, src/models.rs:43-98

Event and Response Payloads

When the plugin emits events via the Tauri listen mechanism, it wraps data in a TauriEventWrapper.

export interface TauriEventWrapper<T> {
  event: string;
  payload: T;
  id: number;
}

Sources: guest-js/index.ts:73-77

The following table describes the internal payload types (T) used in these wrappers:

Payload Type	Fields	Description
ConnectionStatus	ts: number	Unix timestamp of the connection state change.
ChannelStatus	channel: string	Information regarding a specific channel (e.g., subscribing).
PublicationData	channel: string, data: string	Contains the channel name and base64-encoded message data.
ErrorData	error: string	Contains the error message/description.

Sources: guest-js/index.ts:60-71, src/models.rs:149-183

Event Types and Listeners

The plugin provides a high-level API for attaching listeners to specific Centrifugo events. These are prefixed with centrifugo: in the Tauri event system.

Listener Mapping

The guest-js implementation maps specific string identifiers to typed callback functions.

Implementation Detail: Publication Handling

When a publication event is received, the plugin often provides helpers to automatically decode the data if it is JSON-formatted.

export const onMessage = async (callback: (data: { channel: string; data: any }) => void): Promise<UnlistenFn> => 
  await onCentrifugoEvent('publication', (pubData: TauriEventWrapper<PublicationData>) => {
    try {
      const decodedData = utils.decodeJson(pubData.payload.data)
      callback({
        channel: pubData.payload.channel,
        data: decodedData
      })
    } catch (error) {
      // Fallback to raw data if JSON decoding fails
      callback({
        channel: pubData.payload.channel,
        data: pubData.payload.data
      })
    }
  })

Sources: guest-js/index.ts:187-203

Permission Scopes and Command Identifiers

The system's security and command routing are governed by a schema that defines valid operations. These identifiers are used both in the Rust invoke handlers and the Tauri permission system.

Allowed Commands

The following command identifiers represent the valid event-triggering operations:

• connect, disconnect
• publish, rpc
• presence, presence_stats
• history
• add_subscription, remove_subscription
• ping, set_token, refresh

Sources: permissions/schemas/schema.json:208-468, guest-js/index.ts:114-158

Protocol Specifics (JSON vs Protobuf)

While the plugin supports both protocols, the data structures in the src/models.rs and guest-js/index.ts remain consistent by using base64 strings for the data fields. This abstraction allows the application layer to treat messages as generic payloads regardless of the underlying transport format (JSON or Protobuf).

API Protobuf Structure

The underlying Centrifugo API utilizes a more complex Protobuf definition for internal server operations, including PublishRequest, SubscribeRequest, and BroadcastRequest. The plugin maps the simplified StartConfig and PublishRequest from the frontend to these more granular server-side commands.

Sources: examples/server/proto/api.proto:89-130, src/models.rs:43-98

Summary

The event data structures and types in the Tauri Centrifugo plugin provide a robust framework for real-time messaging. By utilizing strictly typed interfaces in TypeScript and corresponding serializable structs in Rust, the plugin ensures that developers can handle complex WebSocket interactions—such as channel publications and connection lifecycle events—with high reliability and minimal manual data parsing.