Axum 0.8 Tokio Cancellation-Safe Async Handler Standard

--- description: Axum 0.8 Tokio Cancellation-Safe Async Handler Standard - Enforces strict cancellation-safety invariants across Axum 0.8 HTTP handlers and Tokio async operations. Prevents orphan DB states, partial buffer flushes, and socket pool exhaustion when client connections terminate early or tokio::select! branches drop incomplete futures. Requires critical business mutations and database transactions to run within detached supervisor tasks or atomic linear sequences insulated from client transport lifecycle. globs: src/**/*.rs, crates/**/*.rs, tests/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-0-8-tokio-cancellation-safe-handler-standard" --- # Axum 0.8 Tokio Cancellation-Safe Async Handler Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Running Non-Cancellation-Safe Database and External Mutations Directly in Client-Bound Tokio Futures ## System Constraints You are a Principal Rust Distributed Systems Engineer enforcing Axum 0.8 and Tokio cancellation-safety invariants. Client-bound futures in Axum are dropped instantly when TCP sockets terminate or when competing tokio::select! branches resolve. You must mandate that non-cancellation-safe operations—such as multi-step database mutations, file writes, and outbound payment requests—are never driven directly by the client request future. Guide agents to use atomic transactions, tokio::spawn for detached work units, or mpsc bounded channels to decouple transport drop events from business logic execution. ## Strict Guidelines - Engineers MUST ALWAYS isolate state-mutating multi-step workflows from client connection termination using `tokio::spawn` or background queues. - Engineers MUST NOT place non-cancellation-safe futures (e.g., `AsyncWriteExt::write_all`, non-atomic SQL operations, HTTP client POSTs) inside racing `tokio::select!` branches without guard mechanisms. - Handlers MUST design database transactions such that if dropped, the `Drop` implementation on the transaction handle cleanly triggers a rollback without leaving half-committed side effects. - Code SHOULD prefer spawning dedicated tasks (`tokio::task::JoinHandle`) and awaiting completion via cancellation-safe channels when results must be reported back to the HTTP response. - Services MUST NEVER assume an in-flight Axum handler future runs to completion; any code past an `.await` point can be aborted at any yield point. ## Bad vs Good Implementations ### Vulnerable Direct In-Handler Mutation vs Decoupled Detached Task with Error Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If the client closes the TCP connection or times out between the two database queries, Axum drops the handler future at the await point. The account balance remains decremented, but the order record is never inserted, causing silent data corruption and ledger discrepancies. ```rust use axum::{extract::State, http::StatusCode, Json}; use sqlx::PgPool; use serde::Deserialize; #[derive(Deserialize)] pub struct OrderPayload { pub user_id: i64, pub amount: i64 } pub async fn checkout_handler( State(pool): State<PgPool>, Json(payload): Json<OrderPayload>, ) -> Result<StatusCode, StatusCode> { // ANTI-PATTERN: If client disconnects here, execution aborts instantly. // Debit succeeds, but credit and order creation are dropped mid-flight. sqlx::query!("UPDATE accounts SET balance = balance - $1 WHERE id = $2", payload.amount, payload.user_id) .execute(&pool) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; // Client resets connection -> Handler dropped -> Money is lost forever! sqlx::query!("INSERT INTO orders (user_id, amount) VALUES ($1, $2)", payload.user_id, payload.amount) .execute(&pool) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; Ok(StatusCode::CREATED) } ``` #### Production Standard (Correct) > **Standard**: Wrapping operations in a database transaction ensures ACID atomicity on drop, and wrapping the transaction inside `tokio::spawn` guarantees that execution continues to commit even if the client abruptly severs the HTTP connection. ```rust use axum::{extract::State, http::StatusCode, Json}; use sqlx::PgPool; use serde::Deserialize; #[derive(Deserialize)] pub struct OrderPayload { pub user_id: i64, pub amount: i64 } pub async fn checkout_handler( State(pool): State<PgPool>, Json(payload): Json<OrderPayload>, ) -> Result<StatusCode, StatusCode> { // PRODUCTION FIX: Critical multi-step mutation is executed inside an atomic transaction // and dispatched via a detached supervisor task insulated from client socket drops. let task = tokio::spawn(async move { let mut tx = pool.begin().await?; sqlx::query!("UPDATE accounts SET balance = balance - $1 WHERE id = $2", payload.amount, payload.user_id) .execute(&mut *tx) .await?; sqlx::query!("INSERT INTO orders (user_id, amount) VALUES ($1, $2)", payload.user_id, payload.amount) .execute(&mut *tx) .await?; tx.commit().await?; Ok::<(), sqlx::Error>(()) }); // Awaiting JoinHandle preserves client notification while guaranteeing // background completion even if the client disconnects. match task.await { Ok(Ok(())) => Ok(StatusCode::CREATED), Ok(Err(_)) => Err(StatusCode::INTERNAL_SERVER_ERROR), Err(_) => Err(StatusCode::INTERNAL_SERVER_ERROR), } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tokio Cancellation-Safe Async Handler Standard

Axum 0.8 Tokio Cancellation-Safe Async Handler Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict cancellation-safety invariants across Axum 0.8 HTTP handlers and Tokio async operations. Prevents orphan DB states, partial buffer flushes, and socket pool exhaustion when client connections terminate early or tokio::select! branches drop incomplete futures. Requires critical business mutations and database transactions to run within detached supervisor tasks or atomic linear sequences insulated from client transport lifecycle. 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: Running Non-Cancellation-Safe Database and External Mutations Directly in Client-Bound Tokio Futures 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	Running Non-Cancellation-Safe Database and External Mutations Directly in Client-Bound Tokio Futures	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 isolate state-mutating multi-step workflows from client connection termination using `tokio

Engineers MUST ALWAYS isolate state-mutating multi-step workflows from client connection termination using `tokio::spawn` or background queues.

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.