Axum 0.8 Tokio Cooperative Task Scheduling Budget Guardrail

--- description: Axum 0.8 Tokio Cooperative Task Scheduling Budget Guardrail - Enforces preemption yield points and blocking offloads within Axum 0.8 middleware and extractors executing CPU-intensive serialization or validation workloads. Prevents long-running synchronous compute loops from starving Tokio runtime worker threads, eliminating tail-latency degradation and executor stalls under high concurrency. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tokio-cooperative-scheduling-budget-guardrail" --- # Axum 0.8 Tokio Cooperative Task Scheduling Budget Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded Synchronous Serialization Loops Starving Tokio Worker Threads ## System Constraints You are a Principal Rust Architect enforcing cooperative task scheduling invariants in Axum 0.8 and Tokio runtimes. You must prevent executor thread starvation caused by CPU-bound serialization, transformation, or validation in async contexts. Mandate the use of tokio::task::consume_budget, tokio::task::yield_now, or tokio::task::spawn_blocking whenever compute tasks risk exceeding the Tokio scheduling budget (typically >10-100 microseconds). ## Strict Guidelines - Engineers MUST ALWAYS offload serialization or deserialization of unbounded or large payloads (>64 KiB or arrays with dynamic length) to tokio::task::spawn_blocking instead of executing serde_json::from_slice / to_vec inline. - Engineers MUST NOT execute blocking or CPU-bound iterators/transforms directly inside Axum middleware, extractors, or async handler bodies without preemption checkpoints. - Batch-processing loops inside async streams or middleware MUST invoke tokio::task::consume_budget().await or tokio::task::yield_now().await every N iterations (e.g., every 64-128 items) to yield execution back to the Tokio scheduler. - Services MUST configure tokio-console or tracing-durations in staging environments to verify task poll times do not exceed 1 millisecond. - Custom Tower layers and Axum 0.8 middleware MUST NEVER perform synchronous cryptographic verification, heavy compression (e.g., zstd, flate2), or recursive schema validations on the reactor worker threads. ## Bad vs Good Implementations ### Axum 0.8 Batch Serialization Middleware / Handler #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Executing heavy serialization or hashing loops inside an async middleware function monopolizes the Tokio worker thread without yielding. Other cooperative async tasks assigned to the same worker thread experience extreme head-of-line blocking and tail latency. ```rust use axum::{extract::Request, middleware::Next, response::Response}; use serde::Serialize; #[derive(Serialize)] struct AuditRecord { id: u64, payload: Vec<u8> } // ANTI-PATTERN: Iterating over thousands of items synchronously // blocks the Tokio worker thread for tens of milliseconds. pub async fn audit_middleware(req: Request, next: Next) -> Response { let response = next.run(req).await; let records: Vec<AuditRecord> = fetch_large_audit_batch(); // CPU starvation: Synchronous loop blocks worker thread without yielding let mut aggregated_hash = 0u64; for record in &records { let serialized = serde_json::to_vec(&record).expect("serialization failed"); aggregated_hash = aggregated_hash.wrapping_add(serialized.len() as u64); } response } fn fetch_large_audit_batch() -> Vec<AuditRecord> { vec![] } ``` #### Production Standard (Correct) > **Standard**: By delegating heavy serialization and aggregation loops to `tokio::task::spawn_blocking`, Tokio worker threads remain strictly dedicated to low-latency I/O polling and event loop progression, preventing starvation under load. ```rust use axum::{extract::Request, middleware::Next, response::Response}; use serde::Serialize; #[derive(Clone, Serialize)] struct AuditRecord { id: u64, payload: Vec<u8> } // PRODUCTION INVARIANT: Offload CPU-heavy computation to a blocking thread pool // or introduce cooperative yield points using tokio::task::consume_budget. pub async fn audit_middleware(req: Request, next: Next) -> Response { let response = next.run(req).await; let records: Vec<AuditRecord> = fetch_large_audit_batch(); // Offload CPU-bound task off Tokio executor threads entirely let _aggregated_hash = tokio::task::spawn_blocking(move || { let mut hash = 0u64; for record in records { let serialized = serde_json::to_vec(&record).expect("serialization failed"); hash = hash.wrapping_add(serialized.len() as u64); } hash }) .await .map_err(|_| axum::http::StatusCode::INTERNAL_SERVER_ERROR); response } fn fetch_large_audit_batch() -> Vec<AuditRecord> { vec![] } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tokio Cooperative Task Scheduling Budget Guardrail

Axum 0.8 Tokio Cooperative Task Scheduling Budget Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces preemption yield points and blocking offloads within Axum 0.8 middleware and extractors executing CPU-intensive serialization or validation workloads. Prevents long-running synchronous compute loops from starving Tokio runtime worker threads, eliminating tail-latency degradation and executor stalls under high concurrency. 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 Synchronous Serialization Loops Starving Tokio Worker Threads 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 Synchronous Serialization Loops Starving Tokio Worker Threads	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 offload serialization or deserialization of unbounded or large payloads (>64 KiB or arrays with dynamic length) to tokio

Engineers MUST ALWAYS offload serialization or deserialization of unbounded or large payloads (>64 KiB or arrays with dynamic length) to tokio::task::spawn_blocking instead of executing serde_json::from_slice / to_vec inline.

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.