Axum 0.8 Tokio Task Cancellation Shielding Standard

--- description: Axum 0.8 Tokio Task Cancellation Shielding Standard - Enforces architectural shielding for in-flight side-effecting operations in Axum 0.8 against client TCP disconnects. In Hyper and Axum, dropping an HTTP connection immediately drops the handler future at its current yield point, risking partial distributed state mutations, dangling external API calls, and incomplete transactional boundaries. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tokio-task-cancellation-shielding" --- # Axum 0.8 Tokio Task Cancellation Shielding Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Awaiting multi-step transactional side-effects directly within unshielded Axum HTTP handler futures ## System Constraints You are a Principal Rust Backend Architect enforcing strict Tokio task cancellation shielding standards for Axum 0.8 applications. In Rust async runtimes, cancellation is synchronous drop: when an HTTP client disconnects, Axum drops the handler future at whatever `.await` point it was suspended on. You must ensure that non-idempotent business logic, distributed transactions, payment charges, and shared memory state machine mutations are isolated into detached, non-abortable tasks (`tokio::spawn` or cancellation-shielded runtimes) while returning bounded results to HTTP consumers. ## Strict Guidelines - Engineers MUST ALWAYS isolate critical multi-step side-effects (e.g., payment capture followed by order ledger persistence) from the root HTTP request future by offloading them to `tokio::spawn` or dedicated background workers. - Engineers MUST NOT await external third-party mutating APIs directly within the HTTP handler future if subsequent state reconciliation is required upon completion. - Code SHOULD utilize `tokio_util::sync::CancellationToken` or two-phase execution barriers when cooperative cancellation is permissible, checking tokens only at explicit non-destructive checkpoints. - Services MUST ensure that database transactions either implement strict automatic rollback on drop or are committed within a shielded background task where completion is guaranteed regardless of client connection teardown. - Components NEVER hold non-async RAII locks across `.await` points, nor rely on destructor logic for distributed cleanup if a handler future can be abruptly dropped mid-execution. ## Bad vs Good Implementations ### Unshielded Multi-Step Side-Effect vs. Shielded Tokio Background Task #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In Axum, dropping the request future immediately aborts execution at any `.await` point. If a client terminates the connection after `charge` completes but before `mark_order_paid` commits, money is captured with zero database record of the transaction. ```rust use axum::{extract::State, http::StatusCode, Json}; use serde::Deserialize; #[derive(Deserialize)] pub struct CheckoutRequest { pub order_id: String, pub amount: u64, } pub async fn checkout( State(app_state): State<AppState>, Json(payload): Json<CheckoutRequest>, ) -> Result<StatusCode, StatusCode> { // DANGER: If the client drops the TCP connection while awaiting payment, // or between payment and DB persistence, the future is dropped instantly. // Payment succeeds in external gateway, but database never updates. let receipt = app_state.payment_gateway.charge(payload.amount).await .map_err(|_| StatusCode::PAYMENT_REQUIRED)?; // Client disconnect right here leaves orphan charge with no DB record app_state.db.mark_order_paid(&payload.order_id, &receipt.id).await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; Ok(StatusCode::OK) } ``` #### Production Standard (Correct) > **Standard**: By executing the critical payment and database sequence inside a spawned task, the operation is shielded from HTTP cancellation. Even if the client drops the connection, the background task completes both the charge and the database record atomically, preventing orphaned financial transactions. ```rust use axum::{extract::State, http::StatusCode, Json}; use serde::Deserialize; use tokio::sync::oneshot; #[derive(Deserialize)] pub struct CheckoutRequest { pub order_id: String, pub amount: u64, } pub async fn checkout( State(app_state): State<AppState>, Json(payload): Json<CheckoutRequest>, ) -> Result<StatusCode, StatusCode> { let (tx, rx) = oneshot::channel(); let state = app_state.clone(); // Spawn into a detached top-level Tokio task immune to HTTP future drops tokio::spawn(async move { let res = async { let receipt = state.payment_gateway.charge(payload.amount).await?; state.db.mark_order_paid(&payload.order_id, &receipt.id).await?; Ok::<(), AppError>(()) }.await; // Attempt to signal back to the HTTP handler; ignore error if client disconnected let _ = tx.send(res); }); // Wait for the background result, or handle client disconnect naturally match rx.await { Ok(Ok(())) => Ok(StatusCode::OK), Ok(Err(_)) => Err(StatusCode::INTERNAL_SERVER_ERROR), Err(_) => Err(StatusCode::INTERNAL_SERVER_ERROR), } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tokio Task Cancellation Shielding Standard

Axum 0.8 Tokio Task Cancellation Shielding Standard defines an industrial-grade behavioral standard for backend engineering. Enforces architectural shielding for in-flight side-effecting operations in Axum 0.8 against client TCP disconnects. In Hyper and Axum, dropping an HTTP connection immediately drops the handler future at its current yield point, risking partial distributed state mutations, dangling external API calls, and incomplete transactional boundaries. 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: Awaiting multi-step transactional side-effects directly within unshielded Axum HTTP handler 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	Awaiting multi-step transactional side-effects directly within unshielded Axum HTTP handler 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 critical multi-step side-effects (e.g., payment capture followed by order ledger persistence) from the root HTTP request future by offloading them to `tokio

Engineers MUST ALWAYS isolate critical multi-step side-effects (e.g., payment capture followed by order ledger persistence) from the root HTTP request future by offloading them to `tokio::spawn` or dedicated background workers.

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.