Axum 0.8 State Extractors & Tokio Task Cooperative Cancellation Barrier

--- description: Axum 0.8 State Extractors & Tokio Task Cooperative Cancellation Barrier - Enforces deterministic cancellation boundaries across Axum 0.8 request pipelines and background Tokio worker tasks. Prevents orphaned database transactions, unbounded I/O streams, and thread starvation when HTTP/3 clients abruptly drop connections or trigger stream resets (RST_STREAM). Mandates RAII rollback guards and explicit tokio_util::sync::CancellationToken propagation across async boundaries. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tokio-cooperative-cancellation-barrier" --- # Axum 0.8 State Extractors & Tokio Task Cooperative Cancellation Barrier > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Orphaned Tokio Tasks and Leaked Connection Handles on Abrupt HTTP/3 Client Resets ## System Constraints You are a Principal Rust Concurrency Architect enforcing Axum 0.8 State Extractors & Tokio Task Cooperative Cancellation Barriers. You must ensure all asynchronous stream iterations, downstream database handles, and background task handoffs implement strict cooperative cancellation using CancellationToken or explicit select! boundaries, preventing unbounded task runs and leaked database pool handles when HTTP client connections abort. ## Strict Guidelines - Engineers MUST ALWAYS bind child Tokio tasks to a tokio_util::sync::CancellationToken derived from the parent Axum request lifecycle or an explicit drop barrier. - Engineers MUST NOT spawn unbounded background tasks via tokio::spawn without retaining an abort handle or wiring a cooperative cancellation barrier. - Database transactions in async handlers MUST use explicit RAII-guarded types (e.g., sqlx::Transaction) or ensure rollback occurs deterministically on future cancellation. - Handlers consuming or producing infinite or chunked async streams MUST wrap processing loops in tokio::select! against cancellation tokens or client disconnect signals. - Components NEVER assume drop completion happens at intermediate async yield points (.await) without deterministic cleanup guards (Drop guards). ## Bad vs Good Implementations ### Unbounded Task Spawning vs Cooperative CancellationToken Barrier in Axum Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawning detached tasks via tokio::spawn without passing a CancellationToken or retaining a JoinHandle completely decouples execution from client connection state. In HTTP/3, sudden network drops or stream resets leave database pool connections pinned in indefinite, detached loops, exhausting the connection pool. ```rust use axum::{extract::State, Json}; use std::sync::Arc; pub struct AppState { pub pool: sqlx::PgPool, } pub async fn process_job( State(state): State<Arc<AppState>>, Json(payload): Json<Vec<i64>>, ) -> &'static str { // ANTI-PATTERN: Fire-and-forget task without cancellation token or abort handle. // If HTTP/3 client sends RST_STREAM, the spawned task continues executing, // pinning a database connection from the pool and executing phantom writes. tokio::spawn(async move { let mut tx = state.pool.begin().await.unwrap(); for id in payload { sqlx::query("UPDATE items SET processed = true WHERE id = $1") .bind(id) .execute(&mut *tx) .await .unwrap(); tokio::time::sleep(tokio::time::Duration::from_millis(50)).await; } tx.commit().await.unwrap(); }); "Job Enqueued" } ``` #### Production Standard (Correct) > **Standard**: Creates a child CancellationToken connected to application shutdown and lifecycle barriers, runs within a TaskTracker, and bounds stream writes inside a biased tokio::select!. If cancelled, execution breaks immediately and the uncommitted transaction drops, safely executing an automatic SQL rollback. ```rust use axum::{extract::State, http::StatusCode, response::IntoResponse, Json}; use std::sync::Arc; use tokio_util::sync::CancellationToken; use tokio_util::task::TaskTracker; pub struct AppState { pub pool: sqlx::PgPool, pub tracker: TaskTracker, pub global_cancel: CancellationToken, } pub async fn process_job( State(state): State<Arc<AppState>>, Json(payload): Json<Vec<i64>>, ) -> Result<&'static str, (StatusCode, &'static str)> { let child_token = state.global_cancel.child_token(); let pool = state.pool.clone(); // PRODUCTION FIX: Task is tracked, cooperatively cancelled, and uses RAII rollback state.tracker.spawn({ let token = child_token.clone(); async move { let mut tx = match pool.begin().await { Ok(tx) => tx, Err(_) => return, }; for id in payload { tokio::select! { biased; _ = token.cancelled() => { // Transaction is dropped here without commit, triggering automatic rollback return; } res = sqlx::query("UPDATE items SET processed = true WHERE id = $1") .bind(id) .execute(&mut *tx) => { if res.is_err() { return; } } } tokio::time::sleep(tokio::time::Duration::from_millis(50)).await; } let _ = tx.commit().await; } }); Ok("Job Enqueued") } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 State Extractors & Tokio Task Cooperative Cancellation Barrier

Axum 0.8 State Extractors & Tokio Task Cooperative Cancellation Barrier defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic cancellation boundaries across Axum 0.8 request pipelines and background Tokio worker tasks. Prevents orphaned database transactions, unbounded I/O streams, and thread starvation when HTTP/3 clients abruptly drop connections or trigger stream resets (RST_STREAM). Mandates RAII rollback guards and explicit tokio_util::sync::CancellationToken propagation across async 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: Orphaned Tokio Tasks and Leaked Connection Handles on Abrupt HTTP/3 Client Resets 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	Orphaned Tokio Tasks and Leaked Connection Handles on Abrupt HTTP/3 Client Resets	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 bind child Tokio tasks to a tokio_util

Engineers MUST ALWAYS bind child Tokio tasks to a tokio_util::sync::CancellationToken derived from the parent Axum request lifecycle or an explicit drop barrier.

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.