Axum 0.8 Cooperative Workload Shedding and Client Cancellation Invariant

--- description: Axum 0.8 Cooperative Workload Shedding and Client Cancellation Invariant - Mandates explicit cooperative yielding, deterministic cancellation propagation via Tokio cancellation tokens, and bounded queue admission within Axum 0.8 HTTP pipelines. Eliminates runtime worker thread starvation and unbounded heap allocations during cascading upstream retries and abrupt 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-cooperative-load-shedding-cancellation" --- # Axum 0.8 Cooperative Workload Shedding and Client Cancellation Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded detached background spawning and unbudgeted async loops ignoring HTTP client disconnects. ## System Constraints You are a Principal Software Architect enforcing production-grade concurrency invariants for Axum 0.8 and Tokio runtimes. Mandate strict cancellation mechanics, bounded concurrency limits with load shedding, and cooperative task budgeting across all async handlers to prevent thread starvation and memory leaks under cascading retry storms. ## Strict Guidelines - Engineers MUST ALWAYS enforce upstream client disconnect detection by anchoring asynchronous tasks directly to the HTTP request future lifecycle or wiring an explicit `tokio_util::sync::CancellationToken`. - Engineers MUST NOT spawn detached tasks via `tokio::spawn` inside HTTP handlers without tracking them using `tokio_util::task::TaskTracker` or binding them to a scoped cancellation signal. - Code MUST apply backpressure and early rejection using Tower middleware (`tower::load_shed::LoadShedLayer` coupled with `tower::limit::ConcurrencyLimitLayer`) before request parsing occurs. - Services MUST yield control explicitly via `tokio::task::consume_budget().await` or `tokio::task::yield_now().await` inside tight asynchronous loops, deserialization passes, or batch iteration routines. - Components NEVER buffer unbounded request bodies or stream processing chunks into in-memory vectors (`Vec<u8>`) without enforcing strict byte limits via `axum::extract::DefaultBodyLimit` or `http_body_util::Limited`. - Handlers invoking long-running database transactions or external RPCs MUST wrap operations in `tokio::select!` with cancellation branches to guarantee immediate abort on client connection drop. ## Bad vs Good Implementations ### Unbounded Detached Processing vs. Cooperative Shedding and Cancellation #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawning detached work via `tokio::spawn` divorces execution from the HTTP socket connection. When an upstream client cancels or times out and retries, the orphaned background tasks accumulate monotonically in memory. The unbudgeted loop starves Tokio worker threads, leading to cascading service collapse. ```rust use axum::{extract::Json, routing::post, Router}; use serde::Deserialize; #[derive(Deserialize)] struct HeavyBatch { items: Vec<String> } // ANTI-PATTERN: Detached task ignores client disconnect; // no concurrency limit or load shedding; tight loop starves Tokio worker. async fn handle_batch(Json(payload): Json<HeavyBatch>) -> &'static str { tokio::spawn(async move { for item in payload.items { // Starves Tokio task budget in tight CPU/async iterations process_item(&item).await; } }); "Accepted" } pub fn app() -> Router { Router::new().route("/batch", post(handle_batch)) } async fn process_item(_: &str) {} ``` #### Production Standard (Correct) > **Standard**: Applies `LoadShedLayer` and `ConcurrencyLimitLayer` to reject excess requests with HTTP 503 rather than exhausting heap capacity. Work is kept within the request lifecycle, client disconnects drop the future immediately, and `tokio::task::consume_budget().await` yields cooperatively to prevent worker starvation. ```rust use axum::{ error_handling::HandleErrorLayer, extract::Json, http::StatusCode, response::IntoResponse, routing::post, BoxError, Router, }; use serde::Deserialize; use std::time::Duration; use tokio_util::sync::CancellationToken; use tower::{load_shed::LoadShedLayer, limit::ConcurrencyLimitLayer, ServiceBuilder}; #[derive(Deserialize)] struct HeavyBatch { items: Vec<String> } // INVARIANT: Request-scoped cancellation and explicit cooperative task budgeting async fn handle_batch(Json(payload): Json<HeavyBatch>) -> Result<&'static str, StatusCode> { let token = CancellationToken::new(); let drop_guard = token.clone().drop_guard(); for item in payload.items { if token.is_cancelled() { return Err(StatusCode::REQUEST_TIMEOUT); } // Enforce Tokio cooperative scheduling budget tokio::task::consume_budget().await; process_item(&item).await; } drop(drop_guard); Ok("Processed") } async fn handle_shed_error(err: BoxError) -> (StatusCode, String) { if err.is::<tower::load_shed::error::Overloaded>() { (StatusCode::SERVICE_UNAVAILABLE, "Server overloaded; load shed.".into()) } else { (StatusCode::INTERNAL_SERVER_ERROR, format!("Unhandled error: {err}")) } } pub fn app() -> Router { let middleware = ServiceBuilder::new() .layer(HandleErrorLayer::new(handle_shed_error)) .layer(LoadShedLayer::new()) // Reject immediately when saturated .layer(ConcurrencyLimitLayer::new(1024)); // Bound concurrent in-flight requests Router::new() .route("/batch", post(handle_batch)) .layer(middleware) } async fn process_item(_: &str) {} ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Cooperative Workload Shedding and Client Cancellation Invariant

Axum 0.8 Cooperative Workload Shedding and Client Cancellation Invariant defines an industrial-grade behavioral standard for backend engineering. Mandates explicit cooperative yielding, deterministic cancellation propagation via Tokio cancellation tokens, and bounded queue admission within Axum 0.8 HTTP pipelines. Eliminates runtime worker thread starvation and unbounded heap allocations during cascading upstream retries and abrupt 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 detached background spawning and unbudgeted async loops ignoring HTTP client disconnects. 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 detached background spawning and unbudgeted async loops ignoring HTTP client disconnects.	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 enforce upstream client disconnect detection by anchoring asynchronous tasks directly to the HTTP request future lifecycle or wiring an explicit `tokio_util

Engineers MUST ALWAYS enforce upstream client disconnect detection by anchoring asynchronous tasks directly to the HTTP request future lifecycle or wiring an explicit `tokio_util::sync::CancellationToken`.

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.