Axum 0.8 Zero-Copy Streaming & Cooperative Cancellation Guardrail

--- description: Axum 0.8 Zero-Copy Streaming & Cooperative Cancellation Guardrail - Enforces strict zero-copy chunk streaming and deterministic cooperative cancellation for Axum 0.8 backends over HTTP/2 and HTTP/3. Guarantees that client disconnects, QUIC stream resets, and downstream backpressure propagate upstream to immediately halt resource consumption without orphan tasks or unbounded buffering. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-zero-copy-streaming-cancellation" --- # Axum 0.8 Zero-Copy Streaming & Cooperative Cancellation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded In-Memory Buffering and Orphaned Producer Loops on Client Disconnect ## System Constraints You are a Principal Rust Architect enforcing high-throughput, low-latency streaming standards for Axum 0.8. You mandate zero-copy byte streaming using `bytes::Bytes`, explicit backpressure management, and cooperative cancellation via `tokio_util::sync::CancellationToken` or RAII drop guards to prevent memory leaks and zombie async tasks when HTTP/2 or HTTP/3 streams are aborted. ## Strict Guidelines - Engineers MUST ALWAYS use `bytes::Bytes` or `axum::body::Body::from_stream` rather than collecting chunked bodies into intermediate `Vec<u8>` buffers in memory. - Engineers MUST NEVER spawn un-monitored background tasks (`tokio::spawn`) that produce stream data without binding them to client body lifecycle or a `CancellationToken`. - Code MUST handle cooperative cancellation by integrating `tokio_util::sync::CancellationToken` or relying on stream drop semantics to clean up upstream cursors (e.g., SQL cursors, S3 chunk readers, IPC sockets). - Services MUST enforce backpressure using bounded channels (such as `tokio::sync::mpsc::channel` with explicit capacities) or direct asynchronous streams (`futures_core::Stream`). - Components NEVER buffer unbounded request or response bodies without enforcing explicit maximum limits via `axum::extract::DefaultBodyLimit` or manual size checkpoints. ## Bad vs Good Implementations ### Unbounded Buffering and Orphaned Background Producer #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawns an asynchronous loop with an unbounded channel that does not cooperatively tie into the HTTP request lifecycle. When an HTTP/3 client sends `STOP_SENDING` or disconnects, the task may keep producing chunks into an unconsumed channel or lag significantly behind, causing unbounded heap allocation and thread pool contention. ```rust use axum::{body::Body, response::Response, routing::get, Router}; use tokio::sync::mpsc; pub fn routes() -> Router { Router::new().route("/stream", get(leak_stream_handler)) } async fn leak_stream_handler() -> Response { // Anti-pattern: Unbounded channel and unlinked tokio::spawn. // If the HTTP client disconnects (RESET_STREAM in HTTP/3), // this spawned task continues indefinitely, saturating memory. let (tx, mut rx) = mpsc::unbounded_channel(); tokio::spawn(async move { let mut count = 0u64; loop { let payload = format!("chunk-{count}\n").into_bytes(); if tx.send(payload).is_err() { break; } count += 1; tokio::time::sleep(std::time::Duration::from_millis(10)).await; } }); let stream = async_stream::stream! { while let Some(chunk) = rx.recv().await { yield Ok::<_, std::io::Error>(chunk); } }; Response::new(Body::from_stream(stream)) } ``` #### Production Standard (Correct) > **Standard**: Utilizes `bytes::Bytes` for zero-copy allocations and ties stream execution directly to `CancellationToken` and drop semantics. If the HTTP client drops connection or QUIC resets the stream, the stream drop guard trips, aborting upstream producers immediately and preventing memory exhaustion. ```rust use axum::{body::Body, response::{IntoResponse, Response}, routing::get, Router}; use bytes::Bytes; use futures_util::stream::Stream; use std::{io, time::Duration}; use tokio_util::sync::CancellationToken; pub fn routes() -> Router { Router::new().route("/stream", get(safe_stream_handler)) } async fn safe_stream_handler() -> Response { let token = CancellationToken::new(); let child_token = token.child_token(); // Zero-copy stream with bounded generation and cancellation linkage let stream = async_stream::try_stream! { // RAII guard ensuring token is cancelled when stream drops (e.g. client disconnects) let _guard = token.drop_guard(); let mut count = 0u64; loop { tokio::select! { biased; _ = child_token.cancelled() => { break; } _ = tokio::time::sleep(Duration::from_millis(10)) => { let chunk = Bytes::from(format!("chunk-{count}\n")); yield chunk; count += 1; } } } }; into_zero_copy_response(stream) } fn into_zero_copy_response<S>(stream: S) -> Response where S: Stream<Item = Result<Bytes, io::Error>> + Send + 'static, { Body::from_stream(stream).into_response() } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Zero-Copy Streaming & Cooperative Cancellation Guardrail

Axum 0.8 Zero-Copy Streaming & Cooperative Cancellation Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict zero-copy chunk streaming and deterministic cooperative cancellation for Axum 0.8 backends over HTTP/2 and HTTP/3. Guarantees that client disconnects, QUIC stream resets, and downstream backpressure propagate upstream to immediately halt resource consumption without orphan tasks or unbounded 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 Buffering and Orphaned Producer Loops on Client Disconnect 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 Buffering and Orphaned Producer Loops on Client Disconnect	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 use `bytes

Engineers MUST ALWAYS use `bytes::Bytes` or `axum::body::Body::from_stream` rather than collecting chunked bodies into intermediate `Vec<u8>` buffers in memory.

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.