Tauri 2.0 IPC Zero-Copy ArrayBuffer & Channel Binary Transfer Boundary

--- description: Tauri 2.0 IPC Zero-Copy ArrayBuffer & Channel Binary Transfer Boundary - Enforces zero-serialization binary streaming between the Tauri Core Rust runtime and web client WebViews using Tauri 2.0 Channels or raw binary Response types. Prohibits base64 strings or JSON integer array representations of byte arrays (`Vec<u8>`) across the IPC boundary to eliminate memory thrashing, main thread serialization locks, and quadratic GC allocation churn. globs: src/**/*.{ts,tsx}, src-tauri/src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tauri-v2-ipc-zero-copy-binary-boundary" --- # Tauri 2.0 IPC Zero-Copy ArrayBuffer & Channel Binary Transfer Boundary > **Severity**: CRITICAL | **Category**: frontend > **Anti-Pattern Warning**: Serializing Raw Byte Buffers into Base64 Strings or JSON Number Arrays across Tauri IPC ## System Constraints You are a Principal Systems & Frontend Engineer enforcing zero-copy binary communication boundaries across Tauri 2.0 applications. You mandate that high-throughput and large payload binary operations bypass JSON-RPC serialization by utilizing Tauri 2.0 binary IPC protocols, Channel streaming primitives, or custom protocol URL schemes. You strictly reject JSON-marshaled `Vec<u8>` arrays, Base64 encoding over IPC, and redundant ArrayBuffer memory duplications. ## Strict Guidelines - Engineers MUST ALWAYS use `@tauri-apps/api/core` `invoke` with explicit `Uint8Array` or Tauri 2.0 `Channel<Uint8Array>` when streaming binary data. - Engineers MUST NOT return raw `Vec<u8>` directly inside standard JSON-serialized command structs without `tauri::ipc::Response` or binary Channel wrapping. - Engineers MUST configure Tauri 2.0 Rust commands to return `tauri::ipc::Response` containing raw byte slices (`Response::new(vec)`) rather than JSON-encoded payload objects. - Frontend consumers MUST transfer ownership or instantiate views using zero-copy TypedArray slicing (`new Uint8Array(buffer, offset, length)`) instead of copying via `.slice()` where possible. - High-frequency binary event streams (e.g., video, audio, telemetry) MUST use `Channel<Uint8Array>` instead of `app_handle.emit()` to avoid IPC broadcast table JSON serialization overhead. - Components NEVER decode base64 binary chunks in the JavaScript main thread when handling data transferred from native backend plugins. ## Bad vs Good Implementations ### Anti-Pattern: JSON-Serialized Byte Array over Standard Invoke #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Returning a byte array (`Vec<u8>`) inside a standard serde-serialized struct forces the Tauri IPC bridge to serialize every single byte into an ASCII JSON integer separated by commas. A 10MB payload expands to ~40MB of text and triggers heavy GC pauses during JSON parsing on the WebView thread. ```typescript import { invoke } from '@tauri-apps/api/core'; interface FrameResponse { frameId: number; // Anti-pattern: Serialized as a massive JSON array of numbers [0, 255, 12, ...] data: number[]; } export async function fetchRawFrame(id: number): Promise<Uint8Array> { const res = await invoke<FrameResponse>('get_raw_frame', { id }); // Costly allocation: iterates over million-element JS array to build Uint8Array return new Uint8Array(res.data); } ``` #### Production Standard (Correct) > **Standard**: By returning a native `tauri::ipc::Response` from Rust with bytes, Tauri sends the buffer directly over the native WebView IPC bridge as an ArrayBuffer. JavaScript immediately receives a typed `Uint8Array` without intermediate JSON stringification or per-element allocations. ```typescript import { invoke } from '@tauri-apps/api/core'; export async function fetchRawFrame(id: number): Promise<Uint8Array> { // Tauri 2.0 invoke directly resolves to Uint8Array when backend returns tauri::ipc::Response const binaryPayload = await invoke<Uint8Array>('get_raw_frame', { id }, { // In Tauri 2.0, binary responses bypass serde_json headers: { 'Content-Type': 'application/octet-stream' } }); return binaryPayload; } ``` ### Streaming High-Throughput Payloads via Tauri 2.0 Channel #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using global events with Base64 strings imposes a 33% payload bloat, requires string allocation on Rust side, and forces synchronous string decoding via `atob` and character iteration on the JS main thread, severely degrading UI frame rates. ```typescript import { listen } from '@tauri-apps/api/event'; // Anti-pattern: Global event broker serializes base64 strings on main thread export function subscribeToSensorStream(onChunk: (chunk: Uint8Array) => void) { return listen<string>('sensor-data-chunk', (event) => { const binaryString = atob(event.payload); const len = binaryString.length; const bytes = new Uint8Array(len); for (let i = 0; i < len; i++) { bytes[i] = binaryString.charCodeAt(i); } onChunk(bytes); }); } ``` #### Production Standard (Correct) > **Standard**: Tauri 2.0 `Channel` supports binary data frames natively. The Rust backend writes raw byte slices directly to the channel emitter (`on_data.send(vec)`), which are decoded straight into `Uint8Array` instances in the WebView without JSON parsing or string translation. ```typescript import { Channel } from '@tauri-apps/api/core'; import { invoke } from '@tauri-apps/api/core'; export async function subscribeToSensorStream(onChunk: (chunk: Uint8Array) => void): Promise<() => void> { const onData = new Channel<Uint8Array>(); onData.onmessage = (chunk: Uint8Array) => { // Native zero-copy binary dispatch directly to TypedArray handler onChunk(chunk); }; await invoke('start_sensor_stream', { onData }); return () => { void invoke('stop_sensor_stream'); }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 IPC Zero-Copy ArrayBuffer & Channel Binary Transfer Boundary

Tauri 2.0 IPC Zero-Copy ArrayBuffer & Channel Binary Transfer Boundary defines an industrial-grade behavioral standard for frontend engineering. Enforces zero-serialization binary streaming between the Tauri Core Rust runtime and web client WebViews using Tauri 2.0 Channels or raw binary Response types. Prohibits base64 strings or JSON integer array representations of byte arrays (`Vec<u8>`) across the IPC boundary to eliminate memory thrashing, main thread serialization locks, and quadratic GC allocation churn. Modern software architectures require strict adherence to deterministic patterns to guarantee high availability, maintainability, and zero security vulnerabilities.

Framework Paradigm Shift & Drift MechanicsLLMs are trained on millions of open-source repositories containing outdated code, legacy idioms, and unpatched antipatterns. When coding assistants generate implementations for this stack, they default to common statistical tokens: Serializing Raw Byte Buffers into Base64 Strings or JSON Number Arrays across Tauri IPC Without an explicit system instruction file, developers spend hours debugging silent failures.

Failure Modes & Production Blast Radius

Hazard Analysis: What Breaks Without This Rule

The following failure modes have been cataloged from hundreds of hours of production code reviews where AI assistants produced non-compliant implementations:

Failure Mode	AI Symptom (The Anti-Pattern)	Severity	Production Impact & Remedy
AI Hallucination & Deprecation Drift	Serializing Raw Byte Buffers into Base64 Strings or JSON Number Arrays across Tauri IPC	Critical	Violating this industrial standard introduces regression bugs, security risks, and unexpected runtime failures in production. Enforce explicit behavioral system directives across all AI coding assistants in your repository.
Silent Architecture Inconsistency	AI assistants produce mixed paradigms across files, creating fragmented codebase conventions.	Medium	Increases cognitive load during code reviews and leads to maintenance debt across engineering teams. Pin project conventions in .cursor/rules, CLAUDE.md, and AGENTS.md so all team agents follow identical guardrails.

Architectural Directives in Detail

Step-by-Step Production Directives

Each rule constraint below is injected into the AI agent's system prompt to establish deterministic boundaries:

Engineers MUST ALWAYS use `@tauri-apps/api/core` `invoke` with explicit `Uint8Array` or Tauri 2.0 `Channel<Uint8Array>` when streaming binary data.

Rationale:AI models frequently generate unconstrained code here because statistical language distributions lack project-specific architectural context. Mandating this directive ensures that generated code adheres to verified industrial production requirements.