Axum 0.8 Asynchronous Streaming Backpressure & Memory Bounds Standard

--- description: Axum 0.8 Asynchronous Streaming Backpressure & Memory Bounds Standard - Enforces strict byte-budget guards, bounded buffer pipelines, and deterministic backpressure across all Axum 0.8 streaming endpoints and multipart handlers. Prevents catastrophic OOM panics and heap fragmentation caused by unbounded buffering, disabled DefaultBodyLimit guards, and unthrottled chunk collection. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-0-8-streaming-backpressure-bounds" --- # Axum 0.8 Asynchronous Streaming Backpressure & Memory Bounds Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Buffering unbounded streams into in-memory vectors or detaching consumers without backpressure, risking process-level OOM DoS. ## System Constraints You are a Principal Rust Architect enforcing the Axum 0.8 Asynchronous Streaming Backpressure & Memory Bounds Standard. You must reject any code that disables body limits without localized byte counting, buffers full streaming payloads into memory (e.g., Vec<u8>), or introduces unbounded channel decoupling between stream producers and consumers. Mandate bounded Tokio channels, incremental chunk writes, explicit maximum payload limits, and proper stream cancellation handling. ## Strict Guidelines - Engineers MUST ALWAYS enforce explicit byte limits per stream using either axum::extract::DefaultBodyLimit::max(N) or a manual atomic byte-budget wrapper around http_body_util::BodyExt. - Engineers MUST NOT disable DefaultBodyLimit on routes without applying a hard-capped streaming token counter that aborts with StatusCode::PAYLOAD_TOO_LARGE upon overflow. - Engineers MUST NEVER accumulate incoming multipart field chunks into an in-memory Vec<u8> or String; chunks MUST be piped incrementally to bounded sinks (e.g., tokio::fs::File or bounded mpsc channels) with backpressure. - Streaming pipelines MUST await each downstream sink write before pulling the subsequent chunk from the stream to preserve TCP window backpressure. - Bounded channels (tokio::sync::mpsc::channel) MUST be used when handing stream data to separate worker tasks; engineers MUST NEVER use unbounded_channel in network I/O paths. - Error boundaries MUST ensure underlying temporary files or incomplete buffers are securely unlinked and reclaimed immediately when a client aborts or a byte limit is breached. ## Bad vs Good Implementations ### Unbounded Multipart Accumulation vs. Incremental Bounded Stream with Backpressure #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Reading every chunk of every field into a growing Vec<u8> eliminates backpressure and consumes unconstrained heap memory. A single malicious or slow client sending hundreds of megabytes concurrently will exhaust server memory and trigger an OS OOM kill. ```rust use axum::{extract::Multipart, http::StatusCode, response::IntoResponse}; pub async fn upload_file(mut multipart: Multipart) -> Result<impl IntoResponse, StatusCode> { // ANTI-PATTERN: Completely unconstrained in-memory buffering. // Disables limits and buffers raw field chunks directly into RAM, // leading to deterministic host OOM under concurrent heavy uploads. while let Some(mut field) = multipart.next_field().await.map_err(|_| StatusCode::BAD_REQUEST)? { let mut file_bytes = Vec::new(); while let Some(chunk) = field.chunk().await.map_err(|_| StatusCode::BAD_REQUEST)? { file_bytes.extend_from_slice(&chunk); } tokio::fs::write("/tmp/uploaded_file.bin", &file_bytes) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } Ok(StatusCode::OK) } ``` #### Production Standard (Correct) > **Standard**: Streams chunks directly to the persistent storage sink while tracking cumulative size against a hard byte ceiling. Awaiting target_file.write_all ensures backpressure is propagated to the TCP stack, preventing unbounded memory spikes. ```rust use axum::{extract::Multipart, http::StatusCode, response::IntoResponse}; use tokio::io::AsyncWriteExt; const MAX_FILE_SIZE: usize = 20 * 1024 * 1024; // 20 MB budget pub async fn upload_file(mut multipart: Multipart) -> Result<impl IntoResponse, StatusCode> { while let Some(mut field) = multipart.next_field().await.map_err(|_| StatusCode::BAD_REQUEST)? { let mut total_bytes = 0usize; let mut target_file = tokio::fs::File::create("/tmp/uploaded_file.bin") .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; // Stream incrementally with deterministic backpressure while let Some(chunk) = field.chunk().await.map_err(|_| StatusCode::BAD_REQUEST)? { total_bytes += chunk.len(); if total_bytes > MAX_FILE_SIZE { drop(target_file); let _ = tokio::fs::remove_file("/tmp/uploaded_file.bin").await; return Err(StatusCode::PAYLOAD_TOO_LARGE); } // Awaiting write preserves TCP socket backpressure to sender target_file .write_all(&chunk) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } target_file.flush().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } Ok(StatusCode::OK) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Asynchronous Streaming Backpressure & Memory Bounds Standard

Axum 0.8 Asynchronous Streaming Backpressure & Memory Bounds Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict byte-budget guards, bounded buffer pipelines, and deterministic backpressure across all Axum 0.8 streaming endpoints and multipart handlers. Prevents catastrophic OOM panics and heap fragmentation caused by unbounded buffering, disabled DefaultBodyLimit guards, and unthrottled chunk collection. 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 unbounded streams into in-memory vectors or detaching consumers without backpressure, risking process-level OOM DoS. 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 unbounded streams into in-memory vectors or detaching consumers without backpressure, risking process-level OOM DoS.	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 enforce explicit byte limits per stream using either axum

Engineers MUST ALWAYS enforce explicit byte limits per stream using either axum::extract::DefaultBodyLimit::max(N) or a manual atomic byte-budget wrapper around http_body_util::BodyExt.

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.