Axum 0.8 Tokio Cooperative Task Budgeting & Cancellation Safety Standard

--- description: Axum 0.8 Tokio Cooperative Task Budgeting & Cancellation Safety Standard - Mandates explicit cooperative task budgeting and cancellation-safe branching across Axum 0.8 middleware, extractors, and request streaming pipelines. Guarantees that compute-bound or tight I/O iterations yield control back to the Tokio runtime executor to prevent multi-threaded thread-pool starvation, latency tail spikes, and corrupt state on client disconnects. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-0-8-tokio-cooperative-budgeting-standard" --- # Axum 0.8 Tokio Cooperative Task Budgeting & Cancellation Safety Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded iteration without cooperative budget checks and cancellation-unsafe futures in tokio::select! middleware branches ## System Constraints You are a Principal Rust Architect enforcing cooperative async runtime invariants in Axum 0.8 and Tokio. Every async routine that processes streaming bodies, iterative middleware pipelines, or CPU-adjacent decoding MUST explicitly interact with Tokio's cooperative budgeting subsystem (`tokio::task::consume_budget().await` or `tokio::task::yield_now().await`) and ensure all branches inside `tokio::select!` blocks are provably cancellation-safe. ## Strict Guidelines - Engineers MUST ALWAYS invoke `tokio::task::consume_budget().await` inside tight streaming body loops or batch token-validation routines to prevent multi-threaded runtime starvation. - Engineers MUST NOT place cancellation-unsafe futures (such as `AsyncReadExt::read`, multi-stage transactions, or unpinned partial writes) directly inside race conditions within `tokio::select!` branches without pinning state outside the macro. - Middleware pipelines processing multi-part or streaming request payloads MUST monitor connection termination via `axum::serve::IncomingConnection` and clean up state safely on abrupt client drop. - Services MUST route long-running, blocking CPU-bound tasks (such as Argon2/Bcrypt hashing, image transcoding, or heavy cryptographic validation) to `tokio::task::spawn_blocking` rather than saturating cooperative async worker pools. - Components NEVER execute raw synchronizing primitives (`std::sync::Mutex`, `std::sync::RwLock`) across `.await` points; all concurrent state within Axum extractors MUST utilize `tokio::sync` equivalents or decouple lock acquisition from async suspension. ## Bad vs Good Implementations ### Cancellation-Unsafe Stream Middleware vs. Cancellation-Safe Cooperative Budget Yielding #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Iterating over unbudgeted data streams starves the Tokio worker thread because cooperative budget limits are bypassed when stream processing is tightly coupled without yield points. Additionally, if wrapped in external timeouts or select! blocks, partially processed chunks drop without cleanup. ```rust use axum::{body::Body, extract::Request, middleware::Next, response::Response}; use futures_util::StreamExt; use tokio::io::AsyncReadExt; pub async fn unbudgeted_middleware(req: Request<Body>, next: Next) -> Response { let (parts, body) = req.into_parts(); let mut stream = body.into_data_stream(); let mut buffer = Vec::new(); // ANTI-PATTERN 1: Cancellation unsafe tokio::select! recreates read state on drop // ANTI-PATTERN 2: No cooperative budget yielding; starves executor under multi-megabyte streams while let Some(chunk_res) = stream.next().await { if let Ok(chunk) = chunk_res { buffer.extend_from_slice(&chunk); // Starves worker thread on large uploads: Tokio budget never checked } } let req = Request::from_parts(parts, Body::from(buffer)); next.run(req).await } ``` #### Production Standard (Correct) > **Standard**: Utilizes `tokio::task::consume_budget().await` on incoming data frames to cooperatively surrender execution time to other Tokio runtime tasks. Pins the frame reading inside a biased `tokio::select!` block to preserve partial buffers and enforce determinism. ```rust use axum::{body::Body, extract::Request, middleware::Next, response::{Response, IntoResponse}}; use bytes::BytesMut; use http::StatusCode; use futures_util::StreamExt; use tokio::task; pub async fn budgeted_cancellation_safe_middleware(req: Request<Body>, next: Next) -> Result<Response, StatusCode> { let (parts, body) = req.into_parts(); let mut stream = body.into_data_stream(); let mut buffer = BytesMut::with_capacity(8192); // Invariant: Yield control cooperatively to the Tokio executor // and ensure clean abort without dropping un-flushed partial state loop { tokio::select! { biased; chunk_opt = stream.next() => { match chunk_opt { Some(Ok(chunk)) => { buffer.extend_from_slice(&chunk); // Invariant: Explicitly consume Tokio budget to avoid thread starvation task::consume_budget().await; } Some(Err(_)) => return Err(StatusCode::BAD_REQUEST), None => break, } } _ = task::yield_now() => { // Secondary safety valve guaranteeing scheduler fairness under high packet density } } } let reconstructed_req = Request::from_parts(parts, Body::from(buffer.freeze())); Ok(next.run(reconstructed_req).await) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tokio Cooperative Task Budgeting & Cancellation Safety Standard

Axum 0.8 Tokio Cooperative Task Budgeting & Cancellation Safety Standard defines an industrial-grade behavioral standard for backend engineering. Mandates explicit cooperative task budgeting and cancellation-safe branching across Axum 0.8 middleware, extractors, and request streaming pipelines. Guarantees that compute-bound or tight I/O iterations yield control back to the Tokio runtime executor to prevent multi-threaded thread-pool starvation, latency tail spikes, and corrupt state on client disconnects. 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 iteration without cooperative budget checks and cancellation-unsafe futures in tokio::select! middleware branches 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 iteration without cooperative budget checks and cancellation-unsafe futures in tokio::select! middleware branches	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 invoke `tokio

Engineers MUST ALWAYS invoke `tokio::task::consume_budget().await` inside tight streaming body loops or batch token-validation routines to prevent multi-threaded runtime starvation.

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.