Axum 0.8 Request Cancellation Propagation & Client Disconnect Abort Drain

--- description: Axum 0.8 Request Cancellation Propagation & Client Disconnect Abort Drain - Mandates that Axum 0.8 request handlers, Tower middleware, and downstream database operations strictly honor HTTP/2 and HTTP/3 RST_STREAM disconnect signals. Prevents compute leaks, database connection pool starvation, and phantom transactional writes by enforcing Tokio cancellation propagation and RAII rollback semantics. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-tower-cancellation-abort-drain" --- # Axum 0.8 Request Cancellation Propagation & Client Disconnect Abort Drain > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning Unlinked Background Tasks and Ignoring Stream Teardown in Long-Running Handlers ## System Constraints You are a Principal Rust Architect enforcing Axum 0.8 and Tower request lifecycle semantics. Mandate that all handlers, middleware, and IO pipelines cleanly abort execution when a client drops the connection or sends an HTTP/2 RST_STREAM. Disallow detached asynchronous tasks that outlive the client socket without an explicit, monitored background supervisor. ## Strict Guidelines - Engineers MUST ALWAYS keep request-scoped asynchronous tasks bound to the Axum handler future so Tokio runtime drops downstream operations when the client disconnects. - Engineers MUST NOT spawn detached `tokio::spawn` tasks inside handlers without explicitly linking them to a `tokio_util::sync::CancellationToken` or handling cooperative shutdown. - Database transactions MUST rely on RAII automatic rollback upon future drop, rather than executing deferred commits in detached background tasks. - Handlers executing long-lived CPU loops, external HTTP calls, or streaming bodies MUST cooperatively poll cancellation via `tokio::select!` or yield points. - Components NEVER swallow cancellation errors or convert premature socket closures into partial successful state transitions. ## Bad vs Good Implementations ### Axum 0.8 Client Disconnect & SQL Transaction Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Detaching the database transaction with `tokio::spawn` decouples execution from the hyper/axum connection lifecycle. When an HTTP/2 client aborts via RST_STREAM, Axum drops the handler future, but the spawned task continues executing, exhausting connection pools and causing phantom writes. ```rust use axum::{extract::State, http::StatusCode, response::IntoResponse, Json}; use serde::Deserialize; use sqlx::PgPool; #[derive(Deserialize)] pub struct OrderPayload { pub user_id: i64, pub amount: i64, } // ANTI-PATTERN: Spawning unlinked background tasks ignores RST_STREAM disconnects. // If the client cancels the HTTP/2 stream midway, this task continues burning // connection pool resources and commits orphaned records. pub async fn create_order( State(pool): State<PgPool>, Json(payload): Json<OrderPayload>, ) -> impl IntoResponse { tokio::spawn(async move { let mut tx = pool.begin().await.unwrap(); sqlx::query!( "INSERT INTO orders (user_id, amount) VALUES ($1, $2)", payload.user_id, payload.amount ) .execute(&mut *tx) .await .unwrap(); // Lengthy third-party verification simulates high latency tokio::time::sleep(std::time::Duration::from_secs(5)).await; tx.commit().await.unwrap(); }); StatusCode::ACCEPTED } ``` #### Production Standard (Correct) > **Standard**: By executing the transaction directly within the handler's asynchronous lifecycle, any client-side RST_STREAM or socket termination drops the active future. Rust's RAII drop semantics guarantee that the `sqlx::Transaction` drops before commit, safely aborting downstream IO and returning the connection to the pool. ```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 OrderPayload { pub user_id: i64, pub amount: i64, } // PRODUCTION FIX: The future remains strictly inlined to the Axum handler. // If the client disconnects (RST_STREAM), hyper drops the handler future, // immediately dropping `tx` and triggering automatic PostgreSQL rollback via RAII. pub async fn create_order( State(pool): State<PgPool>, Json(payload): Json<OrderPayload>, ) -> Result<impl IntoResponse, StatusCode> { let mut tx = pool.begin().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; sqlx::query!( "INSERT INTO orders (user_id, amount) VALUES ($1, $2)", payload.user_id, payload.amount ) .execute(&mut *tx) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; // If client disconnects during this await, the entire stack frame unwinds, // dropping `tx` before commit, reliably rolling back uncommitted DB mutations. tokio::time::sleep(std::time::Duration::from_secs(5)).await; tx.commit().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; Ok((StatusCode::CREATED, Json(serde_json::json!({ "status": "completed" })))) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Request Cancellation Propagation & Client Disconnect Abort Drain

Axum 0.8 Request Cancellation Propagation & Client Disconnect Abort Drain defines an industrial-grade behavioral standard for backend engineering. Mandates that Axum 0.8 request handlers, Tower middleware, and downstream database operations strictly honor HTTP/2 and HTTP/3 RST_STREAM disconnect signals. Prevents compute leaks, database connection pool starvation, and phantom transactional writes by enforcing Tokio cancellation propagation and RAII rollback semantics. 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: Spawning Unlinked Background Tasks and Ignoring Stream Teardown in Long-Running Handlers 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	Spawning Unlinked Background Tasks and Ignoring Stream Teardown in Long-Running Handlers	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 keep request-scoped asynchronous tasks bound to the Axum handler future so Tokio runtime drops downstream operations when the client disconnects.

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.