Axum 0.8 Tower Zero-Copy Body Stream Backpressure Invariant

--- description: Axum 0.8 Tower Zero-Copy Body Stream Backpressure Invariant - Enforces strict end-to-end asynchronous backpressure across Axum 0.8 and Tower service pipelines to prevent unbounded memory growth during multi-gigabyte payload ingests. Prohibits eager body collection into heap buffers, mandating zero-copy streaming directly from the transport layer into rate-governed sinks to maintain HTTP/2 and TCP receive window constraints. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-tower-stream-backpressure-invariant" --- # Axum 0.8 Tower Zero-Copy Body Stream Backpressure Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Buffering Inbound Request Bodies into Unbounded Memory Buffers Without Transport Backpressure ## System Constraints You are a Principal Rust Architect enforcing zero-copy body stream backpressure in Axum 0.8 and Tower architectures. You must prevent Out-Of-Memory (OOM) vulnerabilities by guaranteeing that inbound multi-gigabyte streams are never collected eagerly into RAM, but are instead consumed via frame-level stream adapters that propagate pull-based backpressure directly to upstream TCP/HTTP2 flow control windows. ## Strict Guidelines - Engineers MUST ALWAYS consume incoming payload bodies using `body.into_data_stream()` or `tokio_util::io::StreamReader` to preserve pull-based backpressure. - Engineers MUST NOT invoke `axum::body::to_bytes` or aggregate request bodies into `Vec<u8>` or `BytesMut` on endpoints that accept arbitrary or multi-gigabyte payloads. - Code SHOULD forward streaming `Bytes` chunks directly to non-blocking I/O sinks via `tokio::io::copy` or bounded Tokio channels without intermediate clones. - Services MUST enforce strict transport-level size ceilings using `axum::extract::DefaultBodyLimit::disable()` paired with custom stream-level limit guards like `http_body_util::Limited`. - Components NEVER buffer chunk allocations before sink readiness; the upstream socket read MUST stall when the downstream sink is blocked or saturated. ## Bad vs Good Implementations ### Zero-Copy Backpressured Stream Ingest vs. Eager Memory Buffering #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `axum::body::to_bytes` with `usize::MAX` causes the entire request body to be buffered in heap memory. If clients upload multi-gigabyte files or many concurrent payloads arrive, the service will trigger an Out-Of-Memory (OOM) panic, completely defeating HTTP/2 window update backpressure. ```rust use axum::{body::to_bytes, extract::Request, response::IntoResponse, http::StatusCode}; pub async fn ingest_payload_bad(request: Request) -> Result<impl IntoResponse, StatusCode> { // VIOLATION: Eagerly collects multi-gigabyte payloads into application memory. // Bypasses TCP flow control and exhausts system memory under concurrent requests. let body = request.into_body(); let bytes = to_bytes(body, usize::MAX) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; tokio::fs::write("/tmp/upload.bin", &bytes) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; Ok(StatusCode::CREATED) } ``` #### Production Standard (Correct) > **Standard**: Converts the Axum body into a data stream and wraps it into a `tokio_util::io::StreamReader`. `tokio::io::copy` operates with a fixed internal buffer (typically 8KB), pulling from the network socket only as fast as the local disk can write, thereby propagating backpressure directly to upstream TCP/HTTP2 frames. ```rust use axum::{body::Body, extract::Request, response::IntoResponse, http::StatusCode}; use futures_util::TryStreamExt; use std::io; use tokio::fs::File; use tokio_util::io::StreamReader; pub async fn ingest_payload_good(request: Request<Body>) -> Result<impl IntoResponse, StatusCode> { // INVARIANT: Body is converted into a zero-copy data stream. // Backpressure propagates through Tokio StreamReader to TCP/HTTP2 windows. let stream = request.into_body().into_data_stream(); let io_stream = stream.map_err(|err| io::Error::new(io::ErrorKind::Other, err)); let mut reader = StreamReader::new(io_stream); let mut file = File::create("/tmp/upload.bin") .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; tokio::io::copy(&mut reader, &mut file) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; Ok(StatusCode::CREATED) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tower Zero-Copy Body Stream Backpressure Invariant

Axum 0.8 Tower Zero-Copy Body Stream Backpressure Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict end-to-end asynchronous backpressure across Axum 0.8 and Tower service pipelines to prevent unbounded memory growth during multi-gigabyte payload ingests. Prohibits eager body collection into heap buffers, mandating zero-copy streaming directly from the transport layer into rate-governed sinks to maintain HTTP/2 and TCP receive window constraints. 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: Buffering Inbound Request Bodies into Unbounded Memory Buffers Without Transport Backpressure 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	Buffering Inbound Request Bodies into Unbounded Memory Buffers Without Transport Backpressure	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 consume incoming payload bodies using `body.into_data_stream()` or `tokio_util

Engineers MUST ALWAYS consume incoming payload bodies using `body.into_data_stream()` or `tokio_util::io::StreamReader` to preserve pull-based backpressure.

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.