Axum 0.8 Backpressure-Bounded Request Stream Invariant

--- description: Axum 0.8 Backpressure-Bounded Request Stream Invariant - Prevents async runtime memory pool exhaustion during large multipart and body stream ingest by ensuring TCP backpressure propagates upstream when internal downstream workers stall or disconnect. Guarantees that asynchronous task boundaries enforce bounded buffers and structured cancellation to mitigate unbounded memory growth during interrupted or slow-consumed streams. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-backpressure-bounded-request-stream-invariant" --- # Axum 0.8 Backpressure-Bounded Request Stream Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Channel Buffering and Detached Task Spawning in Axum Request Stream Consumption ## System Constraints You are a Principal Engineer enforcing the Axum 0.8 Backpressure-Bounded Request Stream Invariant. Mandate strict propagation of TCP backpressure from internal storage/processing sinks upstream to the Hyper/Tokio transport layer. Prohibit unbounded channels (`tokio::sync::mpsc::unbounded_channel`), detached background task loops reading from unthrottled request bodies, and decoupled buffer allocations across await points. Require bounded Tokio channels with explicit queue capacities, cancellation-aware task coordination via RAII or `CancellationToken`, and immediate abort of request body pulling when downstream consumer sinks fail or drop their receivers. ## Strict Guidelines - Engineers MUST ALWAYS enforce bounded Tokio channels (`tokio::sync::mpsc::channel(N)`) with small, deterministic capacities (e.g., 2–8 chunk buffers) when decoupling request stream ingestion from background consumer processing. - Engineers MUST NOT spawn detached tasks (`tokio::spawn`) that consume Axum `Multipart` or `BodyStream` without holding an `AbortHandle` or `CancellationToken` tied to the incoming HTTP request connection lifetime. - Engineers MUST propagate downstream channel full/close states back to the upstream HTTP stream by immediately stopping calls to `field.chunk().await` or `body.frame().await` upon send failure. - Code SHOULD prefer direct zero-copy stream processing (e.g., piping `Stream` directly into `tokio_util::io::StreamReader` or `AsyncWrite` sinks) over manual channel-based intermediary worker architectures. - Services MUST explicitly enforce payload boundaries via `tower_http::limit::RequestBodyLimitLayer` or controlled stream chunk counter gates to reject oversized payloads before runtime heap allocation spikes. ## Bad vs Good Implementations ### Multipart Stream Ingestion: Unbounded Channel Anti-Pattern vs. Bounded Backpressure Pipeline #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using `mpsc::unbounded_channel` buffers all incoming TCP frames directly into the Tokio runtime heap without yielding backpressure to the client socket. If the client streams faster than the spawned worker can process, or if the consumer slows down, memory consumption grows linearly with stream size until the allocator triggers an out-of-memory crash. ```rust use axum::{extract::Multipart, http::StatusCode, response::IntoResponse}; use tokio::sync::mpsc; pub async fn upload_handler(mut multipart: Multipart) -> Result<impl IntoResponse, StatusCode> { // ANTI-PATTERN: Unbounded channel removes TCP backpressure. // If downstream processing stalls, chunks buffer infinitely in RAM until OOM. let (tx, mut rx) = mpsc::unbounded_channel(); tokio::spawn(async move { while let Some(chunk) = rx.recv().await { // Slow downstream processing (e.g., remote object storage, transcoding) tokio::time::sleep(std::time::Duration::from_millis(50)).await; let _ = chunk; } }); while let Some(field) = multipart.next_field().await.map_err(|_| StatusCode::BAD_REQUEST)? { let mut field = field; while let Some(chunk) = field.chunk().await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)? { // Unbounded send never yields backpressure to hyper/TCP socket tx.send(chunk).unwrap(); } } Ok(StatusCode::OK) } ``` #### Production Standard (Correct) > **Standard**: Employs `mpsc::channel(4)` to bound internal queue depth. When the queue reaches capacity, `tx.send(chunk).await` pauses execution, halting calls to `field.chunk().await`. This causes Hyper to withhold TCP window updates, propagating hardware-level backpressure upstream to the client. If the worker encounters an error and drops `rx`, the producer terminates immediately without exhausting memory. ```rust use axum::{extract::Multipart, http::StatusCode, response::IntoResponse}; use tokio::sync::mpsc; use tokio_util::sync::CancellationToken; const STREAM_CHANNEL_CAPACITY: usize = 4; pub async fn upload_handler(mut multipart: Multipart) -> Result<impl IntoResponse, StatusCode> { // INVARIANT: Bounded channel enforces backpressure. let (tx, mut rx) = mpsc::channel::<bytes::Bytes>(STREAM_CHANNEL_CAPACITY); let cancel_token = CancellationToken::new(); let worker_token = cancel_token.clone(); let worker_handle = tokio::spawn(async move { tokio::select! { _ = worker_token.cancelled() => Err(StatusCode::REQUEST_TIMEOUT), res = async { while let Some(chunk) = rx.recv().await { // Downstream processing; backpressure is exerted when buffer fills tokio::time::sleep(std::time::Duration::from_millis(50)).await; let _ = chunk; } Ok(()) } => res, } }); while let Some(field) = multipart.next_field().await.map_err(|_| StatusCode::BAD_REQUEST)? { let mut field = field; while let Some(chunk) = field.chunk().await.map_err(|_| StatusCode::BAD_REQUEST)? { // Backpressure point: `send().await` suspends reading from socket if channel is full if tx.send(chunk).await.is_err() { // Consumer dropped rx or failed; abort reading immediately cancel_token.cancel(); return Err(StatusCode::INTERNAL_SERVER_ERROR); } } } drop(tx); // Signal EOF to consumer worker worker_handle.await .map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)? .map(|_| StatusCode::OK) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Backpressure-Bounded Request Stream Invariant

Axum 0.8 Backpressure-Bounded Request Stream Invariant defines an industrial-grade behavioral standard for backend engineering. Prevents async runtime memory pool exhaustion during large multipart and body stream ingest by ensuring TCP backpressure propagates upstream when internal downstream workers stall or disconnect. Guarantees that asynchronous task boundaries enforce bounded buffers and structured cancellation to mitigate unbounded memory growth during interrupted or slow-consumed streams. 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 Channel Buffering and Detached Task Spawning in Axum Request Stream Consumption 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 Channel Buffering and Detached Task Spawning in Axum Request Stream Consumption	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 bounded Tokio channels (`tokio

Engineers MUST ALWAYS enforce bounded Tokio channels (`tokio::sync::mpsc::channel(N)`) with small, deterministic capacities (e.g., 2–8 chunk buffers) when decoupling request stream ingestion from background consumer processing.

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.