Axum 0.8 Backpressure Buffer Shedding & Client Disconnect Cancellation Guardrail

--- description: Axum 0.8 Backpressure Buffer Shedding & Client Disconnect Cancellation Guardrail - Enforces immediate cooperative cancellation of nested Tokio asynchronous tasks upon HTTP client disconnect in Axum 0.8 services. Mandates bounded concurrency queues with Tower LoadShed backpressure to protect executor thread pools and database connection pools from zombie compute cycles under sustained load spikes. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-0-8-backpressure-buffer-shedding-cancellation" --- # Axum 0.8 Backpressure Buffer Shedding & Client Disconnect Cancellation Guardrail > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Spawning detached Tokio tasks or utilizing unbounded buffers that leak CPU and I/O resources after client disconnect ## System Constraints You are a Principal Rust Systems Architect enforcing strict concurrency invariants in Axum 0.8 and Tokio. Mandate cooperative cancellation using CancellationToken or RAII guard wrappers for all nested async I/O and compute jobs. Strictly forbid detached `tokio::spawn` calls within request handlers without bidirectional cancellation links, and require Tower `LoadShedLayer` paired with bounded `BufferLayer` to prevent executor thread pool exhaustion during cascading client aborts. ## Strict Guidelines - Engineers MUST ALWAYS bind long-running background tasks spawned from request handlers to a child `tokio_util::sync::CancellationToken` dropped when the handler future terminates. - Engineers MUST NOT invoke fire-and-forget `tokio::spawn` for side effects (e.g., analytics, heavy DB updates, external API calls) within handlers unless explicitly coordinated via durable outbox queues or scoped supervisors. - Code SHOULD prefer running concurrent child futures within the handler lifecycle via `tokio::try_join!`, `tokio::select!`, or `futures::stream::FuturesUnordered` instead of detached `tokio::spawn`. - Services MUST configure `tower::load_shed::LoadShedLayer` immediately preceding bounded `tower::buffer::BufferLayer` or concurrency limits to shed excess traffic with `HTTP 503 Service Unavailable` rather than holding unbounded pending requests. - Components NEVER block Tokio worker threads with synchronous compute or blocking I/O; compute intensive routines MUST be offloaded to `tokio::task::spawn_blocking` and guarded by cancellation polling via `tokio_util::sync::CancellationToken::is_cancelled`. ## Bad vs Good Implementations ### Client Disconnect Cancellation and Load Shedding in Axum 0.8 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Calling `tokio::spawn` detaches execution from the incoming HTTP request future. If the client disconnects or times out before completion, the spawned task continues executing, burning CPU and monopolizing database connection pool slots. Furthermore, without bounded load shedding, the service starves the Tokio runtime under traffic bursts. ```rust use axum::{extract::State, routing::post, Json, Router}; use std::sync::Arc; #[derive(Clone)] struct AppState { db: Arc<Database> } // ANTI-PATTERN: Detached task runs to completion even if client disconnects. // Handler accepts infinite buffered work without shedding load. async fn handle_heavy_transcode( State(state): State<AppState>, Json(payload): Json<Payload>, ) -> &'static str { // Spawning detached future loses the connection drop signal tokio::spawn(async move { state.db.execute_heavy_query(&payload.id).await; perform_expensive_cpu_bound_work(&payload.data).await; }); "Accepted" } pub fn app(state: AppState) -> Router { Router::new() .route("/transcode", post(handle_heavy_transcode)) .with_state(state) } ``` #### Production Standard (Correct) > **Standard**: The handler registers a `CancellationToken` whose `DropGuard` triggers immediate cancellation across child tasks if the client aborts or disconnects. In addition, the Tower middleware pipeline combines `BufferLayer(1024)` with `LoadShedLayer` to fail fast with HTTP 503 instead of creating unbounded backlogs. ```rust use axum::{ error_handling::HandleErrorLayer, extract::State, http::StatusCode, routing::post, BoxError, Json, Router, }; use std::{sync::Arc, time::Duration}; use tokio_util::sync::CancellationToken; use tower::{buffer::BufferLayer, load_shed::LoadShedLayer, ServiceBuilder}; #[derive(Clone)] struct AppState { db: Arc<Database> } async fn handle_heavy_transcode( State(state): State<AppState>, Json(payload): Json<Payload>, ) -> Result<&'static str, StatusCode> { // Guard token: dropped automatically if client closes connection/handler future aborts let token = CancellationToken::new(); let child_token = token.child_token(); let db = state.db.clone(); let work_task = tokio::spawn(async move { tokio::select! { _ = child_token.cancelled() => { tracing::warn!(id = %payload.id, "Client disconnected, aborting background pipeline"); } res = async { db.execute_heavy_query(&payload.id).await; perform_cancellable_work(&payload.data, &child_token).await; } => { let _ = res; } } }); // Retain token in scope: if HTTP request drops, drop guard cancels child_token let _token_guard = token.drop_guard(); work_task.await.map_err(|_| StatusCode::INTERNAL_SERVER_ERROR)?; Ok("Completed") } pub fn app(state: AppState) -> Router { Router::new() .route("/transcode", post(handle_heavy_transcode)) .layer( ServiceBuilder::new() .layer(HandleErrorLayer::new(|err: BoxError| async move { if err.is::<tower::load_shed::error::Overloaded>() { StatusCode::SERVICE_UNAVAILABLE } else { StatusCode::INTERNAL_SERVER_ERROR } })) .layer(LoadShedLayer::new()) .layer(BufferLayer::new(1024)) .into_inner(), ) .with_state(state) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Backpressure Buffer Shedding & Client Disconnect Cancellation Guardrail

Axum 0.8 Backpressure Buffer Shedding & Client Disconnect Cancellation Guardrail defines an industrial-grade behavioral standard for backend engineering. Enforces immediate cooperative cancellation of nested Tokio asynchronous tasks upon HTTP client disconnect in Axum 0.8 services. Mandates bounded concurrency queues with Tower LoadShed backpressure to protect executor thread pools and database connection pools from zombie compute cycles under sustained load spikes. 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 or utilizing unbounded buffers that leak CPU and I/O resources after client disconnect 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 or utilizing unbounded buffers that leak CPU and I/O resources after client disconnect	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 bind long-running background tasks spawned from request handlers to a child `tokio_util

Engineers MUST ALWAYS bind long-running background tasks spawned from request handlers to a child `tokio_util::sync::CancellationToken` dropped when the handler future terminates.

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.