Axum 0.8 Extractor-Driven Zero-Copy Multipart Streaming Invariants

--- description: Axum 0.8 Extractor-Driven Zero-Copy Multipart Streaming Invariants - Enforces strict zero-copy streaming invariants for high-throughput multipart ingestion in Rust Axum 0.8 services. Prohibits in-memory payload aggregation into vectors or intermediate buffers, mandating chunk-level direct piping to sinks via tokio_util and bounded backpressure extractors. Guarantees predictable, sub-megabyte resident set size (RSS) per connection during concurrent multi-gigabit payload transfers. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rust-axum-zero-copy-streaming-guardrail" --- # Axum 0.8 Extractor-Driven Zero-Copy Multipart Streaming Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Heap Buffer Accumulation via In-Memory Ingestion of Multipart Payloads (e.g., field.bytes().await or Vec<u8> Aggregation) ## System Constraints You are a Principal Rust Architect enforcing zero-allocation, backpressure-driven streaming patterns in Axum 0.8. Mandate strict chunk-to-sink forwarding, reject any in-memory buffering or premature payload realization, and enforce compile-time extractor guarantees. ## Strict Guidelines - Engineers MUST ALWAYS pipe Axum 0.8 `Multipart` fields directly to target `tokio::io::AsyncWrite` sinks using `tokio_util::io::StreamReader` or continuous chunk iteration (`field.chunk().await`). - Engineers MUST NOT call `field.bytes().await`, `field.text().await`, or `axum::body::to_bytes()` on unconstrained multipart file fields, as this buffers entire multi-gigabyte files into heap memory. - Handlers MUST explicitly configure `DefaultBodyLimit::disable()` ONLY at the route scope where custom extractor-level stream size accounting and rate limiting are actively enforced. - Streaming pipelines MUST preserve end-to-end backpressure by awaiting write operations on each received `Bytes` chunk before pulling subsequent chunks from the network frame. - Custom extractors SHOULD wrap `axum_extra::extract` or raw `axum::extract::FromRequest` implementations to enforce mime-type verification and chunked size invariants prior to handler execution. - Services MUST NEVER allocate intermediate dynamic collections (`Vec<u8>`, `BytesMut`) to inspect magic numbers; engineers must read only the fixed prefix window directly from the first stream chunk. ## Bad vs Good Implementations ### Axum 0.8 Multipart Stream Forwarding vs. In-Memory Buffering #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling `field.bytes().await` materializes the entire body into an unconstrained heap `Bytes` allocation. Under multi-gigabit concurrent ingestion, this causes severe RSS memory spikes, garbage collection/allocator lock contention, and rapid Linux OOM killer termination. ```rust use axum::{extract::Multipart, http::StatusCode, response::IntoResponse}; use tokio::fs::File; use tokio::io::AsyncWriteExt; pub async fn upload_bad(mut multipart: Multipart) -> Result<impl IntoResponse, StatusCode> { while let Some(field) = multipart.next_field().await.map_err(|_| StatusCode::BAD_REQUEST)? { if field.name() == Some("file") { // ANTI-PATTERN: Buffers multi-gigabit file entirely into heap RAM let data = field.bytes().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; let mut destination = File::create("/tmp/upload.bin") .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; destination.write_all(&data).await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } } Ok(StatusCode::OK) } ``` #### Production Standard (Correct) > **Standard**: Transforms the multipart chunk stream directly into a `StreamReader` and utilizes `tokio::io::copy` to pipe chunks straight into the target file descriptor. Allocations are strictly bounded to the internal 8KB buffer, applying backpressure to the TCP window and maintaining flat memory usage regardless of payload size. ```rust use axum::{extract::Multipart, http::StatusCode, response::IntoResponse}; use futures_util::TryStreamExt; use std::io; use tokio::fs::File; use tokio_util::io::StreamReader; pub async fn upload_good(mut multipart: Multipart) -> Result<impl IntoResponse, StatusCode> { while let Some(field) = multipart.next_field().await.map_err(|_| StatusCode::BAD_REQUEST)? { if field.name() == Some("file") { // Convert the field chunk stream into an AsyncRead without heap accumulation let body_stream = field.map_err(|err| io::Error::new(io::ErrorKind::Other, err)); let mut stream_reader = StreamReader::new(body_stream); let mut destination = File::create("/tmp/upload.bin") .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; // Zero-copy stream pipe with bounded OS-level TCP buffer backpressure tokio::io::copy(&mut stream_reader, &mut destination) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } } Ok(StatusCode::OK) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Extractor-Driven Zero-Copy Multipart Streaming Invariants

Axum 0.8 Extractor-Driven Zero-Copy Multipart Streaming Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces strict zero-copy streaming invariants for high-throughput multipart ingestion in Rust Axum 0.8 services. Prohibits in-memory payload aggregation into vectors or intermediate buffers, mandating chunk-level direct piping to sinks via tokio_util and bounded backpressure extractors. Guarantees predictable, sub-megabyte resident set size (RSS) per connection during concurrent multi-gigabit payload transfers. 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: Heap Buffer Accumulation via In-Memory Ingestion of Multipart Payloads (e.g., field.bytes().await or Vec<u8> Aggregation) 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	Heap Buffer Accumulation via In-Memory Ingestion of Multipart Payloads (e.g., field.bytes().await or Vec<u8> Aggregation)	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 pipe Axum 0.8 `Multipart` fields directly to target `tokio

Engineers MUST ALWAYS pipe Axum 0.8 `Multipart` fields directly to target `tokio::io::AsyncWrite` sinks using `tokio_util::io::StreamReader` or continuous chunk iteration (`field.chunk().await`).

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.