Guest JS API Core Reference
Relevant source files
The following files were used as context for generating this wiki page:
The Guest JS API Core Reference provides a detailed overview of the JavaScript/TypeScript interface used to interact with the Centrifugo Tauri plugin. This API facilitates real-time, bidirectional communication between a Tauri frontend and a Centrifugo server, abstracting the underlying WebSocket and Rust logic into a set of accessible functions and event listeners.
The API is designed with an event-driven architecture, supporting both JSON and Protobuf protocols. It handles connection lifecycle management, dynamic channel subscriptions, and remote procedure calls (RPC). By utilizing Tauri's command system, the JS API allows developers to manage high-performance real-time features on desktop and mobile platforms with minimal configuration.
Sources: README.md:12-23, src/lib.rs:5-15
Core Connection Management
The API provides fundamental functions to establish, monitor, and terminate connections to the Centrifugo server. These functions interact directly with the Rust backend commands registered during plugin initialization.
Connection Workflow
The connection process involves passing a StartConfig object to the connect function. This configuration defines the target URL, authentication tokens, and initial channel subscriptions.
Sources: README.md:72-85, src/models.rs:44-54
Principal Commands
| Function | Description | Source |
|---|---|---|
connect(config: StartConfig) | Initializes a WebSocket connection using the provided configuration. | src/lib.rs:104 |
disconnect() | Safely closes the active connection and clears local state. | src/lib.rs:105 |
isConnected() | Returns a Promise resolving to a boolean indicating the current status. | src/lib.rs:116 |
getConnectionState() | Retrieves a string representation of the detailed connection state. | src/lib.rs:118 |
Data Models and Configuration
Communication between the Guest JS and the Rust backend is governed by strictly typed data models. These models ensure that parameters such as timeouts and tokens are correctly serialized using camelCase to match JavaScript conventions.
StartConfig Interface
The StartConfig is the primary structure for initializing the plugin.
| Field | Type | Description |
|---|---|---|
url | string | The WebSocket URL of the Centrifugo server. |
token | string? | Optional JWT token for authentication. |
channels | string[] | List of channels to join immediately upon connection. |
useProtobuf | boolean | Flag to switch from JSON to Protobuf protocol. |
readTimeout | number? | Optional timeout for read operations in milliseconds. |
| Sources: src/models.rs:55-71, README.md:204-212 |
Channel and Message Handling
The plugin implements a robust system for managing channel subscriptions and handling incoming publications. Users can dynamically add or remove subscriptions without restarting the primary connection.
Subscription Lifecycle
Messaging Operations
- Publishing: Messages are sent to specific channels using the
publishcommand. The data must be base64-encoded, thoughhelpers.publishJsonis provided to handle object serialization automatically. - RPC: Remote Procedure Calls allow the client to request specific data or actions from the server, returning a
RpcResponsecontaining base64 data and a timestamp.
Sources: src/models.rs:88-109, README.md:89-100
Event System
The Guest JS API exposes several event listeners that allow the frontend to react to state changes and incoming data. These listeners return an UnlistenFn to prevent memory leaks during component unmounting.
| Listener | Trigger Condition | Payload Type |
|---|---|---|
onConnecting | When a connection attempt is initiated. | ConnectionStatus |
onConnected | When the WebSocket is successfully established. | ConnectionStatus |
onDisconnected | When the connection is lost or closed. | ConnectionStatus |
onPublication | When a message is received on any subscribed channel. | PublicationData |
onError | When an internal or network error occurs. | ErrorData |
| Sources: README.md:120-141, src/models.rs:175-197 |
Utilities and Helpers
The API includes a utils namespace for data transformation and a helpers namespace for simplified common patterns.
Utility Functions
utils.encode(string): Encodes a standard string to base64.utils.decodeJson(string): Decodes a base64 string directly into a JavaScript object.
Sources: README.md:164-173, examples/tauri-app/src/App.svelte:145-148
Helper Patterns
Helpers provide higher-level abstractions, such as waitForConnection(timeout), which returns a boolean promise, or subscribeToChannel(channel, callback), which combines subscription logic with message handling.
Sources: README.md:188-197
Security and Permissions
Access to the Guest JS API functions is restricted by Tauri's ACL (Access Control List). The plugin defines a default permission set that must be included in the app's capability configuration to allow frontend access.
{
"permissions": [
"centrifugo:default"
]
}
The default set grants access to critical commands including connect, publish, rpc, and add_subscription.
Sources: README.md:295-303, permissions/schemas/schema.json:442-463
The Guest JS API provides a comprehensive, type-safe interface for real-time operations. By abstracting Centrifugo's complex protocol into standard JavaScript promises and event listeners, it enables developers to build responsive, data-driven Tauri applications across all supported platforms.