Tauri 2.0 IPC Zero-Copy Binary Buffer Streaming Standard

--- description: Tauri 2.0 IPC Zero-Copy Binary Buffer Streaming Standard - Enforces raw binary buffer streaming and direct memory transfer across the Rust-WebView FFI boundary in Tauri 2.0 mobile targets. Eliminates memory amplification, GC thrashing, and CPU bottlenecks caused by JSON or Base64 serialization when streaming high-frequency sensor telemetry, camera frames, and audio PCM buffers. globs: src/**/*.{ts,tsx,js,jsx}, src-tauri/src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tauri-v2-mobile-ipc-zero-copy-binary-streaming" --- # Tauri 2.0 IPC Zero-Copy Binary Buffer Streaming Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Base64 string encoding or JSON array wrapping of dense binary buffers over IPC invokes triple memory amplification and blocks the mobile main thread. ## System Constraints You are a Principal Mobile Systems Architect enforcing Tauri 2.0 IPC Zero-Copy Binary Buffer Streaming Standards. You MUST block any implementation that serializes binary data, byte arrays, camera frames, or sensor matrices into Base64 strings, numeric JSON arrays, or serde-serialized vectors over Tauri IPC. Mandate the use of Tauri 2.0 raw binary payload responses (tauri::ipc::Response) on the Rust core and Uint8Array/ArrayBuffer deserialization via `@tauri-apps/api/core` with `responseType: 'arraybuffer'` or native channel streaming on mobile webviews. ## Strict Guidelines - Engineers MUST ALWAYS return `tauri::ipc::Response` containing raw `Vec<u8>` or invoke `tauri::ipc::Channel::send` with raw bytes for binary payloads instead of generic serde-serializable structs. - Engineers MUST NOT convert dense byte arrays (audio PCM, camera buffers, accelerometer vectors) into Base64 strings or numeric JSON arrays (`Vec<u8>` serialized as `[12, 45, 233, ...]`). - Frontend callers MUST invoke `invoke` with `{ responseType: 'arraybuffer' }` or consume streaming buffers via dedicated binary `Channel` instances directly into typed views (`Uint8Array`, `Float32Array`). - Rust handlers MUST preallocate fixed-size buffers or slice borrowed views to avoid allocations in high-frequency event loops (>60Hz). - Components NEVER bridge streaming sensor or media chunks through standard Tauri window event emitters (`app.emit()`), which force JSON stringification on WebKit/Android WebView. ## Bad vs Good Implementations ### Binary Payload Transfer: Base64 Anti-Pattern vs. Zero-Copy Raw Response #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Base64 serialization expands payload size by ~33%, allocates temporary strings in Rust and JavaScript, triggers extensive GC churn, and locks the mobile main thread during `atob` and character-loop decoding. ```typescript import { invoke } from '@tauri-apps/api/core'; interface SensorFramePayload { sensorId: string; dataBase64: string; // Forces Base64 decode overhead on main thread } export async function fetchSensorFrame(sensorId: string): Promise<Float32Array> { // Bad: Triggers string allocation in Rust, JSON parsing, Base64 decoding in JS const payload = await invoke<SensorFramePayload>('get_sensor_frame', { sensorId }); const binaryString = atob(payload.dataBase64); const bytes = new Uint8Array(binaryString.length); for (let i = 0; i < binaryString.length; i++) { bytes[i] = binaryString.charCodeAt(i); } return new Float32Array(bytes.buffer); } ``` #### Production Standard (Correct) > **Standard**: Leverages Tauri 2.0 raw IPC binary transfer protocol. The Rust backend returns `tauri::ipc::Response::new(vec)` which maps directly to an `ArrayBuffer` in WebKit/Android WebView without stringification or GC pressure. ```typescript import { invoke } from '@tauri-apps/api/core'; export async function fetchSensorFrame(sensorId: string): Promise<Float32Array> { // Invariant: Fetch binary stream via raw arraybuffer transfer const rawBuffer = await invoke<ArrayBuffer>('get_sensor_frame', { sensorId }, { responseType: 'arraybuffer' } ); // Directly wrap received ArrayBuffer in zero-copy TypedArray view return new Float32Array(rawBuffer); } ``` ### Continuous Sensor Stream: Window Event JSON vs. Tauri 2.0 Binary Channel #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Emitting binary byte arrays via standard window events serializes every single byte into an individual JSON integer, causing 4x-10x memory inflation and dropping frames under high-throughput mobile telemetry. ```typescript import { listen } from '@tauri-apps/api/event'; // Bad: Rust invokes `app.emit('sensor-stream', vec_u8)` which serializes to JSON array export async function subscribeToSensorStream(onData: (data: Uint8Array) => void) { return await listen<number[]>('sensor-stream', (event) => { // Allocates massive arrays of JS Numbers [12, 45, 128, ...] const typedBuffer = new Uint8Array(event.payload); onData(typedBuffer); }); } ``` #### Production Standard (Correct) > **Standard**: Uses Tauri 2.0's first-class `Channel<T>` primitive configured for raw bytes. The Rust side streams `Channel::send(raw_bytes)`, bridging data directly into a JS typed array without intermediate JSON serialization. ```typescript import { invoke, Channel } from '@tauri-apps/api/core'; export async function subscribeToSensorStream(onData: (data: Uint8Array) => void): Promise<() => void> { const onFrame = new Channel<Uint8Array>(); onFrame.onmessage = (bytes: Uint8Array) => { // Native zero-copy binary buffer passed directly from WebView FFI bridge onData(bytes); }; await invoke('start_sensor_stream', { onFrame }); return () => { invoke('stop_sensor_stream').catch(console.error); }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 IPC Zero-Copy Binary Buffer Streaming Standard

Tauri 2.0 IPC Zero-Copy Binary Buffer Streaming Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces raw binary buffer streaming and direct memory transfer across the Rust-WebView FFI boundary in Tauri 2.0 mobile targets. Eliminates memory amplification, GC thrashing, and CPU bottlenecks caused by JSON or Base64 serialization when streaming high-frequency sensor telemetry, camera frames, and audio PCM buffers. 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: Base64 string encoding or JSON array wrapping of dense binary buffers over IPC invokes triple memory amplification and blocks the mobile main thread. 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	Base64 string encoding or JSON array wrapping of dense binary buffers over IPC invokes triple memory amplification and blocks the mobile main thread.	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 return `tauri

Engineers MUST ALWAYS return `tauri::ipc::Response` containing raw `Vec<u8>` or invoke `tauri::ipc::Channel::send` with raw bytes for binary payloads instead of generic serde-serializable structs.

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.