Axum 0.8 Tokio SSE Cancellation & Backpressure Drain Guardrail

--- description: Axum 0.8 Tokio SSE Cancellation & Backpressure Drain Guardrail - Enforces deterministic Tokio task termination and upstream backpressure propagation upon client disconnects in persistent Axum 0.8 SSE endpoints. Mandates bounded channels, proactive keep-alive heartbeats, and RAII-bound CancellationToken lifecycles to prevent zombie background workers and memory exhaustion. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-tokio-sse-cancellation-drain" --- # Axum 0.8 Tokio SSE Cancellation & Backpressure Drain Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning detached unbounded worker loops that orphan background tasks and leak memory when SSE clients disconnect. ## System Constraints You are a Principal Rust Architect enforcing resource invariants for Axum 0.8 SSE streams. When clients disconnect, Axum drops the response body stream. If background workers are spawned without RAII-bound cancellation or bounded channels, they become orphaned zombie tasks consuming CPU and memory. You must mandate bounded channels, explicit CancellationToken guards, and keep-alive heartbeats. ## Strict Guidelines - Engineers MUST ALWAYS use bounded channels (e.g., tokio::sync::mpsc::channel) with explicit, non-zero capacities to propagate backpressure upstream. - Engineers MUST ALWAYS tie spawned producer tasks to the SSE stream lifecycle using `tokio_util::sync::CancellationToken` and an RAII drop guard. - Engineers MUST NOT use `tokio::sync::mpsc::unbounded_channel` or unbounded buffers for streaming responses. - Code MUST terminate producer loops immediately when `tx.reserve()` or `tx.send()` encounters a closed channel error. - Services MUST configure `KeepAlive` on `axum::response::sse::Sse` to ensure TCP-level dead-connection detection and prompt socket closure. ## Bad vs Good Implementations ### Unbounded SSE Stream with Orphaned Task vs. Bounded Stream with CancellationToken Drop Guard #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler spawns an unmonitored background task with an unbounded channel. When the client disconnects, Axum drops the stream, but the spawned task continues generating and discarding events, or running database queries, leaking CPU and memory as a zombie task. Additionally, no keep-alive interval is set to detect half-open TCP connections. ```rust use axum::response::sse::{Event, Sse}; use std::convert::Infallible; use tokio::sync::mpsc; use tokio_stream::wrappers::UnboundedReceiverStream; pub async fn sse_handler() -> Sse<UnboundedReceiverStream<Result<Event, Infallible>>> { // ANTI-PATTERN: Unbounded channel prevents upstream backpressure let (tx, rx) = mpsc::unbounded_channel(); // ANTI-PATTERN: Detached task has no cancellation token tied to stream drop; // if the receiver drops, ignoring the send error leaves heavy work running indefinitely. tokio::spawn(async move { let mut counter: u64 = 0; loop { counter += 1; let _ = tx.send(Ok(Event::default().data(format!("event #{counter}")))); tokio::time::sleep(std::time::Duration::from_millis(500)).await; } }); // ANTI-PATTERN: Missing keep_alive configuration to detect dead TCP sockets Sse::new(UnboundedReceiverStream::new(rx)) } ``` #### Production Standard (Correct) > **Standard**: Uses a bounded channel (capacity 16) for backpressure, wraps the stream in a generator holding a CancellationToken DropGuard, and monitors channel closure via tx.reserve(). When the client disconnects, the stream is dropped, firing the drop guard and causing the worker task to abort immediately. KeepAlive pings ensure dead sockets are actively detected. ```rust use axum::response::sse::{Event, KeepAlive, Sse}; use futures_core::stream::Stream; use std::{convert::Infallible, time::Duration}; use tokio::sync::mpsc; use tokio_stream::wrappers::ReceiverStream; use tokio_util::sync::CancellationToken; pub async fn sse_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { const BUFFER_CAPACITY: usize = 16; let (tx, rx) = mpsc::channel::<Result<Event, Infallible>>(BUFFER_CAPACITY); let cancel_token = CancellationToken::new(); let worker_token = cancel_token.child_token(); // PROD-INVARIANT: Worker task terminates via child cancellation token OR closed sender permit tokio::spawn(async move { let mut counter: u64 = 0; loop { tokio::select! { biased; _ = worker_token.cancelled() => break, permit_res = tx.reserve() => { match permit_res { Ok(permit) => { counter += 1; permit.send(Ok(Event::default().data(format!("event #{counter}")))); tokio::time::sleep(Duration::from_millis(500)).await; } Err(_) => break, // Channel closed: client disconnected and stream dropped } } } } }); // PROD-INVARIANT: RAII drop guard fires cancellation token immediately upon client disconnect let receiver_stream = ReceiverStream::new(rx); let drop_guard_stream = async_stream::stream! { let _guard = cancel_token.drop_guard(); for await item in receiver_stream { yield item; } }; // PROD-INVARIANT: Enable proactive keep-alive to drop stale sockets promptly Sse::new(drop_guard_stream).keep_alive( KeepAlive::new() .interval(Duration::from_secs(15)) .text("keep-alive-ping"), ) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tokio SSE Cancellation & Backpressure Drain Guardrail

Axum 0.8 Tokio SSE Cancellation & Backpressure Drain Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic Tokio task termination and upstream backpressure propagation upon client disconnects in persistent Axum 0.8 SSE endpoints. Mandates bounded channels, proactive keep-alive heartbeats, and RAII-bound CancellationToken lifecycles to prevent zombie background workers and memory exhaustion. 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 unbounded worker loops that orphan background tasks and leak memory when SSE clients disconnect. 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 unbounded worker loops that orphan background tasks and leak memory when SSE clients disconnect.	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 use bounded channels (e.g., tokio

Engineers MUST ALWAYS use bounded channels (e.g., tokio::sync::mpsc::channel) with explicit, non-zero capacities to propagate backpressure upstream.

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.