Axum 0.8 Tower Leaf-Node Request Cancellation and Socket Drain Invariant

--- description: Axum 0.8 Tower Leaf-Node Request Cancellation and Socket Drain Invariant - Enforces deterministic downstream socket cleanup and prevents orphaned Tokio task leaks when HTTP/3 client streams abort mid-flight during backpressured operations. Mandates explicit cancellation propagation via tokens and guards across Tower leaf services and decoupled background tasks. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tower-request-cancellation-drain" --- # Axum 0.8 Tower Leaf-Node Request Cancellation and Socket Drain Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning Unmonitored Tokio Tasks and Ignoring Stream Abort Drops in Axum Request Pipelines ## System Constraints You are a Principal Systems Engineer enforcing strict cancellation propagation and deterministic resource drainage in Axum 0.8 and Tower service architectures. Ensure zero orphaned background tasks when HTTP/3 or HTTP/2 client streams reset mid-execution. ## Strict Guidelines - Engineers MUST ALWAYS link asynchronous background execution to the incoming request lifecycle using `tokio_util::sync::CancellationToken` or scoped task groups. - Engineers MUST NOT invoke raw `tokio::spawn` for request-scoped work without wiring cancellation listeners to detect HTTP/3 `RST_STREAM` or socket drops. - Code SHOULD wrap streaming response bodies and channel publishers with RAII drop guards to drain or close underlying resources immediately upon client disconnect. - Services MUST monitor request future cancellation within backpressured processing loops using `tokio::select!` or cancellation-aware streams. - Components NEVER assume intermediate database transactions or external RPCs abort automatically when an Axum handler future is dropped by Tower. ## Bad vs Good Implementations ### Streaming Response Processing with Cancellation Propagation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When an HTTP/3 client stream aborts mid-flight, Axum drops the outer response future, but the background worker task spawned via tokio::spawn continues to consume CPU and DB resources until the buffer fills and tx.send fails, leaking resources under heavy backpressure. ```rust use axum::{extract::Request, response::IntoResponse}; use tokio::sync::mpsc; use tokio_stream::wrappers::ReceiverStream; pub async fn handler(req: Request) -> impl IntoResponse { let (tx, rx) = mpsc::channel(16); // ANTI-PATTERN: Orphaned task running indefinitely if client resets stream tokio::spawn(async move { for i in 0..10_000 { // Heavy computation / DB pull continuing after HTTP/3 client disconnects tokio::time::sleep(std::time::Duration::from_millis(50)).await; if tx.send(format!("chunk {}\n", i)).await.is_err() { break; } } }); axum::response::Body::from_stream(ReceiverStream::new(rx)) } ``` #### Production Standard (Correct) > **Standard**: Using a CancellationToken paired with an RAII drop_guard attached to the streaming body ensures that as soon as Axum/Tower drops the response future due to an HTTP/3 stream cancellation, the background Tokio task is notified instantly and terminates without orphan latency. ```rust use axum::{extract::Request, response::IntoResponse}; use tokio::sync::mpsc; use tokio_stream::wrappers::ReceiverStream; use tokio_util::sync::CancellationToken; pub async fn handler(req: Request) -> impl IntoResponse { let (tx, rx) = mpsc::channel(16); let token = CancellationToken::new(); let child_token = token.clone(); // Guard automatically triggers cancellation token when response stream is dropped let drop_guard = token.drop_guard(); tokio::spawn(async move { for i in 0..10_000 { tokio::select! { biased; _ = child_token.cancelled() => { // Explicit leaf-node pipeline drainage tracing::info!("Client stream aborted: halting worker task cleanly"); break; } _ = tokio::time::sleep(std::time::Duration::from_millis(50)) => { if tx.send(format!("chunk {}\n", i)).await.is_err() { break; } } } } }); let stream = ReceiverStream::new(rx); // Attach drop guard to response lifecycle axum::response::Body::from_stream(async_stream::stream! { let _guard = drop_guard; for await item in stream { yield Ok::<_, std::io::Error>(item); } }) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tower Leaf-Node Request Cancellation and Socket Drain Invariant

Axum 0.8 Tower Leaf-Node Request Cancellation and Socket Drain Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic downstream socket cleanup and prevents orphaned Tokio task leaks when HTTP/3 client streams abort mid-flight during backpressured operations. Mandates explicit cancellation propagation via tokens and guards across Tower leaf services and decoupled background tasks. 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 Unmonitored Tokio Tasks and Ignoring Stream Abort Drops in Axum Request Pipelines 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 Unmonitored Tokio Tasks and Ignoring Stream Abort Drops in Axum Request Pipelines	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 asynchronous background execution to the incoming request lifecycle using `tokio_util

Engineers MUST ALWAYS link asynchronous background execution to the incoming request lifecycle using `tokio_util::sync::CancellationToken` or scoped task groups.

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.