Axum 0.8 Stream Backpressure & Cooperative Early Disconnect Invariant

--- description: Axum 0.8 Stream Backpressure & Cooperative Early Disconnect Invariant - Enforces deterministic cancellation and bounded backpressure across asynchronous HTTP/2 and HTTP/3 streaming pipelines in Axum 0.8. Ensures that downstream client disconnects (such as RST_STREAM or socket drops) immediately tear down upstream background workers, preventing resource leakage, memory exhaustion, and phantom query execution. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-async-stream-backpressure-disconnect-guardrail" --- # Axum 0.8 Stream Backpressure & Cooperative Early Disconnect Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Detached Background Task Spawning with Unbounded Channels Ignoring Receiver Drops ## System Constraints You are a Principal Rust Systems Architect specializing in Axum 0.8 and Tokio network runtime safety. Mandate strict adherence to bounded backpressure, cooperative stream cancellation, and zero-leak task lifecycles during client disconnects in high-throughput HTTP streaming endpoints. ## Strict Guidelines - Engineers MUST ALWAYS tie the lifecycle of asynchronous generation tasks directly to the Axum response Body stream drop or pass a Tokio CancellationToken that trips when the stream drops. - Engineers MUST NOT spawn detached tasks (`tokio::spawn`) that feed unbounded channels (`tokio::sync::mpsc::unbounded_channel`) without checking sender error responses on every yield. - Services MUST enforce bounded backpressure using bounded channels (`mpsc::channel(N)`) with N tuned to match socket buffer requirements (typically between 16 and 64 items). - Stream generation logic MUST treat `mpsc::error::SendError` as an immediate cancellation signal and gracefully abort all upstream database cursors, socket connections, and compute workloads. - Handlers MUST utilize `axum::body::Body::from_stream` wrapped over standard `ReceiverStream` or `async_stream` blocks that natively yield on cancellation, rather than keeping independent background workers alive. ## Bad vs Good Implementations ### Unbounded Detached Task vs. Cooperative Bounded ReceiverStream with Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawns a detached background task with an unbounded channel. When an HTTP/2 client terminates the connection, the receiver is dropped, but the producer continues processing iterations, ignoring send errors and consuming memory and database connections without backpressure. ```rust use axum::{body::Body, response::Response, routing::get, Router}; use tokio::sync::mpsc; async fn leak_prone_handler() -> Response { // ANTI-PATTERN: Unbounded channel + detached tokio::spawn. // Ignores client disconnection (RST_STREAM); loop runs until batch limit, // leaking CPU and memory while queuing data that will never be delivered. let (tx, mut rx) = mpsc::unbounded_channel(); tokio::spawn(async move { for i in 0..1_000_000 { tokio::time::sleep(tokio::time::Duration::from_millis(50)).await; // Ignoring result causes phantom computation if tx.send fails late let _ = tx.send(Ok::<_, std::io::Error>(format!("data: item {}\n\n", i))); } }); let stream = tokio_stream::wrappers::UnboundedReceiverStream::new(rx); Response::new(Body::from_stream(stream)) } ``` #### Production Standard (Correct) > **Standard**: Implements a strictly bounded mpsc channel ensuring downstream backpressure, combined with a `CancellationToken` whose drop guard fires as soon as Axum drops the stream upon client disconnect. This halts upstream execution immediately without leaking memory or CPU. ```rust use axum::{body::Body, http::StatusCode, response::Response, routing::get, Router}; use tokio::sync::mpsc; use tokio_stream::wrappers::ReceiverStream; use tokio_util::sync::CancellationToken; use bytes::Bytes; async fn resilient_stream_handler() -> Result<Response, StatusCode> { // INVARIANT: Bounded channel enforces backpressure. // CancellationToken guarantees cooperative teardown on client disconnect. const BUFFER_CAPACITY: usize = 32; let (tx, rx) = mpsc::channel::<Result<Bytes, std::io::Error>>(BUFFER_CAPACITY); let token = CancellationToken::new(); let child_token = token.clone(); tokio::spawn(async move { for i in 0..1_000_000 { tokio::select! { biased; _ = child_token.cancelled() => { tracing::info!("Client disconnected. Aborting upstream generation task."); break; } res = tx.send(Ok(Bytes::from(format!("data: item {}\n\n", i)))) => { if res.is_err() { tracing::info!("Receiver dropped, terminating producer loop."); break; } } } tokio::time::sleep(tokio::time::Duration::from_millis(50)).await; } }); // Token guard drops and cancels producer when Stream/Body is dropped on disconnect let guard_stream = ReceiverStream::new(rx); let stream_with_guard = async_stream::stream! { let _guard = token.drop_guard(); for await item in guard_stream { yield item; } }; Ok(Response::builder() .header("content-type", "text/event-stream") .header("cache-control", "no-cache") .body(Body::from_stream(stream_with_guard)) .unwrap()) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Stream Backpressure & Cooperative Early Disconnect Invariant

Axum 0.8 Stream Backpressure & Cooperative Early Disconnect Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic cancellation and bounded backpressure across asynchronous HTTP/2 and HTTP/3 streaming pipelines in Axum 0.8. Ensures that downstream client disconnects (such as RST_STREAM or socket drops) immediately tear down upstream background workers, preventing resource leakage, memory exhaustion, and phantom query execution. 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: Detached Background Task Spawning with Unbounded Channels Ignoring Receiver Drops 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	Detached Background Task Spawning with Unbounded Channels Ignoring Receiver Drops	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 tie the lifecycle of asynchronous generation tasks directly to the Axum response Body stream drop or pass a Tokio CancellationToken that trips when the stream drops.

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.