Axum 0.8 Tokio Cooperative Task Budgeting and Streaming Backpressure Guardrail

--- description: Axum 0.8 Tokio Cooperative Task Budgeting and Streaming Backpressure Guardrail - Enforces strict bounded channels, explicit Tokio cooperative task budget yielding, and client-driven backpressure on all streaming HTTP response pipelines in Axum 0.8. Eliminates Tokio thread starvation, unbounded heap growth, and runaway producer tasks when downstream clients read slowly or disconnect prematurely. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tokio-streaming-backpressure-standard" --- # Axum 0.8 Tokio Cooperative Task Budgeting and Streaming Backpressure Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Channel Buffering and Tight Serialization Loops in Axum Streaming Endpoints ## System Constraints You are a Principal Rust Systems Architect specializing in Tokio runtime performance and Axum 0.8 distributed services. Your mandate is to enforce non-starving asynchronous streaming backpressure across all Axum HTTP handlers, ensure tight generation loops yield to Tokio's cooperative scheduler, and mandate strictly bounded transmission watermarks. ## Strict Guidelines - Engineers MUST ALWAYS use bounded channels (e.g., `tokio::sync::mpsc::channel` with a fixed watermark) or native `Stream` combinators when bridging async producers to Axum's `Body::from_stream`. - Engineers MUST NOT use `tokio::sync::mpsc::unbounded_channel` or unbounded in-memory queues for HTTP chunk generation or SSE (Server-Sent Events) feeds. - Producers executing iterative chunk generation MUST explicitly invoke `tokio::task::consume_budget().await` or `tokio::task::yield_now().await` periodically during CPU-bound serialization phases to prevent Tokio worker thread starvation. - Handlers MUST bind downstream transmission backpressure directly to database cursors, object store downloads, or data generators so producer speed is throttled by client consumption rate. - Streaming tasks MUST handle downstream disconnection cleanly by ensuring producer tasks terminate immediately upon receiver channel closure or `tokio::select!` cancellation. - Engineers MUST configure appropriate HTTP buffer limits using Axum 0.8 extractor limits (`DefaultBodyLimit`) and chunk allocation pools using `bytes::Bytes` slicing rather than reallocating buffers per chunk. ## Bad vs Good Implementations ### Unbounded Channel Streaming with Starvation Loop vs. Bounded Backpressured Stream #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using an unbounded channel causes memory usage to scale linearly with dataset size if the client has high latency or limits bandwidth. Additionally, the producer loop never yields its Tokio task budget, monopolizing the executor thread and causing high P99 latencies for other requests. ```rust use axum::{body::Body, response::IntoResponse, routing::get, Router}; use tokio::sync::mpsc; use tokio_stream::wrappers::UnboundedReceiverStream; async fn export_records() -> impl IntoResponse { // ANTI-PATTERN: Unbounded channel removes backpressure entirely. // A slow HTTP client will cause the producer to buffer the entire table in RAM. let (tx, rx) = mpsc::unbounded_channel(); tokio::spawn(async move { for id in 0..1_000_000 { // ANTI-PATTERN: Tight serialization loop without cooperative scheduling yields. // Starves Tokio worker threads under high concurrent request volume. let payload = format!("{{\"id\": {}, \"data\": \"record_{}\"}}\n", id, id); let _ = tx.send(Ok::<_, std::io::Error>(payload)); } }); Body::from_stream(UnboundedReceiverStream::new(rx)) } ``` #### Production Standard (Correct) > **Standard**: Uses a bounded channel with capacity 32, stopping generation when the HTTP consumer falls behind. Incorporates `tokio::task::consume_budget().await` to cooperate with the Tokio task scheduler, and immediately aborts generation if `tx.send().await` returns an error due to client disconnection. ```rust use axum::{body::Body, response::{IntoResponse, Response}, http::StatusCode}; use bytes::Bytes; use tokio::sync::mpsc; use tokio_stream::wrappers::ReceiverStream; const STREAM_BUFFER_CAPACITY: usize = 32; pub async fn export_records() -> Response { // INVARIANT: Fixed-capacity bounded channel enforces transmission backpressure. let (tx, rx) = mpsc::channel::<Result<Bytes, std::io::Error>>(STREAM_BUFFER_CAPACITY); tokio::spawn(async move { for id in 0..1_000_000 { // Cooperative task budgeting: yield to Tokio runtime if budget exhausted tokio::task::consume_budget().await; let chunk = Bytes::from(format!("{{\"id\": {}, \"data\": \"record_{}\"}}\n", id, id)); // Backpressure enforcement: send blocks when downstream buffer fills, // and breaks immediately if the client disconnects (rx dropped). if tx.send(Ok(chunk)).await.is_err() { tracing::debug!(target: "streaming", "Client disconnected, aborting generation"); break; } } }); let stream = ReceiverStream::new(rx); Body::from_stream(stream).into_response() } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tokio Cooperative Task Budgeting and Streaming Backpressure Guardrail

Axum 0.8 Tokio Cooperative Task Budgeting and Streaming Backpressure Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces strict bounded channels, explicit Tokio cooperative task budget yielding, and client-driven backpressure on all streaming HTTP response pipelines in Axum 0.8. Eliminates Tokio thread starvation, unbounded heap growth, and runaway producer tasks when downstream clients read slowly or disconnect prematurely. 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 Tight Serialization Loops in Axum Streaming Endpoints 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 Tight Serialization Loops in Axum Streaming Endpoints	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 bounded channels (e.g., `tokio

Engineers MUST ALWAYS use bounded channels (e.g., `tokio::sync::mpsc::channel` with a fixed watermark) or native `Stream` combinators when bridging async producers to Axum's `Body::from_stream`.

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.