Axum 0.8 Tokio CancellationToken Stream Termination & Task Leak Prevention

--- description: Axum 0.8 Tokio CancellationToken Stream Termination & Task Leak Prevention - Mandates proactive runtime cancellation token propagation across Axum 0.8 handlers and Tower middleware layers to guarantee immediate task termination upon HTTP/3 stream cancellation. Eliminates unbounded CPU and memory leaks caused by orphaned Tokio tasks executing past client disconnections or QUIC stream resets. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-cancellation-token-stream-termination" --- # Axum 0.8 Tokio CancellationToken Stream Termination & Task Leak Prevention > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning Unbounded Tokio Worker Tasks Detached From HTTP/3 Stream Drop Lifecycles ## System Constraints You are a Principal Systems Engineer enforcing strict cancellation and resource cleanup invariants across Axum 0.8 and Tokio ecosystems. In HTTP/3 and HTTP/2 architectures, stream resets and client disconnections drop response streams abruptly without closing TCP connections. You must mandate that every spawned asynchronous worker, database cursor, and Tower middleware stream links to a tokio_util::sync::CancellationToken or an RAII drop guard that aborts execution instantaneously upon disconnect. ## Strict Guidelines - Engineers MUST ALWAYS bind long-running background routines and SSE/chunked streams to a tokio_util::sync::CancellationToken child instance tied to the request/stream lifecycle. - Engineers MUST NOT call tokio::spawn inside Axum handlers without passing a CancellationToken or retaining a JoinHandle managed by an RAII cancellation drop guard. - Handlers MUST leverage tokio::select! with biased execution prioritizing token.cancelled() over ongoing compute or I/O operations. - Tower middleware that tracks state across streaming request or response bodies MUST register stream drop hooks to proactively trigger downstream cancellation tokens. - Asynchronous services MUST NEVER rely solely on mpsc channel send failure as a primary disconnect detector, as buffered channels delay termination until buffers saturate. ## Bad vs Good Implementations ### HTTP/3 Streaming Handler Task Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: When an HTTP/3 stream is aborted, the receiver drops, but the spawned task remains alive until buffer exhaustion. If the loop executes heavy asynchronous side effects before calling `tx.send`, the orphaned task consumes server CPU and database connections indefinitely. ```rust use axum::{response::sse::{Event, Sse}, routing::get, Router}; use futures::stream::Stream; use std::{convert::Infallible, time::Duration}; pub async fn bad_stream_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let (tx, rx) = tokio::sync::mpsc::channel(100); // ANTI-PATTERN: Detached task with no cancellation tracking. // When an HTTP/3 client resets the stream, rx drops, but this worker continues // executing heavy compute/IO until the mpsc channel capacity (100) fills up. tokio::spawn(async move { let mut ticker = tokio::time::interval(Duration::from_millis(50)); loop { ticker.tick().await; // Heavy external database query or compute continues running let payload = format!("data: {}", std::time::SystemTime::now().elapsed().unwrap().as_nanos()); if tx.send(Ok(Event::default().data(payload))).await.is_err() { break; } } }); Sse::new(tokio_stream::wrappers::ReceiverStream::new(rx)) } ``` #### Production Standard (Correct) > **Standard**: Binds stream lifecycle to a `StreamGuard` containing a `CancellationToken`. As soon as the HTTP/3 connection drops or Axum aborts the response stream, the guard's `Drop` implementation cancels the child token, instantly terminating the spawned Tokio task via `tokio::select! biased`. ```rust use axum::response::sse::{Event, Sse}; use futures::stream::Stream; use std::{convert::Infallible, time::Duration}; use tokio_util::sync::CancellationToken; use tokio_stream::wrappers::ReceiverStream; struct StreamGuard { token: CancellationToken, } impl Drop for StreamGuard { fn drop(&mut self) { self.token.cancel(); } } pub async fn good_stream_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let token = CancellationToken::new(); let child_token = token.child_token(); let guard = StreamGuard { token }; let (tx, rx) = tokio::sync::mpsc::channel(1); // PRODUCTION INVARIANT: Task explicitly monitors cancellation token alongside work. tokio::spawn(async move { let mut ticker = tokio::time::interval(Duration::from_millis(50)); loop { tokio::select! { biased; _ = child_token.cancelled() => { // Client reset the HTTP/3 stream; abort work immediately break; } _ = ticker.tick() => { let payload = format!("data: {}", std::time::SystemTime::now().elapsed().unwrap().as_nanos()); if tx.send(Ok(Event::default().data(payload))).await.is_err() { break; } } } } }); // When the HTTP/3 connection drops, Axum drops the stream, firing the guard's Drop impl. let stream = ReceiverStream::new(rx); let mapped_stream = futures::stream::unfold((stream, guard), |(mut s, g)| async move { use futures::StreamExt; s.next().await.map(|item| (item, (s, g))) }); Sse::new(mapped_stream) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tokio CancellationToken Stream Termination & Task Leak Prevention

Axum 0.8 Tokio CancellationToken Stream Termination & Task Leak Prevention defines an industrial-grade behavioral standard for backend engineering. Mandates proactive runtime cancellation token propagation across Axum 0.8 handlers and Tower middleware layers to guarantee immediate task termination upon HTTP/3 stream cancellation. Eliminates unbounded CPU and memory leaks caused by orphaned Tokio tasks executing past client disconnections or QUIC stream resets. 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 Unbounded Tokio Worker Tasks Detached From HTTP/3 Stream Drop Lifecycles 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 Unbounded Tokio Worker Tasks Detached From HTTP/3 Stream Drop Lifecycles	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 long-running background routines and SSE/chunked streams to a tokio_util

Engineers MUST ALWAYS bind long-running background routines and SSE/chunked streams to a tokio_util::sync::CancellationToken child instance tied to the request/stream 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.