JSON vs Protobuf Data Handling

Relevant source files

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

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

The Tauri Centrifugo plugin provides a flexible architecture for real-time communication, allowing developers to choose between JSON and Protobuf protocols for data serialization. This choice impacts how the client establishes a WebSocket connection and how data is structured during transmission. While JSON is often preferred for ease of debugging and JavaScript compatibility, Protobuf (Protocol Buffers) offers a more compact binary format suitable for high-performance or bandwidth-constrained environments.

Sources: README.md:12, src/lib.rs:10

Protocol Selection and Configuration

The protocol used by the plugin is determined at the time of connection via the useProtobuf flag in the connection configuration. This setting dictates the underlying communication logic within the tokio-centrifuge library used by the Rust backend.

Connection Configuration Parameters

Parameter	Type	Description
url	string	The WebSocket URL of the Centrifugo server.
useProtobuf	boolean	Flag to enable Protobuf protocol (true) or JSON (false).
channels	string[]	Initial list of channels to subscribe to.

Sources: guest-js/index.ts:6-14, src/models.rs:43-62

Protocol Selection Flow

The following diagram illustrates how the protocol selection influences the connection establishment phase.

Data Serialization and Encoding

Regardless of whether JSON or Protobuf is selected for the transport protocol, the plugin utilizes a specific encoding strategy for the message payloads (data fields). All data sent through the plugin's publish, rpc, or send commands must be Base64 encoded before being passed to the Rust backend.

Base64 Requirement

The Rust models define data fields as strings intended to hold Base64-encoded content. This ensures that binary data (from Protobuf) and stringified objects (from JSON) can be safely passed through the Tauri IPC bridge.

#[derive(Debug, Deserialize, Serialize, Clone)]
#[serde(rename_all = "camelCase")]
pub struct PublishRequest {
    pub channel: String,
    pub data: String, // Base64-encoded message data
}

Sources: src/models.rs:81-86, guest-js/index.ts:17-20

JavaScript Utility Helpers

To simplify the transition between JavaScript objects and the required Base64 format, the plugin provides a utils object. These utilities handle the conversion for both standard strings and JSON objects.

export const utils = {
  encode: (data: string): string => window.btoa(data),
  decode: (data: string): string => window.atob(data),
  encodeJson: (data: any): string => utils.encode(JSON.stringify(data)),
  decodeJson: <T>(data: string): T => JSON.parse(utils.decode(data))
}

Sources: guest-js/index.ts:241-267

Protobuf Schema Definitions

When using the Protobuf protocol, the data structures follow the definitions specified in the api.proto file. This includes standardized messages for publishing, broadcasting, and retrieving history.

Key Protobuf Messages

Message	Purpose
PublishRequest	Defines the structure for sending data to a specific channel.
Publication	Represents a single message received from a channel, including data and metadata.
RPCRequest	Structure for executing remote procedure calls with binary parameters.

Sources: examples/server/proto/api.proto:136-143, examples/server/proto/api.proto:233-239

Publication Data Structure

The representation of received data is consistent across protocols at the plugin interface level, but the content within the data field varies.

Implementation in the Frontend

The helpers namespace provides high-level methods that abstract the serialization process, making it easier to work with JSON even when the underlying transport might be optimized.

Helper Method Logic

When helpers.publishJson is called, it performs the following steps:

1. Stringifies the JavaScript object.
2. Encodes the string to Base64.
3. Invokes the Tauri command with the resulting string.

export const helpers = {
  publishJson: async (channel: string, data: any): Promise<void> => {
    const base64Data = utils.encodeJson(data)
    await publish({ channel, data: base64Data })
  }
}

Sources: guest-js/index.ts:273-277, examples/tauri-app/src/App.svelte:311-325

Conclusion

The Tauri Centrifugo plugin bridges the gap between high-level JavaScript data structures and low-level transport protocols. By requiring Base64 encoding for all data payloads, it maintains a unified interface for both JSON and Protobuf handling. Developers can utilize the useProtobuf configuration for transport efficiency while relying on the utils and helpers modules to manage data serialization seamlessly within the Tauri environment.