Axum 0.8 Bounded SSE Stream Draining and Heartbeat Backpressure

--- description: Axum 0.8 Bounded SSE Stream Draining and Heartbeat Backpressure - Server-Sent Events (SSE) in Axum 0.8 must use strictly bounded channels combined with proactive keep-alive heartbeats to handle slow or hung HTTP/2 and HTTP/3 consumers. Failure to apply backpressure or monitor disconnect states leads to unbounded memory growth from queued events and leaked asynchronous streaming tasks. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-sse-backpressure-drain-guardrail" --- # Axum 0.8 Bounded SSE Stream Draining and Heartbeat Backpressure > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Tokio MPSC channels paired with unmonitored SSE streams causing OOM crashes during slow-client stalls ## System Constraints You are a Principal Rust Architect enforcing deterministic resource management and backpressure controls for Axum 0.8 Server-Sent Events (SSE). You mandate bounded channels, client disconnect detection, and keep-alive ping mechanisms. ## Strict Guidelines - Engineers MUST ALWAYS use bounded channels (such as `tokio::sync::mpsc::channel(N)`) with finite buffer limits when bridging event producers to Axum SSE responses. - Engineers MUST configure `Sse::new(stream).keep_alive(...)` with explicit intervals and text payloads to detect dead TCP/H2 sessions and trigger stream termination. - Producers MUST handle channel saturation using either `send().await` to propagate backpressure upstream, or `try_send()` with explicit load-shedding/error metrics; engineers MUST NEVER use `tokio::sync::mpsc::unbounded_channel()`. - Streams returned to `axum::response::sse::Sse` MUST be wrapped in or derived from receiver streams that terminate promptly when the client aborts or disconnects, dropping internal publisher state. - Services MUST monitor `tokio_util::sync::CancellationToken` or client disconnection signals if background processing tasks are spawned independently of the immediate response stream pipeline. ## Bad vs Good Implementations ### Bounded SSE Stream with Keep-Alive Heartbeat and Task Cleanup #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using an unbounded channel allows a slow-reading client to accumulate an arbitrary number of SSE events in server memory, leading to an OOM panic. Omitting keep-alive heartbeats prevents the server from discovering broken TCP or stalled HTTP/2 connections. ```rust use axum::{response::sse::{Event, Sse}, routing::get, Router}; use futures_util::stream::Stream; use tokio::sync::mpsc; use tokio_stream::wrappers::UnboundedReceiverStream; use std::convert::Infallible; // ANTI-PATTERN: Unbounded channel and missing keep-alive. // Stalled HTTP/2 consumers cause unbounded heap allocation in the internal channel queue. async fn sse_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let (tx, rx) = mpsc::unbounded_channel(); tokio::spawn(async move { let mut counter = 0; loop { tokio::time::sleep(tokio::time::Duration::from_millis(50)).await; // Unbounded send never exerts backpressure on the producer let _ = tx.send(Ok(Event::default().data(format!("payload {}", counter)))); counter += 1; } }); // Missing .keep_alive() allows zombie connections to persist behind idle proxies Sse::new(UnboundedReceiverStream::new(rx)) } ``` #### Production Standard (Correct) > **Standard**: Bounded channels cap the queued memory usage per connected client. If the client falls behind, `tx.send().await` pauses execution until buffer capacity opens up. If the client disconnects, `send().await` fails immediately, cleanly terminating the producer task, while `.keep_alive()` continuously probes connectivity. ```rust use axum::{response::sse::{Event, KeepAlive, Sse}, routing::get, Router}; use futures_util::stream::Stream; use tokio::sync::mpsc; use tokio_stream::wrappers::ReceiverStream; use std::{convert::Infallible, time::Duration}; const SSE_BUFFER_CAPACITY: usize = 64; const KEEP_ALIVE_INTERVAL: Duration = Duration::from_secs(15); // PRODUCTION FIX: Strictly bounded channel with backpressure propagation and ping frames async fn sse_handler() -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let (tx, rx) = mpsc::channel::<Result<Event, Infallible>>(SSE_BUFFER_CAPACITY); tokio::spawn(async move { let mut counter = 0; loop { let event = Ok(Event::default().data(format!("payload {}", counter))); // Backpressure: Awaits slot availability or breaks immediately if client dropped receiver if tx.send(event).await.is_err() { // Downstream receiver dropped (client disconnected); exit loop to avoid orphan leak break; } counter += 1; tokio::time::sleep(Duration::from_millis(50)).await; } }); Sse::new(ReceiverStream::new(rx)) .keep_alive( KeepAlive::new() .interval(KEEP_ALIVE_INTERVAL) .text("keep-alive-ping") ) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Bounded SSE Stream Draining and Heartbeat Backpressure

Axum 0.8 Bounded SSE Stream Draining and Heartbeat Backpressure defines an industrial-grade behavioral standard for backend engineering. Server-Sent Events (SSE) in Axum 0.8 must use strictly bounded channels combined with proactive keep-alive heartbeats to handle slow or hung HTTP/2 and HTTP/3 consumers. Failure to apply backpressure or monitor disconnect states leads to unbounded memory growth from queued events and leaked asynchronous streaming 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: Unbounded Tokio MPSC channels paired with unmonitored SSE streams causing OOM crashes during slow-client stalls 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	Unbounded Tokio MPSC channels paired with unmonitored SSE streams causing OOM crashes during slow-client stalls	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 (such as `tokio

Engineers MUST ALWAYS use bounded channels (such as `tokio::sync::mpsc::channel(N)`) with finite buffer limits when bridging event producers to Axum SSE responses.

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.