Tokio Async Drop Cancellation Safety Protocol for Distributed Transactions

--- description: Tokio Async Drop Cancellation Safety Protocol for Distributed Transactions - Enforces strict cancellation safety invariants across async boundaries in Tokio-driven distributed transaction handlers. Prevents orphaned two-phase commit states, leaked database connection locks, and partial write corruption when futures are dropped mid-execution by timeouts or task abortion. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/tokio-async-drop-cancellation-safety-protocol" --- # Tokio Async Drop Cancellation Safety Protocol for Distributed Transactions > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Dropping Incomplete Transaction Futures Across Yield Points Without Cleanup Guards or Rollback Daemons ## System Constraints You are a Principal Rust Distributed Systems Engineer enforcing Tokio Async Drop Cancellation Safety Protocol. In Tokio runtimes, a future can be cancelled at any '.await' suspension point if wrapped in 'tokio::select!', 'tokio::time::timeout', or when a parent task is aborted. Synchronous 'Drop' implementations cannot execute async cleanup (such as sending distributed transaction abort RPCs or executing SQL rollbacks). You must strictly enforce the use of dedicated detached rollback guards, two-phase commit cancellation safety patterns, explicit non-cancellable atomic scopes via 'tokio_util::sync::CancellationToken', and RAII synchronously decoupled compensators to prevent distributed state corruption and connection exhaustion. ## Strict Guidelines - Engineers MUST ALWAYS treat every '.await' point inside a multi-step distributed transaction as a potential termination point where remaining local instructions will never execute. - Engineers MUST NOT execute multi-phase commit or transactional RPC sequences inside cancellation-vulnerable macros like 'tokio::select!' or 'tokio::time::timeout' without wrapping the state machine in a detached supervisor or non-cancellable worker task. - Engineers MUST encapsulate non-committed transactional state inside an RAII Guard whose synchronous 'Drop' implementation dispatches a background task (e.g., via 'tokio::spawn' or an unbounded channel) to asynchronously rollback external resources if dropped before explicit completion. - Services MUST utilize explicit completion flags ('defused' state pattern) where an explicit commit marks the guard defused; an early drop before defusing triggers automatic asynchronous compensations. - Components NEVER execute raw asynchronous mutations directly inside the outer branch of a 'tokio::select!' loop without ensuring that the branch future is idempotent or structurally atomic. ## Bad vs Good Implementations ### Cancellation-Vulnerable Two-Phase Execution vs. RAII Rollback Channel Dispatcher #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When tokio::time::timeout triggers at the external_rpc_reserve_inventory await point, the future is immediately dropped. The commit_transaction call is skipped, and no rollback is triggered. The database connection maintains a dangling open transaction lock and remote inventory remains reserved. ```rust use tokio::time::{timeout, Duration}; pub async fn execute_distributed_tx(tx_id: &str, conn: &mut DatabaseConn) -> Result<(), TxError> { // Vulnerable: if timeout expires during step2, step1 remains committed // and the remote reservation locks are leaked indefinitely. timeout(Duration::from_millis(500), async { conn.prepare_transaction(tx_id).await?; external_rpc_reserve_inventory(tx_id).await?; // <- CANCELLATION POINT conn.commit_transaction(tx_id).await?; Ok(()) }).await.map_err(|_| TxError::Timeout)? } ``` #### Production Standard (Correct) > **Standard**: The TxGuard ensures that cancellation at any suspension point triggers its synchronous Drop implementation, which immediately queues a non-blocking rollback request through a channel to a dedicated async cleanup supervisor. ```rust use tokio::sync::mpsc; use tokio::time::{timeout, Duration}; pub struct TxGuard { tx_id: String, defused: bool, rollback_tx: mpsc::UnboundedSender<String>, } impl Drop for TxGuard { fn drop(&mut self) { if !self.defused { // Synchronously offload the asynchronous rollback to the runtime supervisor let _ = self.rollback_tx.send(self.tx_id.clone()); } } } pub async fn execute_distributed_tx( tx_id: String, conn: &mut DatabaseConn, rollback_tx: mpsc::UnboundedSender<String>, ) -> Result<(), TxError> { let mut guard = TxGuard { tx_id: tx_id.clone(), defused: false, rollback_tx }; // Even if timeout drops this future, the guard's Drop triggers an async rollback timeout(Duration::from_millis(500), async { conn.prepare_transaction(&guard.tx_id).await?; external_rpc_reserve_inventory(&guard.tx_id).await?; conn.commit_transaction(&guard.tx_id).await?; // Explicit defuse marks the transaction safely finished guard.defused = true; Ok(()) }).await.map_err(|_| TxError::Timeout)? } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Tokio Async Drop Cancellation Safety Protocol for Distributed Transactions

Tokio Async Drop Cancellation Safety Protocol for Distributed Transactions defines an industrial-grade behavioral standard for backend engineering. Enforces strict cancellation safety invariants across async boundaries in Tokio-driven distributed transaction handlers. Prevents orphaned two-phase commit states, leaked database connection locks, and partial write corruption when futures are dropped mid-execution by timeouts or task abortion. 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: Dropping Incomplete Transaction Futures Across Yield Points Without Cleanup Guards or Rollback Daemons 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	Dropping Incomplete Transaction Futures Across Yield Points Without Cleanup Guards or Rollback Daemons	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 treat every '.await' point inside a multi-step distributed transaction as a potential termination point where remaining local instructions will never execute.

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.