Axum 0.8 Tokio Cooperative Task Budgeting & Deterministic Cancellation

--- description: Axum 0.8 Tokio Cooperative Task Budgeting & Deterministic Cancellation - Enforces deterministic cancellation and resource cleanup across Axum 0.8 and Tower middleware chains during abrupt client disconnects under heavy load. Mandates cooperative task budgeting, cancellation-safe transactional state machines, and hierarchical token propagation to prevent resource leaks, zombie background tasks, and connection pool exhaustion. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-tokio-cooperative-cancellation-standard" --- # Axum 0.8 Tokio Cooperative Task Budgeting & Deterministic Cancellation > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unattached Background Spawning and Cancellation-Unsafe Async State Transitions Leading to Connection Leaks and Zombie Work ## System Constraints You are a Principal Rust Systems Architect specializing in high-throughput network services with Axum 0.8 and Tokio. Your responsibility is to strictly enforce cooperative task budgeting, deterministic cancellation semantics, and robust resource cleanup across Tower middleware chains and Axum request pipelines. When clients disconnect prematurely, handlers must terminate synchronously or orchestrate safe rollback without leaving orphaned async tasks, leaked database handles, or corrupted shared memory. ## Strict Guidelines - Engineers MUST ALWAYS bind detached async background work to a parent `tokio_util::sync::CancellationToken` or handle lifecycle termination via `tokio::task::JoinHandle` abort handles. - Engineers MUST NOT invoke fire-and-forget `tokio::spawn` within Axum route handlers for state-mutating operations without explicit rollback guards or completion guarantees. - Handlers executing compute-intensive or unbounded iteration MUST yield cooperatively via `tokio::task::yield_now().await` or `tokio::task::consume_budget().await` to maintain event-loop responsiveness. - Services MUST ensure all multi-step transactional operations (e.g., SQL transactions, distributed locks) utilize RAII rollback guards that execute clean teardown if a client disconnect drops the future at an `.await` boundary. - Middleware and streaming endpoints MUST verify body consumption and channel write outcomes to promptly detect client disconnects (`io::ErrorKind::BrokenPipe` / `ConnectionReset`) and halt downstream processing immediately. - Handlers MUST NEVER use cancellation-unsafe primitives inside `tokio::select!` branches where dropping a branch future causes state desynchronization or unreturned pool connections. ## Bad vs Good Implementations ### Cancellation Safety and Background Work Binding in Axum Handlers #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: If the client disconnects while awaiting the database or intermediate async calls, the future is abruptly dropped. Without structured cancellation and explicit budget yielding, spawned background tasks run unconstrained without a cancellation token, resulting in phantom execution, pool contention, and memory pressure. ```rust use axum::{extract::State, http::StatusCode, response::IntoResponse, Json}; use serde::Deserialize; use std::sync::Arc; #[derive(Deserialize)] pub struct OrderRequest { pub user_id: u64, pub amount: u64 } pub struct AppState { pub db: sqlx::PgPool } pub async fn place_order( State(state): State<Arc<AppState>>, Json(payload): Json<OrderRequest>, ) -> Result<impl IntoResponse, StatusCode> { // ANTI-PATTERN: Client disconnect drops handler future before commit, // or spawns unbounded background task that outlives context without cancellation coordination. let mut tx = state.db.begin().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; sqlx::query!("UPDATE accounts SET balance = balance - $1 WHERE id = $2", payload.amount as i64, payload.user_id as i64) .execute(&mut *tx) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; // Fire-and-forget task continues running even if client severed connection; // leaks resources under heavy load and cannot be throttled or tracked. tokio::spawn(async move { // Heavy external reporting / audit logging std::thread::sleep(std::time::Duration::from_millis(500)); }); tx.commit().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; Ok(StatusCode::CREATED) } ``` #### Production Standard (Correct) > **Standard**: Leverages transactional RAII cleanup to guarantee that connection handles roll back if the client abruptly drops the future. It uses `tokio::task::consume_budget()` to cooperatively yield scheduler control and ties concurrent background tasks to a hierarchical `CancellationToken`. ```rust use axum::{extract::State, http::StatusCode, response::IntoResponse, Json}; use serde::Deserialize; use std::sync::Arc; use tokio_util::sync::CancellationToken; #[derive(Deserialize)] pub struct OrderRequest { pub user_id: u64, pub amount: u64 } pub struct AppState { pub db: sqlx::PgPool, pub cancel_token: CancellationToken, } pub async fn place_order( State(state): State<Arc<AppState>>, Json(payload): Json<OrderRequest>, ) -> Result<impl IntoResponse, StatusCode> { let child_token = state.cancel_token.child_token(); // RAII Transaction: sqlx::Transaction automatically triggers ROLLBACK on drop // if dropped prematurely due to client cancellation. let mut tx = state.db.begin().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; sqlx::query!( "UPDATE accounts SET balance = balance - $1 WHERE id = $2", payload.amount as i64, payload.user_id as i64 ) .execute(&mut *tx) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; // Enforce cooperative budgeting before final non-idempotent commit tokio::task::consume_budget().await; tx.commit().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; // Structured asynchronous job propagation respecting server shutdown and request boundaries let audit_token = child_token.clone(); tokio::spawn(async move { tokio::select! { _ = audit_token.cancelled() => { tracing::warn!("Audit logging aborted due to cancellation signal"); } _ = perform_audit_log(payload.user_id, payload.amount) => { tracing::info!("Audit log committed successfully"); } } }); Ok(StatusCode::CREATED) } async fn perform_audit_log(_user_id: u64, _amount: u64) { tokio::task::yield_now().await; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tokio Cooperative Task Budgeting & Deterministic Cancellation

Axum 0.8 Tokio Cooperative Task Budgeting & Deterministic Cancellation defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic cancellation and resource cleanup across Axum 0.8 and Tower middleware chains during abrupt client disconnects under heavy load. Mandates cooperative task budgeting, cancellation-safe transactional state machines, and hierarchical token propagation to prevent resource leaks, zombie background tasks, and connection pool exhaustion. 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: Unattached Background Spawning and Cancellation-Unsafe Async State Transitions Leading to Connection Leaks and Zombie Work 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	Unattached Background Spawning and Cancellation-Unsafe Async State Transitions Leading to Connection Leaks and Zombie Work	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 detached async background work to a parent `tokio_util

Engineers MUST ALWAYS bind detached async background work to a parent `tokio_util::sync::CancellationToken` or handle lifecycle termination via `tokio::task::JoinHandle` abort handles.

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.