Tauri Plugin Centrifugo

A Tauri plugin for real-time communication with Centrifugo server using the tokio-centrifuge library.

Features

• Real-time Communication: WebSocket-based communication with Centrifugo
• JSON & Protobuf Support: Choose between JSON and Protobuf protocols
• Event-driven Architecture: Comprehensive event system for connection state and messages
• Channel Management: Subscribe/unsubscribe to channels dynamically
• Authentication: JWT token support for secure connections
• Cross-platform: Works on desktop and mobile platforms

Installation

Automatic Installation (Recommended)

Use the Tauri CLI to automatically install both the Rust and JavaScript parts of the plugin:

# npm
npm run tauri add centrifugo

# yarn  
yarn run tauri add centrifugo

# pnpm
pnpm tauri add centrifugo

# deno
deno task tauri add centrifugo

# bun
bun tauri add centrifugo

# cargo
cargo tauri add centrifugo

Manual Installation

Backend (Rust)

Add the plugin using cargo:

cd ./src-tauri
cargo add tauri-plugin-centrifugo

Frontend (JavaScript/TypeScript)

Install the JavaScript API:

npm install tauri-plugin-centrifugo-api
# or
pnpm add tauri-plugin-centrifugo-api

Platform Compatibility

| Platform | Supported | | -------- | --------- | | Linux | ✓ | | Windows | ✓ | | macOS | ✓ | | Android | ✓ | | iOS | ✓ |

Usage

Backend Setup

Initialize the plugin in your Tauri app:

fn main() {
    tauri::Builder::default()
        .plugin(tauri_plugin_centrifugo::init;())
        .run(tauri::generate_context!())
        .expect("error while running tauri application");
}

Frontend API

Basic Connection

import { connect, disconnect, isConnected } from 'tauri-plugin-centrifugo-api'

// Connect to Centrifugo server
await connect({
  url: 'ws://localhost:8000/connection/websocket',
  token: 'your-jwt-token', // optional
  name: 'client-name',
  channels: ['channel1', 'channel2'],
  useProtobuf: false,
  readTimeout: 5000
})

// Check connection status
const connected = await isConnected()

// Disconnect
await disconnect()

Publishing Messages

import { helpers } from 'tauri-plugin-centrifugo-api'

// Publish JSON message
await helpers.publishJson('channel-name', {
  message: 'Hello World',
  timestamp: Date.now()
})

// Publish raw data (base64 encoded)
await publish('channel-name', 'base64-encoded-data')

RPC Calls

import { helpers } from 'tauri-plugin-centrifugo-api'

// Execute RPC with JSON data
const result = await helpers.rpcJson('method-name', {
  userId: 123,
  action: 'getInfo'
})

// Execute RPC with raw data
const result = await rpc('method-name', 'base64-encoded-data')

Event Listeners

import { 
  onConnecting, 
  onConnected, 
  onDisconnected, 
  onPublication,
  onSubscribed,
  onUnsubscribed 
} from 'tauri-plugin-centrifugo-api'

// Listen to connection events
const unlistenConnecting = await onConnecting((eventData) => {
  console.log('Connecting...', eventData.payload)
})

const unlistenConnected = await onConnected((eventData) => {
  console.log('Connected!', eventData.payload)
})

const unlistenDisconnected = await onDisconnected((eventData) => {
  console.log('Disconnected:', eventData.payload)
})

// Listen to publications
const unlistenPublication = await onPublication((eventData) => {
  const { channel, data } = eventData.payload
  console.log(`Message on ${channel}:`, data)
})

// Listen to subscription events
const unlistenSubscribed = await onSubscribed((eventData) => {
  console.log('Subscribed to:', eventData.payload.channel)
})

const unlistenUnsubscribed = await onUnsubscribed((eventData) => {
  console.log('Unsubscribed from:', eventData.payload.channel)
})

// Clean up listeners
unlistenConnecting()
unlistenConnected()
unlistenDisconnected()
unlistenPublication()
unlistenSubscribed()
unlistenUnsubscribed()

Channel Management

import { 
  addSubscription, 
  removeSubscription, 
  getSubscriptions 
} from 'tauri-plugin-centrifugo-api'

// Add new subscription
await addSubscription('new-channel')

// Remove subscription
await removeSubscription('channel-name')

// Get all subscriptions
const subscriptions = await getSubscriptions()

Utility Functions

import { utils } from 'tauri-plugin-centrifugo-api'

// Encode data to base64
const encoded = utils.encode('Hello World')

// Decode base64 data
const decoded = utils.decode('SGVsbG8gV29ybGQ=')

// Encode JSON to base64
const jsonEncoded = utils.encodeJson({ message: 'Hello' })

// Decode base64 JSON
const jsonDecoded = utils.decodeJson(jsonEncoded)

Backend Commands

You can also call Centrifugo commands directly from your Rust backend:

use tauri_plugin_centrifugo::{models::StartConfig, commands::connect};

#[tauri::command]
async fn start_backend_sockets(window: tauri::Window) -> Result<String, String> {
    let config = StartConfig {
        url: "ws://localhost:8000/connection/websocket".to_string(),
        token: None,
        name: Some("backend-client".to_string()),
        version: Some("1.0.0".to_string()),
        channels: vec!["backend".to_string()],
        use_protobuf: false,
        read_timeout: Some(5000),
    };
    
    match connect(window, config).await {
        Ok(_) => Ok("Backend sockets started successfully".to_string()),
        Err(e) => Err(format!("Failed to start backend sockets: {}", e))
    }
}

// Register the command
.invoke_handler(tauri::generate_handler![start_backend_sockets])

Then call it from frontend:

import { invoke } from '@tauri-apps/api/core'

const result = await invoke<string>('start_backend_sockets')
console.log(result) // "Backend sockets started successfully"

API Reference

Core Functions

| Function | Description | Parameters | Returns | |----------|-------------|------------|---------| | connect | Establish connection to Centrifugo | StartConfig | Promise<void> | | disconnect | Close connection | - | Promise<void> | | setToken | Set authentication token | string | Promise<void> | | publish | Publish message to channel | channel: string, data: string | Promise<void> | | rpc | Execute RPC call | method: string, data: string | Promise<any> |

Helper Functions

| Function | Description | Parameters | Returns | |----------|-------------|------------|---------| | helpers.publishJson | Publish JSON data | channel: string, data: any | Promise<void> | | helpers.rpcJson | Execute RPC with JSON | method: string, data: any | Promise<any> | | helpers.subscribeToChannel | Subscribe to channel with message listener | channel: string, callback: Function | Promise<UnlistenFn> | | helpers.subscribeToChannels | Subscribe to multiple channels | channels: string[], callback: Function | Promise<UnlistenFn[]> | | helpers.waitForConnection | Wait for connection with timeout | timeout?: number | Promise<boolean> | | helpers.getConnectionStatus | Get connection status with retry | retries?: number | Promise<string> |

Event Listeners

| Function | Description | Callback Parameter | |----------|-------------|-------------------| | onConnecting | Connection attempt started | TauriEventWrapper<ConnectionStatus> | | onConnected | Connection established | TauriEventWrapper<ConnectionStatus> | | onDisconnected | Connection closed | TauriEventWrapper<ConnectionStatus> | | onError | Connection error | TauriEventWrapper<ErrorData> | | onSubscribed | Channel subscription successful | TauriEventWrapper<ChannelStatus> | | onUnsubscribed | Channel unsubscription successful | TauriEventWrapper<ChannelStatus> | | onSubscribing | Channel subscription attempt | TauriEventWrapper<ChannelStatus> | | onPublication | Message received on channel | TauriEventWrapper<PublicationData> | | onMessage | Decoded message with channel info | { channel: string, data: any } | | onChannelMessage | Decoded message for specific channel | any | | onAnyMessage | Decoded message with timestamp | { channel: string, data: any, timestamp: number } |

Utility Functions

| Function | Description | Parameters | Returns | |----------|-------------|------------|---------| | utils.encode | Encode string to base64 | string | string | | utils.decode | Decode base64 to string | string | string | | utils.encodeJson | Encode object to base64 | any | string | | utils.decodeJson | Decode base64 to object | string | any |

Status Functions

| Function | Description | Returns | |----------|-------------|---------| | isConnected | Check connection status | Promise<boolean> | | getConnectionState | Get detailed connection state | Promise<string> | | getSubscriptions | Get current subscriptions | Promise<Record<string, boolean>> |

Advanced Functions (NotImplemented)

| Function | Description | Status | |----------|-------------|---------| | presence | Get presence information for channel | NotImplemented | | presenceStats | Get presence statistics for channel | NotImplemented | | history | Get message history for channel | NotImplemented | | send | Send message to server | NotImplemented | | refresh | Refresh authentication token | NotImplemented | | subRefresh | Refresh subscription token | NotImplemented | | ping | Ping server | NotImplemented |

Configuration

StartConfig

interface StartConfig {
  url: string                    // WebSocket URL
  token?: string                 // JWT authentication token
  name?: string                  // Client name
  version?: string               // Client version
  channels: string[]             // Channels to subscribe to
  useProtobuf: boolean           // Use Protobuf protocol
  readTimeout?: number           // Read timeout in milliseconds
}

Request Interfaces

interface PublishRequest {
  channel: string
  data: string                   // base64 encoded data
}

interface RpcRequest {
  method: string
  data: string                   // base64 encoded data
}

interface PresenceRequest {
  channel: string
}

interface PresenceStatsRequest {
  channel: string
}

interface HistoryRequest {
  channel: string
  limit?: number
  since?: string
  reverse?: boolean
}

interface SendRequest {
  data: string                   // base64 encoded data
}

interface RefreshRequest {
  token: string
}

interface SubRefreshRequest {
  channel: string
  token: string
}

Response Interfaces

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

interface ConnectionStatus {
  ts: number
}

interface ChannelStatus {
  channel: string
}

interface ErrorData {
  error: string
}

interface RpcResponse {
  method: string
  data: string                   // base64 encoded data
  timestamp: number
}

interface PresenceResponse {
  channel: string
  clients: string[]
  timestamp: number
}

interface PresenceStatsResponse {
  channel: string
  numClients: number
  numUsers: number
  timestamp: number
}

interface HistoryResponse {
  channel: string
  publications: PublicationData[]
  timestamp: number
}

interface PingResponse {
  timestamp: number
}

Event Data Structure

All events use the TauriEventWrapper structure:

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

Advanced Usage Examples

Message Handling with Decoded Data

import { onMessage, onChannelMessage, onAnyMessage } from 'tauri-plugin-centrifugo-api'

// Listen to all messages with automatic JSON decoding
const unlistenMessages = await onMessage(({ channel, data }) => {
  console.log(`Message on ${channel}:`, data)
})

// Listen to messages on specific channel
const unlistenChannel = await onChannelMessage('chat', (data) => {
  console.log('Chat message:', data)
})

// Listen to all messages with timestamp
const unlistenAny = await onAnyMessage(({ channel, data, timestamp }) => {
  console.log(`[${new Date(timestamp).toISOString()}] ${channel}:`, data)
})

Advanced Channel Management

import { helpers } from 'tauri-plugin-centrifugo-api'

// Subscribe to multiple channels with unified callback
const unlisteners = await helpers.subscribeToChannels(['news', 'updates'], ({ channel, data }) => {
  console.log(`${channel}:`, data)
})

// Wait for connection before proceeding
const connected = await helpers.waitForConnection(15000)
if (connected) {
  console.log('Ready to publish messages')
} else {
  console.log('Connection timeout')
}

// Get connection status with retry
const status = await helpers.getConnectionStatus(5)
console.log('Connection status:', status)

Error Handling and Retry Logic

import { connect, isConnected, helpers } from 'tauri-plugin-centrifugo-api'

async function connectWithRetry(maxRetries = 3) {
  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      console.log(`Connection attempt ${attempt}/${maxRetries}`)
      
      await connect({
        url: 'ws://localhost:8000/connection/websocket',
        channels: ['test'],
        useProtobuf: false
      })
      
      // Wait for connection to stabilize
      const connected = await helpers.waitForConnection(5000)
      if (connected) {
        console.log('Successfully connected!')
        return true
      }
      
    } catch (error) {
      console.error(`Attempt ${attempt} failed:`, error)
      
      if (attempt === maxRetries) {
        throw new Error(`Failed to connect after ${maxRetries} attempts`)
      }
      
      // Wait before retry
      await new Promise(resolve => setTimeout(resolve, 1000 * attempt))
    }
  }
  
  return false
}

Example Application

The repository includes a complete Svelte example application demonstrating all plugin features:

• Connection management
• Message publishing
• RPC calls
• Event handling
• Channel subscriptions
• Backend command integration

To run the example:

cd examples/tauri-app
pnpm install
pnpm tauri dev

Development

Building

# Build Rust plugin
cargo build

# Build JavaScript API
cd guest-js
pnpm build

# Build example app
cd examples/tauri-app
pnpm tauri build

Testing

# Test Rust code
cargo test

# Test example app
cd examples/tauri-app
pnpm tauri dev

Dependencies

• Rust: tauri 2.6.2+, tokio-centrifugo, serde, thiserror
• JavaScript: @tauri-apps/api >=2.0.0-beta.6
• Build Tools: rollup, typescript

Permissions

By default all potentially dangerous plugin commands and scopes are blocked and cannot be accessed. You must modify the permissions in your capabilities configuration to enable these.

See the Capabilities Overview for more information and the step by step guide to use plugin permissions.

{
  "permissions": [
    "...",
    "centrifugo:default"
  ]
}

License

MIT License - see LICENSE file for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

Support

For issues and questions:

• Create an issue on GitHub
• Check the example application
• Review the API documentation

tauri-plugin-centrifugo