Axum 0.8 & Hyper 1.x Cooperative Request Cancellation Propagation

--- description: Axum 0.8 & Hyper 1.x Cooperative Request Cancellation Propagation - Enforces deterministic cancellation propagation across asynchronous boundaries in Axum 0.8 and Hyper 1.x services. Prevents orphaned compute and connection pool exhaustion by binding subtasks and database operations to client socket drop lifecycles using structured cancellation tokens and RAII drop guards. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-hyper-cooperative-cancellation-propagation" --- # Axum 0.8 & Hyper 1.x Cooperative Request Cancellation Propagation > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Detached background execution and unlinked Tokio spawns running after HTTP client disconnection ## System Constraints You are a Principal Rust Systems Architect enforcing cooperative cancellation and resource isolation in Axum 0.8 and Hyper 1.x services. You must reject any unbounded concurrency, unlinked background tasks, or database queries that fail to abort when the client terminates the HTTP connection. ## Strict Guidelines - Engineers MUST ALWAYS propagate a `tokio_util::sync::CancellationToken` or rely on future drop semantics (RAII) for synchronous cancellation down to database drivers and I/O tasks. - Engineers MUST NOT call `tokio::spawn` directly inside request handlers without linking the spawned task's lifecycle via an abort handle or child `CancellationToken` (because `JoinHandle::drop` detaches rather than aborts). - Code MUST use `tokio::select!` cautiously with cancellation-safe futures, ensuring stateful streams or transactions are not dropped in corrupted mid-states. - Services MUST configure database drivers (e.g., SQLx, Deadpool) with aggressive cancellation awareness or explicit statement timeouts to release pool connections when handler futures drop. - Components NEVER execute unbound compute-heavy loops without invoking `tokio::task::yield_now()` or periodically checking `cancellation_token.is_cancelled()`. ## Bad vs Good Implementations ### Cooperative Task Abort via Drop Guards vs Detached Fire-and-Forget #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: In Tokio, dropping a `JoinHandle` does not cancel the underlying task; it detaches it. When a Hyper/Axum client aborts an in-flight HTTP request, the top-level handler future is dropped, but the spawned task continues to execute against PostgreSQL, exhausting pool connections and compute resources. ```rust use axum::{extract::State, http::StatusCode, response::IntoResponse, Json}; use serde::Deserialize; use sqlx::PgPool; #[derive(Deserialize)] pub struct ReportQuery { pub report_id: i64 } pub async fn generate_report( State(pool): State<PgPool>, Json(query): Json<ReportQuery>, ) -> Result<impl IntoResponse, StatusCode> { // ANTI-PATTERN: `tokio::spawn` detaches on drop. // If the client disconnects, Axum drops `generate_report`, but this task // continues executing in the background, consuming CPU and DB connections. let join_handle = tokio::spawn(async move { sqlx::query!("SELECT pg_sleep(30), heavy_compute($1)", query.report_id) .fetch_one(&pool) .await }); match join_handle.await { Ok(Ok(_)) => Ok(StatusCode::OK), _ => Err(StatusCode::INTERNAL_SERVER_ERROR), } } ``` #### Production Standard (Correct) > **Standard**: A `CancellationToken::drop_guard()` triggers when the client disconnects and Axum drops the parent future. The spawned task races its database query against `child_token.cancelled()`, immediately terminating execution and releasing database and memory resources. ```rust use axum::{extract::State, http::StatusCode, response::IntoResponse, Json}; use serde::Deserialize; use sqlx::PgPool; use tokio_util::sync::CancellationToken; #[derive(Deserialize)] pub struct ReportQuery { pub report_id: i64 } pub async fn generate_report( State(pool): State<PgPool>, Json(query): Json<ReportQuery>, ) -> Result<impl IntoResponse, StatusCode> { let token = CancellationToken::new(); let child_token = token.child_token(); // RAII guard ensuring subtask cancellation when handler drops let _drop_guard = token.drop_guard(); let mut join_handle = tokio::spawn(async move { tokio::select! { _ = child_token.cancelled() => { // Perform fast deterministic cleanup if necessary Err(sqlx::Error::PoolClosed) } res = sqlx::query!("SELECT heavy_compute($1)", query.report_id).fetch_one(&pool) => { res } } }); match (&mut join_handle).await { Ok(Ok(_)) => Ok(StatusCode::OK), Ok(Err(_)) => Err(StatusCode::REQUEST_TIMEOUT), Err(e) if e.is_cancelled() => Err(StatusCode::SERVICE_UNAVAILABLE), Err(_) => Err(StatusCode::INTERNAL_SERVER_ERROR), } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 & Hyper 1.x Cooperative Request Cancellation Propagation

Axum 0.8 & Hyper 1.x Cooperative Request Cancellation Propagation defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic cancellation propagation across asynchronous boundaries in Axum 0.8 and Hyper 1.x services. Prevents orphaned compute and connection pool exhaustion by binding subtasks and database operations to client socket drop lifecycles using structured cancellation tokens and RAII drop guards. 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 execution and unlinked Tokio spawns running after HTTP client disconnection 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 execution and unlinked Tokio spawns running after HTTP client disconnection	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 propagate a `tokio_util

Engineers MUST ALWAYS propagate a `tokio_util::sync::CancellationToken` or rely on future drop semantics (RAII) for synchronous cancellation down to database drivers and I/O tasks.

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.