Axum 0.8 / Hyper-v1 Bounded Stream Backpressure and Flow-Control Barrier

--- description: Axum 0.8 / Hyper-v1 Bounded Stream Backpressure and Flow-Control Barrier - Enforces deterministic backpressure propagation on Axum 0.8 and Hyper-v1 streaming request bodies to regulate HTTP/2 and HTTP/3 flow-control windows. Eliminates unbounded worker heap buffering and OOM conditions during high-concurrency multipart and file ingestion by coupling TCP/QUIC window updates directly to downstream sink consumption rates. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-hyper-streaming-backpressure-barrier" --- # Axum 0.8 / Hyper-v1 Bounded Stream Backpressure and Flow-Control Barrier > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Eager Body Buffering and Unbounded MPSC Decoupling in Streaming Request Handlers ## System Constraints You are a Principal Rust Systems Architect specializing in Axum 0.8, Hyper v1, and Tokio runtime internals. Mandate strict backpressure barriers on all streaming endpoints. Reject any implementation that buffers unconstrained HTTP request bodies, decouples chunk reading into unbounded queues, or detaches Tokio tasks without awaiting downstream sink readiness. ## Strict Guidelines - Engineers MUST ALWAYS process `axum::body::Body` or `hyper::body::Incoming` using sequential `http_body_util::BodyExt::frame` or bounded stream wrappers like `tokio_util::io::StreamReader`. - Engineers MUST NOT convert multi-gigabyte or streaming request payloads into in-memory collections using `axum::body::to_bytes` without explicit, rigid length caps. - Services MUST couple Hyper-v1 frame polling directly to downstream I/O sinks (e.g., `tokio::fs::File`, S3 multipart uploaders) so TCP/HTTP/2 `WINDOW_UPDATE` frames are withheld until the buffer is physically written. - Pipelines MUST NEVER forward stream chunks through `tokio::sync::mpsc::unbounded_channel`; only bounded channels with a capacity calibrated to available Tokio worker memory limits are permitted. - Handlers MUST explicitly configure global and route-level body limits using `axum::extract::DefaultBodyLimit::disable()` accompanied by manual stream frame counter invariants to avoid payload truncation while preserving system resource caps. ## Bad vs Good Implementations ### Unbounded Ingestion via Eager Task Spawning vs. Bounded Stream Piping #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using an unbounded channel (`mpsc::unbounded_channel`) eagerly pulls frame data from Hyper's incoming buffer into heap memory without awaiting the file write. Hyper immediately sends `WINDOW_UPDATE` frames back to the client, allowing high-throughput clients to exhaust the process memory. ```rust use axum::{body::Body, extract::Request, response::IntoResponse}; use http_body_util::BodyExt; use tokio::sync::mpsc; pub async fn upload_handler(req: Request<Body>) -> impl IntoResponse { let (tx, mut rx) = mpsc::unbounded_channel(); let mut body = req.into_body(); // CRITICAL ANTI-PATTERN: Drains HTTP/2 frames as fast as hyper receives them, // completely divorcing HTTP/2 flow control from disk writing speed. // Ingesting a 5GB file over 10Gbps link will cause immediate OOM under load. tokio::spawn(async move { while let Some(Ok(frame)) = body.frame().await { if let Some(data) = frame.into_data().ok() { let _ = tx.send(data); } } }); tokio::spawn(async move { let mut file = tokio::fs::File::create("/tmp/upload.bin").await.unwrap(); use tokio::io::AsyncWriteExt; while let Some(chunk) = rx.recv().await { let _ = file.write_all(&chunk).await; } }); "Accepted" } ``` #### Production Standard (Correct) > **Standard**: The stream is wrapped using `tokio_util::io::StreamReader` and piped via `tokio::io::copy`. Reading from the incoming body occurs strictly on-demand as bytes are successfully written to the underlying file descriptor. Hyper-v1's underlying frame buffer remains populated when the disk is slow, throttling HTTP/2/3 `WINDOW_UPDATE` frames and naturally rate-limiting the client. ```rust use axum::{body::Body, extract::Request, http::StatusCode, response::IntoResponse}; use http_body_util::BodyExt; use tokio::io::AsyncWriteExt; use tokio_util::io::StreamReader; pub async fn upload_handler(req: Request<Body>) -> Result<impl IntoResponse, (StatusCode, &'static str)> { let body = req.into_body(); // Invariant: Convert frames into a bounded Stream of io::Result<Bytes> let stream = body.into_data_stream().map_err(|err| { std::io::Error::new(std::io::ErrorKind::Other, err) }); // Invariant: StreamReader yields backpressure directly to tokio::io::copy let mut reader = StreamReader::new(stream); let mut destination = tokio::fs::File::create("/tmp/upload.bin") .await .map_err(|_| (StatusCode::INTERNAL_SERVER_ERROR, "Failed to create file"))?; // Invariant: tokio::io::copy awaits destination.write before polling the next chunk from reader. // Hyper-v1 will NOT replenish TCP/HTTP/2 flow-control credits until the current buffer is written. tokio::io::copy(&mut reader, &mut destination) .await .map_err(|_| (StatusCode::BAD_REQUEST, "Stream read/write error"))?; destination.flush().await.map_err(|_| (StatusCode::INTERNAL_SERVER_ERROR, "Flush failure"))?; Ok((StatusCode::CREATED, "File ingested with deterministic backpressure")) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 / Hyper-v1 Bounded Stream Backpressure and Flow-Control Barrier

Axum 0.8 / Hyper-v1 Bounded Stream Backpressure and Flow-Control Barrier defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic backpressure propagation on Axum 0.8 and Hyper-v1 streaming request bodies to regulate HTTP/2 and HTTP/3 flow-control windows. Eliminates unbounded worker heap buffering and OOM conditions during high-concurrency multipart and file ingestion by coupling TCP/QUIC window updates directly to downstream sink consumption rates. 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: Eager Body Buffering and Unbounded MPSC Decoupling in Streaming Request Handlers 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	Eager Body Buffering and Unbounded MPSC Decoupling in Streaming Request Handlers	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 process `axum

Engineers MUST ALWAYS process `axum::body::Body` or `hyper::body::Incoming` using sequential `http_body_util::BodyExt::frame` or bounded stream wrappers like `tokio_util::io::StreamReader`.

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.