Axum 0.8 / Tower Deterministic Frame-Budgeted Multipart Streaming Invariant

--- description: Axum 0.8 / Tower Deterministic Frame-Budgeted Multipart Streaming Invariant - Enforces strict frame and memory budgeting on incoming multipart request streams within Axum 0.8 and Tower services. Prevents heap exhaustion and uncontrolled resource consumption triggered by unbuffered or malicious HTTP/3 DATA frame bursts by decoupling zero-copy network frames from unbounded heap allocators and asserting deterministic backpressure-aware quotas. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-0-8-tower-frame-budgeted-streaming-invariant" --- # Axum 0.8 / Tower Deterministic Frame-Budgeted Multipart Streaming Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Stream Ingestion and Naive Multipart Unwrapping Permitting HTTP/3 Frame Amplification OOM ## System Constraints You are a Principal Systems and Security Architect enforcing Axum 0.8 and Tower invariants for mission-critical HTTP/3 streaming. Mandate strict frame budgets, bounded streaming extraction, and zero-allocation chunk consumption to eliminate memory exhaustion vectors. ## Strict Guidelines - Engineers MUST ALWAYS enforce explicit byte and frame budgets at the Tower layer using `http_body_util::Limited` or Axum's `DefaultBodyLimit::disable` combined with explicit per-field bounded streams. - Engineers MUST NOT rely on default `Multipart::next_field` without an ambient or field-scoped size limit; raw frame extraction without byte counters allows an attacker to stream infinite single-field payloads. - Services MUST apply cooperative backpressure by polling body frames with bounded capacity buffers rather than collecting chunks into intermediate `Vec<u8>` or `BytesMut` structures without hard ceilings. - Engineers MUST configure Tower's `ServiceBuilder` with connection-level and stream-level concurrency barriers (e.g., `tower::limit::ConcurrencyLimit`) to prevent parallel HTTP/3 multi-stream amplification. - Handlers MUST map quota and frame-budget violations deterministically to `StatusCode::PAYLOAD_TOO_LARGE` (413) without draining remaining trailing frames from the offending socket. ## Bad vs Good Implementations ### Multipart Ingestion: Unbounded Collection vs. Frame-Budgeted Stream Processing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The handler polls incoming chunks directly into an unbounded Vec<u8> across the multipart field. A client streaming high-throughput HTTP/3 DATA frames without a specified Content-Length can exploit connection-level flow control to cause rapid heap exhaustion and crash the process via the OOM killer. ```rust use axum::extract::Multipart; use axum::http::StatusCode; use axum::response::IntoResponse; // ANTI-PATTERN: Ingests chunks directly without frame budgets or field limits. // Under HTTP/3, malicious peer sends infinite DATA frames, exhausting memory. pub async fn upload_handler(mut multipart: Multipart) -> Result<impl IntoResponse, StatusCode> { while let Some(mut field) = multipart.next_field().await.map_err(|_| StatusCode::BAD_REQUEST)? { let mut accumulated_bytes = Vec::new(); // Unbounded accumulation directly into host heap while let Some(chunk) = field.chunk().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)? { accumulated_bytes.extend_from_slice(&chunk); } tokio::fs::write("/tmp/upload.bin", &accumulated_bytes) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } Ok(StatusCode::OK) } ``` #### Production Standard (Correct) > **Standard**: The compliant implementation enforces dual constraints: each received chunk is verified against a 64 KiB frame budget (`MAX_CHUNK_LIMIT`) and total field consumption is monotonically checked against a strict 10 MiB limit (`MAX_FIELD_BYTES`). Chunks are streamed directly to disk via `AsyncWriteExt` without unbounded heap buffering, maintaining zero-copy semantics and deterministic backpressure. ```rust use axum::extract::Multipart; use axum::http::StatusCode; use axum::response::IntoResponse; use tokio::io::AsyncWriteExt; const MAX_FIELD_BYTES: usize = 10 * 1024 * 1024; // 10 MiB frame budget const MAX_CHUNK_LIMIT: usize = 64 * 1024; // 64 KiB zero-copy frame budget pub async fn upload_handler(mut multipart: Multipart) -> Result<impl IntoResponse, StatusCode> { while let Some(mut field) = multipart.next_field().await.map_err(|_| StatusCode::BAD_REQUEST)? { let mut file = tokio::fs::File::create("/tmp/upload.bin") .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; let mut total_field_bytes: usize = 0; // Enforce deterministic backpressure and frame quota checks while let Some(chunk) = field.chunk().await.map_err(|_| StatusCode::BAD_REQUEST)? { if chunk.len() > MAX_CHUNK_LIMIT { return Err(StatusCode::BAD_REQUEST); // Frame payload exceeds protocol budget } total_field_bytes = total_field_bytes .checked_add(chunk.len()) .ok_or(StatusCode::PAYLOAD_TOO_LARGE)?; if total_field_bytes > MAX_FIELD_BYTES { return Err(StatusCode::PAYLOAD_TOO_LARGE); } file.write_all(&chunk) .await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; } } Ok(StatusCode::OK) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 / Tower Deterministic Frame-Budgeted Multipart Streaming Invariant

Axum 0.8 / Tower Deterministic Frame-Budgeted Multipart Streaming Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces strict frame and memory budgeting on incoming multipart request streams within Axum 0.8 and Tower services. Prevents heap exhaustion and uncontrolled resource consumption triggered by unbuffered or malicious HTTP/3 DATA frame bursts by decoupling zero-copy network frames from unbounded heap allocators and asserting deterministic backpressure-aware quotas. 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 Stream Ingestion and Naive Multipart Unwrapping Permitting HTTP/3 Frame Amplification OOM 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 Stream Ingestion and Naive Multipart Unwrapping Permitting HTTP/3 Frame Amplification OOM	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 and frame budgets at the Tower layer using `http_body_util

Engineers MUST ALWAYS enforce explicit byte and frame budgets at the Tower layer using `http_body_util::Limited` or Axum's `DefaultBodyLimit::disable` combined with explicit per-field bounded streams.

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.