Axum 0.8 In-Flight Streaming & Tokio Task Cancellation Invariant

--- description: Axum 0.8 In-Flight Streaming & Tokio Task Cancellation Invariant - Enforces strict RAII cancellation tokens and bounded channel draining across Axum 0.8 streaming handlers (SSE, NDJSON, and raw byte streams). Prevents zombie Tokio tasks, memory leaks, and socket descriptor exhaustion during rolling deployments and client disconnects by coupling streams to tokio_util::task::TaskTracker and CancellationToken primitives. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-tokio-streaming-cancellation-standard" --- # Axum 0.8 In-Flight Streaming & Tokio Task Cancellation Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning detached Tokio tasks feeding unmonitored channels in SSE/streaming endpoints without cancellation coordination ## System Constraints You are a Principal Rust Architect enforcing deterministic streaming lifecycle management in Axum 0.8 and Tokio. You must reject any detached Tokio worker task spawned inside HTTP request handlers that does not hook into cooperative cancellation, task trackers, or channel disconnect signals. Enforce clean socket draining and zero task leakage during rolling restarts. ## Strict Guidelines - Engineers MUST ALWAYS link long-lived streaming handlers (SSE, WebSockets, HTTP/3 chunked bodies) to a hierarchical `tokio_util::sync::CancellationToken` derived from the application shutdown signal. - Engineers MUST NOT spawn detached tasks via `tokio::spawn` without retaining an `AbortHandle` or registering the task into a `tokio_util::task::TaskTracker`. - Streaming producer loops MUST terminate immediately when `tokio::sync::mpsc::Sender::send` returns a `SendError`, indicating downstream client disconnection. - Services MUST select over cancellation tokens in all streaming loops to prevent infinite blockages during Kubernetes rolling updates (`SIGTERM`). - Streaming endpoints MUST use `axum::response::sse::KeepAlive` or explicit protocol ping frames to detect dead TCP/QUIC half-open connections before channel buffers fill. - Handlers MUST NEVER leak un-awaited join handles or leave background compute loops running when an Axum `axum::body::Body` stream is dropped. ## Bad vs Good Implementations ### Unbounded Detached Stream Task vs. Coordinated TaskTracker with CancellationToken #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The worker task is spawned detached via tokio::spawn with no TaskTracker, no CancellationToken, and ignores send errors without breaking the loop. When a client disconnects or the container receives SIGTERM, the loop continues running indefinitely in the Tokio runtime, holding memory and socket allocations. ```rust use axum::{response::sse::{Event, Sse}, routing::get, Router}; use futures_util::stream::Stream; use std::{convert::Infallible, time::Duration}; use tokio::sync::mpsc; use tokio_stream::wrappers::ReceiverStream; pub async fn bad_sse_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let (tx, rx) = mpsc::channel(100); // ANTI-PATTERN: Detached task without cancellation token or abort handle. // During SIGTERM or client drops, if the channel is not checked properly // or blocks on external I/O, this worker task becomes an orphaned zombie. tokio::spawn(async move { let mut counter = 0; loop { tokio::time::sleep(Duration::from_secs(1)).await; counter += 1; let _ = tx.send(Ok(Event::default().data(counter.to_string()))).await; } }); Sse::new(ReceiverStream::new(rx)) } ``` #### Production Standard (Correct) > **Standard**: The background producer task is spawned within a global `TaskTracker` and selects against a child `CancellationToken`. If the server initiates graceful shutdown or the client drops the connection (triggering a `SendError`), the loop breaks immediately, releasing memory, workers, and file descriptors. ```rust use axum::{ extract::State, response::sse::{Event, KeepAlive, Sse}, routing::get, Router, }; use futures_util::stream::Stream; use std::{convert::Infallible, sync::Arc, time::Duration}; use tokio::sync::mpsc; use tokio_stream::wrappers::ReceiverStream; use tokio_util::sync::CancellationToken; use tokio_util::task::TaskTracker; #[derive(Clone)] pub struct AppState { pub tracker: TaskTracker, pub shutdown_token: CancellationToken, } pub async fn good_sse_handler( State(state): State<Arc<AppState>>, ) -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let (tx, rx) = mpsc::channel(64); let child_token = state.shutdown_token.child_token(); // INVARIANT: Task is tracked by TaskTracker, uses child cancellation token, // and breaks immediately when the client disconnects (SendError). state.tracker.spawn(async move { let mut ticker = tokio::time::interval(Duration::from_secs(1)); let mut counter = 0u64; loop { tokio::select! { _ = child_token.cancelled() => { tracing::info!("Shutdown signal received; draining worker stream"); break; } _ = ticker.tick() => { counter += 1; let event = Ok(Event::default().data(counter.to_string())); if tx.send(event).await.is_err() { tracing::debug!("Client disconnected; aborting worker task"); break; } } } } }); Sse::new(ReceiverStream::new(rx)) .keep_alive(KeepAlive::new().interval(Duration::from_secs(15))) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 In-Flight Streaming & Tokio Task Cancellation Invariant

Axum 0.8 In-Flight Streaming & Tokio Task Cancellation Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict RAII cancellation tokens and bounded channel draining across Axum 0.8 streaming handlers (SSE, NDJSON, and raw byte streams). Prevents zombie Tokio tasks, memory leaks, and socket descriptor exhaustion during rolling deployments and client disconnects by coupling streams to tokio_util::task::TaskTracker and CancellationToken primitives. 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 Tokio tasks feeding unmonitored channels in SSE/streaming endpoints without cancellation coordination 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 Tokio tasks feeding unmonitored channels in SSE/streaming endpoints without cancellation coordination	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 long-lived streaming handlers (SSE, WebSockets, HTTP/3 chunked bodies) to a hierarchical `tokio_util

Engineers MUST ALWAYS link long-lived streaming handlers (SSE, WebSockets, HTTP/3 chunked bodies) to a hierarchical `tokio_util::sync::CancellationToken` derived from the application shutdown signal.

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.