Axum 0.8 Streamed Payload Spooling & Memory Ceiling Guardrail

--- description: Axum 0.8 Streamed Payload Spooling & Memory Ceiling Guardrail - Mandates strict non-buffering chunk-size enforcement and ephemeral disk-spool failover mechanisms for Axum 0.8 streaming endpoints. Prevents process-level Out-of-Memory (OOM) crashes and heap exhaustion vulnerabilities arising from unbounded chunked transfer encodings and uncontrolled async payload buffering. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-streamed-payload-spooling-memory-ceiling" --- # Axum 0.8 Streamed Payload Spooling & Memory Ceiling Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded In-Memory Body Accumulation and Unmetered Stream Buffering ## System Constraints You are a Principal Rust Architect enforcing Axum 0.8 memory safety and HTTP streaming invariants. You must prevent memory exhaustion attacks by requiring bounded memory accumulation, non-buffering frame/chunk limits, and deterministic ephemeral disk spooling for unbounded or large streamed payloads. ## Strict Guidelines - Engineers MUST NEVER accumulate incoming HTTP payload bodies directly into unbounded heap structures (such as `Vec<u8>`, `BytesMut`, or unconstrained `to_bytes(usize::MAX)` calls) without explicit memory ceiling boundaries. - Services MUST enforce dual-tiered allocation boundaries for streaming endpoints: an immediate in-memory ceiling (e.g., 2MB) followed by transparent spillover into an ephemeral, secure tempfile, bounded by an immutable absolute hard limit (e.g., 50MB). - Middleware layers MUST immediately terminate client connections and return `413 Payload Too Large` if streamed payloads exceed total disk-spool allocation budgets or if single frame chunks exceed frame allocation quotas. - Engineers MUST utilize Axum 0.8 and `http-body-util` primitive boundaries (`Limited`, `BodyExt::collect`) or streaming frame consumers with continuous backpressure, rejecting unmetered consumption loops. - Ephemeral disk spools MUST be unlinked immediately upon creation using OS-level anonymous tempfiles (such as `tempfile::tempfile()`) or scoped async file handles ensuring automatic reclamation upon request drop, panic, or disconnect. - Services MUST configure `tower_http::limit::RequestBodyLimitLayer` at the global router layer as a first line of defense, overriding it only via specialized spooling extractors on designated streaming routes. ## Bad vs Good Implementations ### Naive In-Memory Body Buffer vs. Ephemeral Disk-Spool Streaming Receiver #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Reading the entire body into memory using `BodyExt::collect()` and `.to_bytes()` without size constraints allows a malicious client to stream arbitrarily large amounts of data, causing immediate RAM starvation and triggering the Linux OOM-killer on the service process. ```rust use axum::{body::Body, extract::Request, response::IntoResponse, http::StatusCode}; use http_body_util::BodyExt; pub async fn upload_handler(req: Request<Body>) -> Result<impl IntoResponse, StatusCode> { // DANGEROUS: Collects the entire payload into memory without limits. // An attacker sending an infinite chunked stream will exhaust system heap and crash the pod via OOM. let whole_body = req.into_body().collect().await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)? .to_bytes(); // In-memory manipulation of massive buffer println!("Read {} bytes into RAM", whole_body.len()); Ok(StatusCode::OK) } ``` #### Production Standard (Correct) > **Standard**: The payload stream is read frame-by-frame under continuous backpressure. Payloads under 2 MiB stay in memory; payloads exceeding 2 MiB transparently transition to an ephemeral, OS-unlinked tempfile. Any payload exceeding the 100 MiB hard cap triggers an immediate 413 error and aborts reading, guaranteeing invariant memory safety. ```rust use axum::{body::Body, extract::Request, response::IntoResponse, http::StatusCode}; use bytes::Bytes; use http_body_util::BodyExt; use std::io::{Seek, SeekFrom, Write}; use tempfile::tempfile; const MEMORY_CEILING: usize = 2 * 1024 * 1024; // 2 MiB in RAM const HARD_DISK_CEILING: u64 = 100 * 1024 * 1024; // 100 MiB total on disk enum SpoolPayload { Memory(Bytes), Spool(std::fs::File), } pub async fn upload_handler(req: Request<Body>) -> Result<impl IntoResponse, StatusCode> { let mut body = req.into_body(); let mut mem_buf = Vec::with_capacity(MEMORY_CEILING.min(64 * 1024)); let mut disk_spool: Option<std::fs::File> = None; let mut total_bytes: u64 = 0; while let Some(frame_result) = body.frame().await { let frame = frame_result.map_err(|_| StatusCode::BAD_REQUEST)?; if let Ok(data) = frame.into_data() { let chunk_len = data.len() as u64; total_bytes += chunk_len; if total_bytes > HARD_DISK_CEILING { return Err(StatusCode::PAYLOAD_TOO_LARGE); } if disk_spool.is_none() && total_bytes <= MEMORY_CEILING as u64 { mem_buf.extend_from_slice(&data); } else { let spool = match disk_spool.as_mut() { Some(f) => f, None => { let mut file = tempfile().map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; file.write_all(&mem_buf).map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; mem_buf.clear(); mem_buf.shrink_to_fit(); disk_spool.insert(file) } }; spool.write_all(&data).map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } } } let payload = match disk_spool { Some(mut file) => { file.seek(SeekFrom::Start(0)).map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; SpoolPayload::Spool(file) } None => SpoolPayload::Memory(mem_buf.into()), }; // Payload is now safely bounded, processing can proceed deterministically match payload { SpoolPayload::Memory(b) => Ok(format!("Buffered {} bytes in RAM", b.len())), SpoolPayload::Spool(_) => Ok(format!("Spriveled {} bytes to secure disk spool", total_bytes)), } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Streamed Payload Spooling & Memory Ceiling Guardrail

Axum 0.8 Streamed Payload Spooling & Memory Ceiling Guardrail defines an industrial-grade behavioral standard for backend engineering. Mandates strict non-buffering chunk-size enforcement and ephemeral disk-spool failover mechanisms for Axum 0.8 streaming endpoints. Prevents process-level Out-of-Memory (OOM) crashes and heap exhaustion vulnerabilities arising from unbounded chunked transfer encodings and uncontrolled async payload buffering. 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 In-Memory Body Accumulation and Unmetered Stream Buffering 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 In-Memory Body Accumulation and Unmetered Stream Buffering	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 NEVER accumulate incoming HTTP payload bodies directly into unbounded heap structures (such as `Vec<u8>`, `BytesMut`, or unconstrained `to_bytes(usize

Engineers MUST NEVER accumulate incoming HTTP payload bodies directly into unbounded heap structures (such as `Vec<u8>`, `BytesMut`, or unconstrained `to_bytes(usize::MAX)` calls) without explicit memory ceiling boundaries.

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.