Tauri 2.0 Mobile Zero-Copy Binary Ring Buffer Protocol Invariant

--- description: Tauri 2.0 Mobile Zero-Copy Binary Ring Buffer Protocol Invariant - Enforces zero-copy or direct binary channel streaming for high-frequency binary data between the Tauri 2.0 native Rust core and platform WebViews (iOS WKWebView / Android WebView). Prohibits JSON or Base64 serialization over the standard IPC bridge for binary streams to prevent mobile garbage collector thrashing, main thread stalls, and excessive battery consumption. globs: src/**/*.{ts,tsx}, src-tauri/src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tauri2-mobile-shm-ringbuffer-protocol" --- # Tauri 2.0 Mobile Zero-Copy Binary Ring Buffer Protocol Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Serializing High-Frequency Binary Streaming Payloads via Standard JSON/Base64 invoke() IPC ## System Constraints You are a Principal Systems and Mobile Architect enforcing strict IPC performance boundaries for Tauri 2.0 on Android and iOS. Standard IPC channels rely on WebKit/V8 messaging layers that serialize through JSON strings, causing severe thermal throttling, high GC pause intervals, and frame drops when processing high-frequency streams (such as PCM audio, real-time camera frames, sensor telemetry, and neural embeddings). You must strictly mandate binary streaming channels (Tauri 2.0 `Channel<Vec<u8>>`), memory-mapped ring buffers, or custom protocol streams, maintaining zero-copy semantics and pre-allocated buffer pools across the webview-native boundary. ## Strict Guidelines - Engineers MUST ALWAYS transfer binary streams exceeding 10Hz or 1KB/frame via Tauri 2.0 `Channel<Vec<u8>>` or custom protocol streaming (`tauri://` / `http://tauri.localhost`). - Engineers MUST NOT convert binary data (`ArrayBuffer`, `Uint8Array`, `Vec<u8>`) to Base64 strings, comma-separated numeric arrays, or JSON arrays over `invoke()` on mobile platforms. - Code MUST employ pre-allocated, fixed-capacity ring buffer pools on the webview consumer to eliminate per-frame allocations and garbage collection cycles. - Services MUST manage read/write offsets using atomic sequence counters or structured 16-byte fixed binary headers (magic, sequence_id, payload_length, timestamp) preceding frame payloads. - Components NEVER bridge streaming sensor, audio, or video frame cycles through standard reactive UI state (e.g., React `useState` / Vue `ref`) directly from high-rate IPC subscribers. ## Bad vs Good Implementations ### Tauri 2.0 Webview Binary Ingestion: Serialization vs Binary Channel Ring Buffer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Invoking `poll_audio_samples` over standard `invoke()` forces Rust to serialize floating-point numbers into a JSON array string. Parsing this JSON array inside mobile WebKit/V8 generates thousands of ephemeral heap objects every frame, triggering aggressive garbage collection pauses and exceeding the 16.6ms frame budget. ```typescript import { invoke } from '@tauri-apps/api/core'; // ANTI-PATTERN: Serializes high-throughput raw audio/sensor buffers through JSON IPC export async function startAudioStream(onSample: (data: Float32Array) => void) { const interval = setInterval(async () => { // Serializes a 2048-sample Float32Array into a JSON numeric array [0.012, 0.432, ...] // Causes massive string allocations and JSON parser thrashing in WebView JSC/V8 const rawData = await invoke<number[]>('poll_audio_samples'); const sampleBuffer = new Float32Array(rawData); onSample(sampleBuffer); }, 16); return () => clearInterval(interval); } ``` #### Production Standard (Correct) > **Standard**: Utilizes Tauri 2.0 `Channel<Uint8Array>` to transfer direct raw byte arrays bypassing JSON serialization. Incoming buffers are processed via a zero-allocation circular ring buffer with atomic pointer updates, eliminating mobile UI thread GC pressure and ensuring continuous 60/120 FPS performance. ```typescript import { Channel, invoke } from '@tauri-apps/api/core'; const RING_BUFFER_SIZE = 16 * 1024 * 1024; // 16MB pre-allocated ring buffer const ringBuffer = new SharedArrayBuffer(RING_BUFFER_SIZE); const atomicHeader = new Int32Array(ringBuffer, 0, 4); // [0]=write_ptr, [1]=read_ptr const ringData = new Uint8Array(ringBuffer, 16); export async function startBinaryRingBufferConsumer( onFrame: (payload: Uint8Array) => void ): Promise<() => void> { // Invariant: Native stream writes raw Uint8Array frames directly over Tauri 2.0 Channel const channel = new Channel<Uint8Array>(); channel.onmessage = (chunk: Uint8Array) => { const writePtr = Atomics.load(atomicHeader, 0); const chunkLen = chunk.byteLength; const capacity = ringData.byteLength; // Zero-alloc circular buffer copy if (writePtr + chunkLen <= capacity) { ringData.set(chunk, writePtr); Atomics.store(atomicHeader, 0, (writePtr + chunkLen) % capacity); } else { const firstPart = capacity - writePtr; ringData.set(chunk.subarray(0, firstPart), writePtr); ringData.set(chunk.subarray(firstPart), 0); Atomics.store(atomicHeader, 0, chunkLen - firstPart); } onFrame(chunk); }; await invoke('start_native_binary_stream', { onEvent: channel }); return () => { invoke('stop_native_binary_stream'); }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 Mobile Zero-Copy Binary Ring Buffer Protocol Invariant

Tauri 2.0 Mobile Zero-Copy Binary Ring Buffer Protocol Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces zero-copy or direct binary channel streaming for high-frequency binary data between the Tauri 2.0 native Rust core and platform WebViews (iOS WKWebView / Android WebView). Prohibits JSON or Base64 serialization over the standard IPC bridge for binary streams to prevent mobile garbage collector thrashing, main thread stalls, and excessive battery consumption. 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 High-Frequency Binary Streaming Payloads via Standard JSON/Base64 invoke() 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 High-Frequency Binary Streaming Payloads via Standard JSON/Base64 invoke() 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 transfer binary streams exceeding 10Hz or 1KB/frame via Tauri 2.0 `Channel<Vec<u8>>` or custom protocol streaming (`tauri

Engineers MUST ALWAYS transfer binary streams exceeding 10Hz or 1KB/frame via Tauri 2.0 `Channel<Vec<u8>>` or custom protocol streaming (`tauri://` / `http://tauri.localhost`).

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.