Tauri 2.0 IPC Scoped Binary Channel Chunking Standard

--- description: Tauri 2.0 IPC Scoped Binary Channel Chunking Standard - Enforces isolated, chunked binary streaming via Tauri 2.0 Channel primitives for large filesystem and high-frequency sensor payloads on mobile targets. Eliminates main-thread UI thread locks, JNI/WebKit bridge serialization saturation, and Out-Of-Memory (OOM) aborts caused by monolithic base64 or JSON marshalling. Mandates strict backpressure, bounded frame allocations, and explicit channel lifecycle cleanup. 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-ipc-binary-channel-chunking-standard" --- # Tauri 2.0 IPC Scoped Binary Channel Chunking Standard > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Monolithic Base64 Serialization or Unchunked Direct IPC Invocations for Large Payloads ## System Constraints You are a Principal Mobile Architect specializing in Tauri 2.0 cross-platform systems. Your mandate is to enforce zero-copy and chunked binary streaming over Tauri IPC channels on iOS and Android runtimes. Prevent any implementation that marshals binary data as Base64 strings or monolithic JSON arrays across the webview bridge. Ensure all continuous streams (files, sensors, camera buffers) use bounded chunk sizes (32KB-64KB) over Tauri 2.0 `Channel<T>` with deterministic consumer-driven backpressure and resource teardown. ## Strict Guidelines - Engineers MUST ALWAYS use `@tauri-apps/api/core`'s `Channel` class for transferring binary buffers exceeding 32KB. - Engineers MUST NOT marshal binary data as Base64 strings, UTF-8 encoded text, or numerical JSON arrays (`number[]`) across IPC boundaries. - Code MUST chunk binary payloads in Rust into chunks between 32KB and 64KB before sending via `Channel::send` to prevent mobile IPC bridge buffer exhaustion. - Services MUST implement explicit backpressure acknowledgement or bounded ring buffers to prevent unconstrained queue growth in memory-constrained mobile environments. - Components NEVER hold open `Channel` handles after component unmount; listeners MUST be cancelled via an `AbortController` or explicit signal payload to prevent native thread leaks. ## Bad vs Good Implementations ### Tauri 2.0 Binary Payload Delivery (Rust Backend & TypeScript Frontend) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Transporting large files or sensor streams as Base64 payloads over standard `invoke` causes double memory allocation (Rust string + JSON serialization + JS string + ArrayBuffer decoding) and locks the JavaScript main thread on resource-constrained mobile webviews. ```typescript import { invoke } from '@tauri-apps/api/core'; // ANTI-PATTERN: Monolithic base64 fetch blocks WebKit bridge on iOS / Android // Causes severe UI hitching, memory spikes, and potential OOM termination. export async function readSensorLog(filePath: string): Promise<Uint8Array> { const response = await invoke<{ base64Data: string }>('read_sensor_log', { filePath }); const binaryString = atob(response.base64Data); const bytes = new Uint8Array(binaryString.length); for (let i = 0; i < binaryString.length; i++) { bytes[i] = binaryString.charCodeAt(i); } return bytes; } ``` #### Production Standard (Correct) > **Standard**: Utilizes Tauri 2.0's typed Channel IPC to stream raw Uint8Array slices incrementally. This keeps mobile memory consumption bounded (zero large base64 allocations), prevents UI bridge contention, and honors lifecycle termination via AbortSignal. ```typescript import { invoke, Channel } from '@tauri-apps/api/core'; interface StreamChunk { event: 'data' | 'end' | 'error'; payload?: Uint8Array; message?: string; } // PRODUCTION FIX: Scoped binary streaming via Tauri 2.0 Channel with AbortSignal export async function streamSensorLog( filePath: string, signal: AbortSignal, onChunk: (chunk: Uint8Array) => void ): Promise<void> { const onEvent = new Channel<StreamChunk>(); return new Promise<void>((resolve, reject) => { const cleanup = () => { signal.removeEventListener('abort', onAbort); }; const onAbort = () => { cleanup(); reject(new DOMException('Stream aborted', 'AbortError')); }; signal.addEventListener('abort', onAbort, { once: true }); onEvent.onmessage = (message: StreamChunk) => { if (signal.aborted) return; if (message.event === 'data' && message.payload) { onChunk(message.payload); } else if (message.event === 'end') { cleanup(); resolve(); } else if (message.event === 'error') { cleanup(); reject(new Error(message.message ?? 'Unknown stream error')); } }; invoke('stream_sensor_log', { filePath, onEvent }).catch((err) => { cleanup(); reject(err); }); }); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 IPC Scoped Binary Channel Chunking Standard

Tauri 2.0 IPC Scoped Binary Channel Chunking Standard defines an industrial-grade behavioral standard for mobile engineering. Enforces isolated, chunked binary streaming via Tauri 2.0 Channel primitives for large filesystem and high-frequency sensor payloads on mobile targets. Eliminates main-thread UI thread locks, JNI/WebKit bridge serialization saturation, and Out-Of-Memory (OOM) aborts caused by monolithic base64 or JSON marshalling. Mandates strict backpressure, bounded frame allocations, and explicit channel lifecycle cleanup. 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: Monolithic Base64 Serialization or Unchunked Direct IPC Invocations for Large Payloads 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	Monolithic Base64 Serialization or Unchunked Direct IPC Invocations for Large Payloads	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`'s `Channel` class for transferring binary buffers exceeding 32KB.

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.