Axum 0.8 Zero-Copy Multipart Stream Bounded Allocation Standard

--- description: Axum 0.8 Zero-Copy Multipart Stream Bounded Allocation Standard - Enforces strict per-stream memory quotas and backpressure-driven chunk draining for multipart streaming uploads in Axum 0.8. Prevents catastrophic process memory exhaustion (OOM) and heap fragmentation caused by unbounded buffering under high-concurrency HTTP/2 and HTTP/3 multiplexing. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-zerocopy-multipart-bounded-stream" --- # Axum 0.8 Zero-Copy Multipart Stream Bounded Allocation Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded In-Memory Accumulation via `field.bytes()` or Unmetered Heap Appends in Streaming Handlers ## System Constraints You are a Principal Rust Systems Architect enforcing zero-copy bounded streaming invariants for Axum 0.8 multipart endpoints. You must reject any pattern that collects whole payloads into memory, converts streaming chunks into contiguous vectors (`Vec<u8>`), or buffers unmetered streams without strict backpressure and fixed byte quotas. ## Strict Guidelines - Engineers MUST ALWAYS process multipart file uploads using incrementally drained `field.chunk().await` or `StreamAdapter` directly to an `AsyncWrite` sink. - Engineers MUST NOT call `field.bytes().await` or accumulate arbitrary chunks into in-memory collections (`Vec<u8>`, `BytesMut`) on file upload fields. - Handlers MUST track total accumulated bytes per field and terminate the connection immediately with `StatusCode::PAYLOAD_TOO_LARGE` if the limit is exceeded. - Services MUST enforce backpressure by awaiting the completion of each sink write operation before pulling the next chunk from the upstream wire buffer. - Payload streaming MUST retain zero-copy semantics by forwarding `bytes::Bytes` chunks directly to IO sinks without reallocation or clone duplication. ## Bad vs Good Implementations ### Axum 0.8 Streaming File Upload Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling `field.bytes().await` consumes the entire stream into an unbounded contiguous in-memory buffer. Multiplexed concurrent requests across HTTP/2 or HTTP/3 streams will cause massive memory allocation spikes, triggering OS OOM killers. ```rust use axum::{extract::Multipart, http::StatusCode, response::IntoResponse}; pub async fn upload_file(mut multipart: Multipart) -> Result<impl IntoResponse, StatusCode> { while let Some(field) = multipart.next_field().await.map_err(|_| StatusCode::BAD_REQUEST)? { let name = field.name().unwrap_or_default().to_string(); if name == "file" { // CRITICAL FLAW: Loads entire file into process heap memory. // Under 100 concurrent 500MB uploads, this causes immediate OOM. let data = field.bytes().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; tokio::fs::write("/tmp/uploaded_file.bin", &data) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } } Ok(StatusCode::OK) } ``` #### Production Standard (Correct) > **Standard**: Iterates over incoming chunks incrementally using `field.chunk().await`, enforces hard byte limits, writes directly to the disk sink to maintain backpressure, and retains bounded heap allocation of O(chunk_size) regardless of upload size. ```rust use axum::{extract::Multipart, http::StatusCode, response::IntoResponse}; use tokio::io::AsyncWriteExt; const MAX_FILE_SIZE_BYTES: u64 = 50 * 1024 * 1024; // 50 MiB strict per-stream quota 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)? { if field.name() == Some("file") { let mut out_file = tokio::fs::File::create("/tmp/uploaded_file.bin") .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; let mut bytes_received: u64 = 0; // Enforce backpressure: fetch chunk, write completely, then pull next while let Some(chunk) = field.chunk().await.map_err(|_| StatusCode::BAD_REQUEST)? { bytes_received = bytes_received .checked_add(chunk.len() as u64) .ok_or(StatusCode::PAYLOAD_TOO_LARGE)?; if bytes_received > MAX_FILE_SIZE_BYTES { return Err(StatusCode::PAYLOAD_TOO_LARGE); } // Zero-copy chunk forwarding to async disk sink with bounded memory footprint out_file .write_all(&chunk) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } out_file.flush().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } } Ok(StatusCode::CREATED) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Zero-Copy Multipart Stream Bounded Allocation Standard

Axum 0.8 Zero-Copy Multipart Stream Bounded Allocation Standard defines an industrial-grade behavioral standard for backend engineering. Enforces strict per-stream memory quotas and backpressure-driven chunk draining for multipart streaming uploads in Axum 0.8. Prevents catastrophic process memory exhaustion (OOM) and heap fragmentation caused by unbounded buffering under high-concurrency HTTP/2 and HTTP/3 multiplexing. 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 Accumulation via `field.bytes()` or Unmetered Heap Appends in Streaming 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	Unbounded In-Memory Accumulation via `field.bytes()` or Unmetered Heap Appends in Streaming 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 multipart file uploads using incrementally drained `field.chunk().await` or `StreamAdapter` directly to an `AsyncWrite` sink.

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.