Axum 0.8 Tokio Cooperative Task-Budget Cancellation Standard

--- description: Axum 0.8 Tokio Cooperative Task-Budget Cancellation Standard - Mandates strict binding between Axum 0.8 client connection drops and Tokio cooperative cancellation tokens across streaming SSE, WebSocket, and long-polling conduits. Eliminates zombie background worker tasks and downstream connection-pool starvation by enforcing RAII-based cancellation propagation and cooperative budget yields on all asynchronous execution paths. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tokio-cooperative-cancellation-standard" --- # Axum 0.8 Tokio Cooperative Task-Budget Cancellation Standard > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning Detached Tokio Tasks in Handlers Without Client Disconnect Binding ## System Constraints You are a Principal Rust Architect enforcing the Axum 0.8 Tokio Cooperative Task-Budget Cancellation Standard. All asynchronous endpoints dealing with streaming responses (SSE, WebSockets, chunked streams) or long-running database queries MUST tie worker lifecycles to the transport connection state. When a client disconnects, Axum drops the response body stream; you must guarantee that any associated worker tasks, transactions, and resource allocations terminate immediately via cooperative cancellation tokens rather than running to unanchored completion. ## Strict Guidelines - Engineers MUST ALWAYS instantiate a `tokio_util::sync::CancellationToken` and propagate child tokens or drop guards to any spawned auxiliary task handling work for an Axum request. - Engineers MUST NOT call detached `tokio::spawn` inside request handlers without linking the spawned task to a cancellation mechanism that triggers when Axum drops the stream. - Services MUST utilize RAII drop guards (such as `token.drop_guard()`) attached to stream wrappers or `axum::response::sse::KeepAlive` configurations to signal disconnection instantaneously. - Background streaming loops MUST cooperatively poll cancellation via `tokio::select!` branches or `token.is_cancelled()` checks before acquiring database connections or performing I/O. - Engineers MUST ensure compute-heavy worker loops within streaming handlers regularly yield execution using `tokio::task::consume_budget().await` or `tokio::task::yield_now().await` to prevent starving the Tokio runtime reactor during high churn. ## Bad vs Good Implementations ### Axum 0.8 SSE Handler with Cooperative Cancellation vs Detached Zombie Task #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Spawning a detached Tokio task without a cancellation token decouples the background processing from the Axum HTTP connection. When the client closes the connection, Axum drops the receiver, but the spawned task continues to query the database, acquiring new pool connections and executing work for a phantom consumer. ```rust use axum::{response::sse::{Event, Sse}, extract::State}; use futures::stream::Stream; use tokio::sync::mpsc; use std::convert::Infallible; pub async fn stream_handler( State(pool): State<sqlx::PgPool>, ) -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let (tx, rx) = mpsc::channel(16); // ANTI-PATTERN: Detached task spawned with no awareness of client disconnect. // When the client drops the SSE stream, this loop continues running indefinitely, // pinning a database connection pool slot until the query sequence exhausts. tokio::spawn(async move { loop { let mut conn = pool.acquire().await.unwrap(); let data = sqlx::query!("SELECT pg_sleep(1), random() as val") .fetch_one(&mut *conn) .await .unwrap(); let event = Event::default().data(format!("value: {}", data.val.unwrap_or_default())); if tx.send(Ok(event)).await.is_err() { // Only exits after failing to send to channel, but DB queries continue executing // in-flight and connection starvation has already occurred. break; } } }); Sse::new(tokio_stream::wrappers::ReceiverStream::new(rx)) } ``` #### Production Standard (Correct) > **Standard**: A `CancellationToken` with an attached `drop_guard` captures the Axum stream lifecycle. When the client disconnects, Axum drops the stream, firing the drop guard and instantly cancelling all ongoing and subsequent database pool operations via biased `tokio::select!` branches, accompanied by cooperative budget yielding. ```rust use axum::{ extract::State, response::sse::{Event, Sse}, }; use futures::stream::{Stream, StreamExt}; use std::convert::Infallible; use std::time::Duration; use tokio_util::sync::CancellationToken; use tokio_stream::wrappers::ReceiverStream; pub async fn stream_handler( State(pool): State<sqlx::PgPool>, ) -> Sse<impl Stream<Item = Result<Event, Infallible>>> { let token = CancellationToken::new(); let child_token = token.child_token(); let (tx, rx) = tokio::sync::mpsc::channel(16); // SPAWN BOUND TASK: Strictly tied to cancellation token lifecycle tokio::spawn(async move { loop { tokio::select! { biased; _ = child_token.cancelled() => { tracing::info!("Client disconnected: terminating background query task immediately"); break; } // Acquire DB connection cooperatively with cancellation guard conn_res = pool.acquire() => { let mut conn = match conn_res { Ok(c) => c, Err(e) => { tracing::error!("Database acquisition failed: {e}"); break; } }; tokio::select! { biased; _ = child_token.cancelled() => break, query_res = sqlx::query!("SELECT pg_sleep(1), random() as val").fetch_one(&mut *conn) => { if let Ok(record) = query_res { let event = Event::default().data(format!("val: {}", record.val.unwrap_or_default())); if tx.send(Ok(event)).await.is_err() { break; } } } } } } // Yield cooperative budget to prevent reactor starvation tokio::task::consume_budget().await; } }); // RAII Drop Guard: Cancels the child task immediately when Axum drops the stream let drop_guard = token.drop_guard(); let stream = ReceiverStream::new(rx).map(move |item| { let _guard = &drop_guard; item }); Sse::new(stream).keep_alive( axum::response::sse::KeepAlive::new() .interval(Duration::from_secs(15)) .text("ping"), ) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Tokio Cooperative Task-Budget Cancellation Standard

Axum 0.8 Tokio Cooperative Task-Budget Cancellation Standard defines an industrial-grade behavioral standard for backend engineering. Mandates strict binding between Axum 0.8 client connection drops and Tokio cooperative cancellation tokens across streaming SSE, WebSocket, and long-polling conduits. Eliminates zombie background worker tasks and downstream connection-pool starvation by enforcing RAII-based cancellation propagation and cooperative budget yields on all asynchronous execution paths. 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: Spawning Detached Tokio Tasks in Handlers Without Client Disconnect Binding 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	Spawning Detached Tokio Tasks in Handlers Without Client Disconnect Binding	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 instantiate a `tokio_util

Engineers MUST ALWAYS instantiate a `tokio_util::sync::CancellationToken` and propagate child tokens or drop guards to any spawned auxiliary task handling work for an Axum request.

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.