Tauri 2.0 IPC Reentrancy Prevention & Bounded Ring-Buffer Bridge Invariant

--- description: Tauri 2.0 IPC Reentrancy Prevention & Bounded Ring-Buffer Bridge Invariant - Enforces non-reentrant, backpressure-managed IPC streaming between Tauri 2.0 native Rust cores and mobile webview runtimes. Prevents webview main-thread starvation and IPC message-loop deadlocks by mandating bounded ring buffers, batched channel-based telemetry, and prohibiting synchronous reentrant invoke calls within event handlers. 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-reentrancy-ringbuffer-guardrail" --- # Tauri 2.0 IPC Reentrancy Prevention & Bounded Ring-Buffer Bridge Invariant > **Severity**: CRITICAL | **Category**: mobile > **Anti-Pattern Warning**: Unbounded Direct IPC Telemetry Flooding with Synchronous Reentrant Invocations Freezing Mobile Webviews ## System Constraints You are a Principal Mobile Architect enforcing strict Tauri 2.0 IPC safety, non-reentrancy, and ring-buffer throughput limits. Mandate invariants that prevent mobile main-thread locking, WebKit/WebView ANR crashes, and Rust-Webview bridge deadlocks caused by unbounded telemetry streaming or reentrant `invoke` executions. ## Strict Guidelines - Engineers MUST ALWAYS decouple high-frequency native telemetry using bounded circular ring buffers or Tauri 2.0 Channel primitives (`tauri::ipc::Channel`) with strict backpressure. - Engineers MUST NOT execute reentrant `invoke()` calls directly inside Tauri `listen()` event listener callbacks; dispatch state mutations asynchronously outside the bridge context. - Code SHOULD batch high-frequency telemetry events on the webview layer using `requestAnimationFrame` to decouple UI paint cycles from incoming IPC packet rates. - Services MUST enforce upper bounds on Rust-to-Webview event queues; if the webview bridge is saturated, drop the oldest telemetry frames or signal a backpressure overflow. - Components NEVER attach un-deduplicated listeners for high-frequency telemetry streams without guaranteed lifecycle teardown and unlisten handle execution. ## Bad vs Good Implementations ### Tauri 2.0 Telemetry Ingestion: Reentrant Invoke vs Bounded Ring-Buffer Channel #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing `invoke` synchronously inside a high-frequency `listen` callback creates an IPC reentrancy deadlock where the native bridge waits on the webview, which in turn waits on an invoke response. Furthermore, processing 120Hz+ events directly into UI callbacks starves the webview event loop, causing severe frame drops and mobile ANR (Application Not Responding) timeouts. ```typescript import { listen } from '@tauri-apps/api/event'; import { invoke } from '@tauri-apps/api/core'; interface SensorFrame { id: string; readings: number[]; } // ANTI-PATTERN: Direct unthrottled event listener executing synchronous reentrant invoke export function attachSensorBridge(onData: (frame: SensorFrame) => void) { const unlistenPromise = listen<SensorFrame>('sensor://telemetry', async (event) => { // DEADLOCK HAZARD: Synchronous reentrant invoke back to Rust while Rust IPC queue is locked await invoke('telemetry_ack', { frameId: event.payload.id }); // PERF HAZARD: Unthrottled UI update (e.g. 120Hz) saturates WebKit/Android WebView JS thread onData(event.payload); }); return () => { unlistenPromise.then((unlisten) => unlisten()); }; } ``` #### Production Standard (Correct) > **Standard**: Utilizes Tauri 2.0's native `Channel` mechanism for unidirectional, non-reentrant IPC transmission. Introduces a bounded ring-buffer (capacity 64) with deterministic tail-dropping on backpressure saturation, and coalesces UI updates via `requestAnimationFrame` to keep the mobile webview main thread fully responsive at 60/120 FPS. ```typescript import { Channel, invoke } from '@tauri-apps/api/core'; interface SensorFrame { id: string; readings: number[]; } // PRODUCTION INVARIANT: Bounded Ring-Buffer with RAF-batched consumption and decoupled channel export function attachSensorBridge(onBatchUpdate: (frames: SensorFrame[]) => void) { const RING_BUFFER_CAPACITY = 64; const ringBuffer: SensorFrame[] = []; let rafHandle: number | null = null; let isSubscribed = true; const channel = new Channel<SensorFrame>(); channel.onmessage = (frame: SensorFrame) => { if (!isSubscribed) return; // Ring-buffer boundary guard: drop oldest frame on overflow to maintain memory invariant if (ringBuffer.length >= RING_BUFFER_CAPACITY) { ringBuffer.shift(); } ringBuffer.push(frame); // Schedule batched paint-cycle consumption without blocking IPC ingestion if (rafHandle === null) { rafHandle = requestAnimationFrame(() => { rafHandle = null; if (ringBuffer.length > 0) { const batch = ringBuffer.splice(0, ringBuffer.length); onBatchUpdate(batch); } }); } }; // Non-reentrant channel attachment: Rust writes to channel without waiting for frontend ack invoke('start_sensor_stream', { onEvent: channel }).catch((err) => { console.error('Failed to initialize telemetry stream channel', err); }); return () => { isSubscribed = false; if (rafHandle !== null) { cancelAnimationFrame(rafHandle); } invoke('stop_sensor_stream').catch(console.error); }; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tauri 2.0 IPC Reentrancy Prevention & Bounded Ring-Buffer Bridge Invariant

Tauri 2.0 IPC Reentrancy Prevention & Bounded Ring-Buffer Bridge Invariant defines an industrial-grade behavioral standard for mobile engineering. Enforces non-reentrant, backpressure-managed IPC streaming between Tauri 2.0 native Rust cores and mobile webview runtimes. Prevents webview main-thread starvation and IPC message-loop deadlocks by mandating bounded ring buffers, batched channel-based telemetry, and prohibiting synchronous reentrant invoke calls within event handlers. 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: Unbounded Direct IPC Telemetry Flooding with Synchronous Reentrant Invocations Freezing Mobile Webviews 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	Unbounded Direct IPC Telemetry Flooding with Synchronous Reentrant Invocations Freezing Mobile Webviews	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 decouple high-frequency native telemetry using bounded circular ring buffers or Tauri 2.0 Channel primitives (`tauri

Engineers MUST ALWAYS decouple high-frequency native telemetry using bounded circular ring buffers or Tauri 2.0 Channel primitives (`tauri::ipc::Channel`) with strict backpressure.

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.