Axum 0.8 Cooperative Task Cancellation and Downstream Abort Propagation

--- description: Axum 0.8 Cooperative Task Cancellation and Downstream Abort Propagation - Enforces deterministic cancellation token propagation and drop semantics across Axum 0.8 and Tower service stacks. Guarantees that TCP socket disconnects and downstream HTTP aborts immediately terminate in-flight database queries, external RPCs, and asynchronous worker tasks to prevent unmetered compute drain and resource pool exhaustion. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-cancellation-token-downstream-abort-propagation" --- # Axum 0.8 Cooperative Task Cancellation and Downstream Abort Propagation > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Detached Background Spawning and Ignored Future Drops Inducing Phantom Compute and Connection Leaks ## System Constraints You are a Principal Rust Distributed Systems Engineer enforcing strict cancellation-token and drop-safety invariants in Axum 0.8 and Tokio ecosystems. Every asynchronous handler, Tower middleware, and background worker must actively propagate or bind to client disconnect signals. You must prevent detached async tasks, unmonitored future detachment, and non-cancellable database queries when downstream HTTP clients disconnect. ## Strict Guidelines - Engineers MUST ALWAYS link long-running or resource-intensive handlers to a `tokio_util::sync::CancellationToken` attached to the request or client connection lifecycle. - Engineers MUST NOT use unanchored `tokio::spawn` within Axum handlers for operations intended to serve the immediate request lifecycle; child work must be bounded via `tokio::select!` or task trackers tied to cancellation. - Services MUST propagate cancellation tokens into database drivers (e.g., passing cancellation-aware futures to SQLx queries) so that aborts actively terminate PostgreSQL/MySQL backend operations via connection drop or query cancellation. - Middleware layers MUST implement drop-safe forwarders: if an upstream Tower layer drops the inner service future, resources must clean up deterministically via RAII guards or `scopeguard`. - Components NEVER ignore future drop cancellation contracts when using external sync blocks or blocking threads; `tokio::task::spawn_blocking` must be paired with explicit abort or timeout monitors. ## Bad vs Good Implementations ### Cancellation Token Propagation in Axum 0.8 Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawning an unanchored tokio task isolates execution from the handler's future lifecycle. If the client disconnects or times out, the Axum request future is dropped, but the spawned task continues executing expensive queries against the database pool indefinitely, creating phantom compute load. ```rust use axum::{extract::State, response::Json}; use std::sync::Arc; pub async fn search_handler( State(pool): State<Arc<sqlx::PgPool>>, Json(payload): Json<SearchQuery>, ) -> Result<Json<Vec<SearchResult>>, StatusCode> { // ANTI-PATTERN: Spawns detached work that continues running // to completion even if the HTTP client disconnects immediately. let handle = tokio::spawn(async move { heavy_database_search(&pool, payload).await }); let results = handle.await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; Ok(Json(results)) } ``` #### Production Standard (Correct) > **Standard**: The handler registers a `CancellationToken` tied to the connection lifecycle and uses `tokio::select!` to race client cancellation against the query. If the client disconnects, execution terminates immediately, dropping the query future and allowing the database pool connection to clean up without phantom query execution. ```rust use axum::{extract::{Extension, State}, http::StatusCode, response::Json}; use std::sync::Arc; use tokio_util::sync::CancellationToken; pub async fn search_handler( State(pool): State<Arc<sqlx::PgPool>>, Extension(token): Extension<CancellationToken>, Json(payload): Json<SearchQuery>, ) -> Result<Json<Vec<SearchResult>>, StatusCode> { // INVARIANT: Cooperative cancellation race with downstream disconnect. // In Axum, future drop already cancels un-spawned futures, but using an explicit // CancellationToken allows shared child cancellation across complex multi-step pipelines. tokio::select! { _ = token.cancelled() => { tracing::warn!("Client aborted connection; cancelling downstream query execution"); Err(StatusCode::from_u16(499).unwrap_or(StatusCode::BAD_REQUEST)) } result = heavy_database_search(&pool, payload) => { let data = result.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; Ok(Json(data)) } } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Cooperative Task Cancellation and Downstream Abort Propagation

Axum 0.8 Cooperative Task Cancellation and Downstream Abort Propagation defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic cancellation token propagation and drop semantics across Axum 0.8 and Tower service stacks. Guarantees that TCP socket disconnects and downstream HTTP aborts immediately terminate in-flight database queries, external RPCs, and asynchronous worker tasks to prevent unmetered compute drain and resource 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: Detached Background Spawning and Ignored Future Drops Inducing Phantom Compute and Connection Leaks 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	Detached Background Spawning and Ignored Future Drops Inducing Phantom Compute and Connection Leaks	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 link long-running or resource-intensive handlers to a `tokio_util

Engineers MUST ALWAYS link long-running or resource-intensive handlers to a `tokio_util::sync::CancellationToken` attached to the request or client connection lifecycle.

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.