Axum 0.8 Hyper-Native Streaming Body Backpressure and Abort Teardown

--- description: Axum 0.8 Hyper-Native Streaming Body Backpressure and Abort Teardown - Enforces strict end-to-end backpressure propagation and immediate cancellation propagation across Axum 0.8 / Hyper 1.x streaming pipelines. Forbids unbounded channel buffers (`mpsc::unbounded_channel`) and unmetered in-memory collection (`to_bytes` without limits), guaranteeing deterministic O(1) memory consumption and instant upstream connection teardown when downstream HTTP clients disconnect. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-hyper-streaming-backpressure-invariant" --- # Axum 0.8 Hyper-Native Streaming Body Backpressure and Abort Teardown > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Channel Buffering and Ignored Cancellation During Hyper Stream Consumption ## System Constraints You are a Principal Rust Distributed Systems Architect specializing in Axum 0.8 and Hyper 1.x async I/O runtimes. Enforce strict backpressure and cooperative cancellation on all incoming and outgoing streaming bodies. Reject any pattern that buffers HTTP bodies without static byte caps, relies on unbounded tokio channels, or spawns detached background tasks that continue reading upstream payloads after client TCP disconnects. Require idiomatic use of `http_body_util::BodyStream`, bounded channels with proactive capacity control, and `tokio::select!` cancellation boundaries. ## Strict Guidelines - Engineers MUST ALWAYS bound downstream buffering by using bounded channels (`tokio::sync::mpsc::channel(N)`) or direct stream adapters (`ReaderStream`, `StreamBody`) rather than intermediate unbounded buffers. - Engineers MUST NOT call `axum::body::to_bytes` or Hyper body collection without an explicit, deterministic byte limit (`axum::extract::DefaultBodyLimit` or `http_body_util::Limited`). - Services MUST propagate client socket disconnects immediately to upstream I/O sources by binding the consuming stream lifetime to the request handler future or wiring `tokio::select!` with connection drop guards. - Code SHOULD leverage `http_body_util::BodyStream` and `tokio_util::io::StreamReader` to transform hyper-native frames without copying memory across task boundaries. - Components NEVER spawn unlinked `tokio::spawn` tasks that pull from request bodies without an explicit cancellation token or watch channel tied to client liveness. ## Bad vs Good Implementations ### Unbounded Chunk Forwarding vs. Zero-Copy Backpressured Stream Adapter #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawning an unlinked background task feeding into `mpsc::unbounded_channel` buffers unlimited data if downstream consumption lags or stalls. Furthermore, if the client disconnects, the spawned task continues consuming upstream network bandwidth and memory, causing unmetered resource leaks. ```rust use axum::{body::Body, extract::Request, response::Response, http::StatusCode}; use tokio::sync::mpsc; pub async fn proxy_stream_bad(req: Request) -> Result<Response, StatusCode> { let mut body = req.into_body(); // ANTI-PATTERN: Unbounded buffer destroys backpressure; slow receiver causes OOM let (tx, mut rx) = mpsc::unbounded_channel(); // ANTI-PATTERN: Detached background task ignores client disconnect and leaks memory tokio::spawn(async move { use http_body_util::BodyExt; while let Some(frame_res) = body.frame().await { if let Ok(frame) = frame_res { if let Some(data) = frame.data_ref() { let _ = tx.send(data.clone()); } } } }); let stream = async_stream::stream! { while let Some(chunk) = rx.recv().await { yield Ok::<_, std::io::Error>(chunk); } }; Ok(Response::new(Body::from_stream(stream))) } ``` #### Production Standard (Correct) > **Standard**: Utilizes `http_body_util::BodyStream` to maintain native frame backpressure. Memory is consumed in O(1) buffer sizes determined by the TCP socket window. If the client drops connection, Hyper tears down the response body stream, which drops the upstream extractor instantly. ```rust use axum::{body::Body, extract::Request, response::Response, http::StatusCode}; use http_body_util::BodyStream; use futures_util::TryStreamExt; pub async fn proxy_stream_good(req: Request) -> Result<Response, StatusCode> { // INVARIANT: Wrap native Axum 0.8 Body in BodyStream directly without unbounded queues let body_stream = BodyStream::new(req.into_body()); // Direct stream mapping preserves Hyper's pull-based backpressure frame-by-frame let byte_stream = body_stream.try_filter_map(|frame| async move { Ok(frame.into_data().ok()) }); // Returning Body::from_stream binds stream consumption directly to the client's socket drain rate. // If the client disconnects, the response future drops, instantly dropping `byte_stream` and aborting upstream I/O. Ok(Response::new(Body::from_stream(byte_stream))) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Hyper-Native Streaming Body Backpressure and Abort Teardown

Axum 0.8 Hyper-Native Streaming Body Backpressure and Abort Teardown defines an industrial-grade behavioral standard for backend engineering. Enforces strict end-to-end backpressure propagation and immediate cancellation propagation across Axum 0.8 / Hyper 1.x streaming pipelines. Forbids unbounded channel buffers (`mpsc::unbounded_channel`) and unmetered in-memory collection (`to_bytes` without limits), guaranteeing deterministic O(1) memory consumption and instant upstream connection teardown when downstream HTTP clients disconnect. 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 Channel Buffering and Ignored Cancellation During Hyper Stream Consumption 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 Channel Buffering and Ignored Cancellation During Hyper Stream Consumption	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 bound downstream buffering by using bounded channels (`tokio

Engineers MUST ALWAYS bound downstream buffering by using bounded channels (`tokio::sync::mpsc::channel(N)`) or direct stream adapters (`ReaderStream`, `StreamBody`) rather than intermediate unbounded buffers.

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.