Axum 0.8 & Tower Async Cancellation and Downstream Drop Safety Invariants

--- description: Axum 0.8 & Tower Async Cancellation and Downstream Drop Safety Invariants - Enforces deterministic teardown of downstream asynchronous tasks and RAII guard patterns when client disconnects or request bodies drop prematurely in Axum 0.8. Prevents background CPU starvation, orphan unbounded execution, and lingering pooled database connection checkouts caused by unhandled Rust async cancellation points. Mandates tokio::select! drop awareness, cancellation tokens, and explicit transaction rollbacks. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-0-8-tower-cancellation-and-drop-safety-guardrail" --- # Axum 0.8 & Tower Async Cancellation and Downstream Drop Safety Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning detached unbounded futures or holding unmonitored RAII transactional leases across cancellation-vulnerable await points ## System Constraints You are a Principal Rust Architect enforcing deterministic asynchronous cancellation, RAII safety, and drop semantics in Axum 0.8 and Tower services. In Rust, async cancellation occurs synchronously at any .await point via future dropping. You must ensure that premature client disconnections, stream aborts, or Tower timeout layer cancellations cleanly reclaim resources, release database connections to pools immediately, roll back uncommitted transactions, and prevent detached background tasks from consuming system resources unchecked. ## Strict Guidelines - Engineers MUST ALWAYS treat every `.await` point within Axum handlers and Tower middleware as a potential synchronous cancellation exit via `Drop`. - Engineers MUST NOT spawn unbounded background tasks with `tokio::spawn` inside request handlers unless explicitly tethered to a managed `CancellationToken` or worker pool with deliberate lifecycle supervision. - Engineers MUST wrap multi-step database mutations within explicit transaction guards where connection checkouts and rollbacks are deterministic upon future drop, rather than relying on delayed pool cleanups. - Code MUST avoid holding exclusive locks (such as `tokio::sync::Mutex` or transactional table locks) across cancellation-prone I/O streams or long-polling response body streams. - Services MUST implement `tokio_util::sync::CancellationToken` or `axum::extract::Request::into_body` stream drop detection when orchestrating long-running transactional work or proxy pipelines. - Components NEVER assume cleanup logic placed sequentially after an `.await` boundary will execute; stateful teardown MUST be encapsulated in explicit RAII `Drop` implementations or guarded by cancellation tokens. ## Bad vs Good Implementations ### Handling Client Disconnection and Database Transaction Drop Safety #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawning an unmonitored tokio task prevents the handler from propagating backpressure or respecting cancellation. Conversely, if executed in the handler directly without RAII guard verification, premature drops at .await boundaries can stall transaction rollback or waste database connections in pooled starvation states. ```rust use axum::{extract::State, Json}; use sqlx::PgPool; use serde::Deserialize; #[derive(Deserialize)] pub struct ProcessPayload { pub items: Vec<String> } // ANTI-PATTERN: If client disconnects mid-processing, tokio::spawn detaches // work indefinitely, while uncommitted database handles may leak or linger. pub async fn handle_batch( State(pool): State<PgPool>, Json(payload): Json<ProcessPayload>, ) -> &'static str { tokio::spawn(async move { let mut tx = pool.begin().await.unwrap(); for item in payload.items { sqlx::query!("INSERT INTO audit_log (entry) VALUES ($1)", item) .execute(&mut *tx) .await .unwrap(); } tx.commit().await.unwrap(); }); "accepted" } ``` #### Production Standard (Correct) > **Standard**: Uses biased tokio::select! with a CancellationToken and relies on sqlx::Transaction's Drop guard to automatically roll back mutations if client drops future before commit is reached. Avoids orphaned background execution. ```rust use axum::{extract::State, http::StatusCode, Json}; use sqlx::PgPool; use serde::Deserialize; use tokio_util::sync::CancellationToken; use tracing::{error, info}; #[derive(Deserialize)] pub struct ProcessPayload { pub items: Vec<String> } // PRODUCTION INVARIANT: Cooperative cancellation with explicit transactional RAII. pub async fn handle_batch( State(pool): State<PgPool>, Json(payload): Json<ProcessPayload>, ) -> Result<StatusCode, StatusCode> { let token = CancellationToken::new(); let _drop_guard = token.clone().drop_guard(); let mut tx = pool.begin().await.map_err(|e| { error!("Failed to acquire db transaction: {e}"); StatusCode::INTERNAL_SERVER_ERROR })?; for item in payload.items { tokio::select! { biased; _ = token.cancelled() => { info!("Client aborted connection, discarding transaction"); // sqlx::Transaction automatically triggers rollback on Drop return Err(StatusCode::REQUEST_TIMEOUT); } res = sqlx::query!("INSERT INTO audit_log (entry) VALUES ($1)", item).execute(&mut *tx) => { if let Err(e) = res { error!("Insert failed: {e}"); return Err(StatusCode::INTERNAL_SERVER_ERROR); } } } } tx.commit().await.map_err(|e| { error!("Commit failed: {e}"); StatusCode::INTERNAL_SERVER_ERROR })?; Ok(StatusCode::OK) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 & Tower Async Cancellation and Downstream Drop Safety Invariants

Axum 0.8 & Tower Async Cancellation and Downstream Drop Safety Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic teardown of downstream asynchronous tasks and RAII guard patterns when client disconnects or request bodies drop prematurely in Axum 0.8. Prevents background CPU starvation, orphan unbounded execution, and lingering pooled database connection checkouts caused by unhandled Rust async cancellation points. Mandates tokio::select! drop awareness, cancellation tokens, and explicit transaction rollbacks. 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: Spawning detached unbounded futures or holding unmonitored RAII transactional leases across cancellation-vulnerable await points 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	Spawning detached unbounded futures or holding unmonitored RAII transactional leases across cancellation-vulnerable await points	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 within Axum handlers and Tower middleware as a potential synchronous cancellation exit via `Drop`.

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.