Axum 0.8 Streaming Extractor Task Cancellation Barrier

--- description: Axum 0.8 Streaming Extractor Task Cancellation Barrier - Mandates deterministic cancellation boundaries for all Axum 0.8 streaming responses, SSE, and WebSocket loops. When hyper drops an active response stream upon client disconnect, detached background worker tasks must be proactively terminated via CancellationToken or RAII drop guards to prevent unbounded memory and thread leaks. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-streaming-cancellation-barrier" --- # Axum 0.8 Streaming Extractor Task Cancellation Barrier > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning Detached Background Producers Without Cancellation Barriers in Streaming Handlers ## System Constraints You are a Principal Rust Concurrency Architect enforcing Axum 0.8 streaming safety. Abrupt client disconnects drop hyper response streams; you must guarantee no background task continues executing orphaned asynchronous workloads, holding database connections, or exhausting thread pools. ## Strict Guidelines - Engineers MUST ALWAYS couple background stream producers to a `tokio_util::sync::CancellationToken` or an RAII `AbortHandle` drop guard. - Engineers MUST NOT spawn detached `tokio::spawn` loops inside SSE or WebSocket handlers without a reciprocal client termination listener. - Code SHOULD prefer `async_stream::try_stream!` or `futures::stream::unfold` where stream cancellation natively drops the generator future without manual task synchronization. - Services MUST ensure that channels transmitting streaming chunks to Axum response adapters yield early exits when `Sender::send` or `Sender::reserve` returns `SendError`. - Components NEVER rely on TCP keep-alive or slow-disconnect timeouts to cleanup leaked generator tasks. ## Bad vs Good Implementations ### SSE Response Task Leak vs RAII Cancellation Guard #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Hyper drops `ReceiverStream` when the client terminates the connection, but `state.expensive_database_cursor().await` blocks independently inside a detached tokio task. The worker leaks active DB handles, CPU cycles, and memory until completion. ```rust use axum::{extract::State, response::sse::{Event, Sse}}; use futures::stream::Stream; use std::convert::Infallible; use tokio::sync::mpsc; use tokio_stream::wrappers::ReceiverStream; pub async fn handler_bad(State(state): State<AppState>) -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let (tx, rx) = mpsc::channel(32); // ANTI-PATTERN: Detached task spawned with no cancellation token. // If client disconnects immediately, expensive DB queries and remote LLM tokens // continue executing until the buffer fills and send fails, or indefinitely if blocked on I/O. tokio::spawn(async move { while let Some(item) = state.expensive_database_cursor().await { let _ = tx.send(Ok(Event::default().data(item))).await; } }); Sse::new(ReceiverStream::new(rx)) } ``` #### Production Standard (Correct) > **Standard**: Using a `DropGuard` from `tokio_util::sync::CancellationToken` guarantees that hyper dropping the SSE stream immediately cancels the child task, instantly aborting ongoing database I/O and freeing resources. ```rust use axum::{extract::State, response::sse::{Event, Sse}}; use futures::stream::Stream; use std::convert::Infallible; use tokio_stream::wrappers::ReceiverStream; use tokio_util::sync::CancellationToken; use tokio::sync::mpsc; pub async fn handler_good(State(state): State<AppState>) -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let token = CancellationToken::new(); let child_token = token.child_token(); let (tx, rx) = mpsc::channel(32); tokio::spawn(async move { tokio::select! { _ = child_token.cancelled() => { // Deterministic cancellation barrier triggered on client disconnect } _ = async { while let Some(item) = state.expensive_database_cursor().await { if tx.send(Ok(Event::default().data(item))).await.is_err() { break; } } } => {} } }); // Guard automatically triggers child_token.cancel() when Axum drops the stream let stream = ReceiverStream::new(rx); let guarded_stream = async_stream::stream! { let _guard = token.drop_guard(); for await item in stream { yield item; } }; Sse::new(guarded_stream) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Streaming Extractor Task Cancellation Barrier

Axum 0.8 Streaming Extractor Task Cancellation Barrier defines an industrial-grade behavioral standard for backend engineering. Mandates deterministic cancellation boundaries for all Axum 0.8 streaming responses, SSE, and WebSocket loops. When hyper drops an active response stream upon client disconnect, detached background worker tasks must be proactively terminated via CancellationToken or RAII drop guards to prevent unbounded memory and thread leaks. 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 Detached Background Producers Without Cancellation Barriers in Streaming 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 Detached Background Producers Without Cancellation Barriers in Streaming 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 couple background stream producers to a `tokio_util

Engineers MUST ALWAYS couple background stream producers to a `tokio_util::sync::CancellationToken` or an RAII `AbortHandle` drop guard.

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.