Axum 0.8 & Tokio Cooperative Task Budgeting and Cancellation Architecture

--- description: Axum 0.8 & Tokio Cooperative Task Budgeting and Cancellation Architecture - Eliminates Tokio worker thread starvation and orphan resource leaks in Axum 0.8 streaming and reverse-proxy handlers by enforcing cooperative task yielding and hierarchical CancellationToken propagation. Ensures unbounded byte-stream iteration respects runtime execution budgets and cleanly unbinds upstream connections when downstream clients abort. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tokio-cooperative-cancellation-pipeline" --- # Axum 0.8 & Tokio Cooperative Task Budgeting and Cancellation Architecture > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Async Stream Loops Without Yielding or Hierarchical Cancellation Propagation ## System Constraints You are a Principal Rust Systems Architect enforcing strict Axum 0.8 and Tokio concurrency standards. You must mandate cooperative task budget yielding and hierarchical CancellationToken propagation across all streaming, long-polling, and proxy workloads to prevent executor thread starvation and zombie allocations. ## Strict Guidelines - Engineers MUST ALWAYS propagate `tokio_util::sync::CancellationToken` through request contexts into all secondary worker routines and spawned streaming handlers. - Engineers MUST NOT spawn detached Tokio tasks (`tokio::spawn`) inside Axum handlers without binding their lifecycle to a parent cancellation token or tracking `JoinHandle` abort handles. - Code SHOULD cooperatively yield control back to the Tokio executor (`tokio::task::yield_now().await`) at fixed frame/byte intervals during high-throughput un-paced stream processing loops to respect task poll budgets. - Services MUST monitor client disconnects via request drop or connection state watchdogs and trigger token cancellations to terminate downstream upstream network sockets immediately. - Components NEVER execute long-running CPU-bound encoding, hashing, or transformation steps directly inside the Tokio async worker loop; use `tokio::task::spawn_blocking` with explicit cancellation checks. ## Bad vs Good Implementations ### Unbounded Stream Ingestion & Detached Background Processing #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The spawned task is detached from the Axum request lifecycle. If the HTTP client disconnects, `stream.next()` may continue consuming or hang, the downstream processing is not cooperatively budgeted (`tokio::task::yield_now()` is missing), and the task will starve the Tokio worker thread without cancellation checks. ```rust use axum::{body::Body, extract::Request, response::IntoResponse}; use futures_util::StreamExt; pub async fn proxy_stream_handler(req: Request) -> impl IntoResponse { let mut stream = req.into_body().into_data_stream(); // CRITICAL BUG: Detached task has no cancellation binding or cooperative budget. // If the client disconnects or floods the endpoint, this task runs unbounded, // monopolizing the executor thread and leaking memory. tokio::spawn(async move { let mut total_bytes = 0usize; while let Some(chunk_res) = stream.next().await { if let Ok(chunk) = chunk_res { total_bytes += chunk.len(); // Heavy processing loop without yield or cancellation checks process_chunk_inline(&chunk); } } tracing::info!("Finished processing {total_bytes} bytes"); }); axum::http::StatusCode::ACCEPTED } fn process_chunk_inline(_data: &[u8]) { // synchronous unbudgeted processing } ``` #### Production Standard (Correct) > **Standard**: A hierarchical `CancellationToken` is tied to the request lifetime via `drop_guard`. `tokio::select!` with `biased;` prioritizes cancellation over stream polling. An explicit cooperative byte threshold calls `tokio::task::yield_now().await`, ensuring the worker pool is never starved by unbounded incoming streams. ```rust use axum::{body::Body, extract::Request, response::IntoResponse, http::StatusCode}; use futures_util::StreamExt; use tokio_util::sync::CancellationToken; const COOP_YIELD_THRESHOLD_BYTES: usize = 1024 * 1024; // 1 MB yield budget pub async fn proxy_stream_handler(req: Request) -> Result<impl IntoResponse, StatusCode> { let token = CancellationToken::new(); let child_token = token.child_token(); let mut stream = req.into_body().into_data_stream(); // Guard: Token drops when caller aborts or disconnects let _drop_guard = token.drop_guard(); let handle = tokio::spawn(async move { let mut accumulated_bytes = 0usize; loop { tokio::select! { biased; _ = child_token.cancelled() => { tracing::warn!("Client aborted: cooperative cancellation triggered"); break; } chunk_opt = stream.next() => { match chunk_opt { Some(Ok(chunk)) => { let len = chunk.len(); accumulated_bytes += len; // Offload CPU heavy work or process chunk safely process_chunk_safe(chunk).await; // Prevent executor thread starvation during high throughput if accumulated_bytes >= COOP_YIELD_THRESHOLD_BYTES { accumulated_bytes = 0; tokio::task::yield_now().await; } } Some(Err(err)) => { tracing::error!(%err, "Stream ingestion failure"); break; } None => break, } } } } }); // Retain handle reference or await termination contract Ok(StatusCode::ACCEPTED) } async fn process_chunk_safe(_chunk: axum::body::Bytes) { // Async or bounded operation } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 & Tokio Cooperative Task Budgeting and Cancellation Architecture

Axum 0.8 & Tokio Cooperative Task Budgeting and Cancellation Architecture defines an industrial-grade behavioral standard for backend engineering. Eliminates Tokio worker thread starvation and orphan resource leaks in Axum 0.8 streaming and reverse-proxy handlers by enforcing cooperative task yielding and hierarchical CancellationToken propagation. Ensures unbounded byte-stream iteration respects runtime execution budgets and cleanly unbinds upstream connections when downstream clients abort. 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 Async Stream Loops Without Yielding or Hierarchical Cancellation Propagation 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 Async Stream Loops Without Yielding or Hierarchical Cancellation Propagation	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 propagate `tokio_util

Engineers MUST ALWAYS propagate `tokio_util::sync::CancellationToken` through request contexts into all secondary worker routines and spawned streaming handlers.

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.