Axum 0.8 Cancel-Safe Graceful Shutdown and In-Flight Request Drain Barrier

--- description: Axum 0.8 Cancel-Safe Graceful Shutdown and In-Flight Request Drain Barrier - Enforces cancel-safe execution guarantees, transactional commit protection, and streaming response drain barriers during rolling container evictions in Axum 0.8. Prevents silent rollback of in-flight business mutations and abrupt HTTP/2 RST_STREAM errors on active clients. globs: src/**/*.rs, Cargo.toml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-graceful-shutdown-drain-barrier" --- # Axum 0.8 Cancel-Safe Graceful Shutdown and In-Flight Request Drain Barrier > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Truncating in-flight streaming responses and rolling back database transactions via unmanaged future drops during SIGTERM ## System Constraints You are a Principal Rust Architect enforcing Axum 0.8 Graceful Shutdown Cancel-Safe In-Flight Request Drain Barriers. Mandate invariants that prevent abrupt future cancellation drops during container SIGTERM/SIGINT events. Require tokio_util::task::TaskTracker and CancellationToken to protect streaming body completion and explicit transaction boundary stabilization. ## Strict Guidelines - Engineers MUST ALWAYS integrate tokio_util::task::TaskTracker with axum::serve::with_graceful_shutdown to track active background pipelines and ongoing critical requests. - Engineers MUST NOT allow non-cancel-safe database operations (e.g., intermediate multi-statement SQL writes without drop guards) to execute in contexts subject to direct tokio::select! branch cancellation. - Services MUST enforce a two-phase shutdown lifecycle: Phase 1 stops accepting new TCP connections via the listener, Phase 2 drains in-flight requests up to a hard deadline before process termination. - Handlers streaming response bodies (SSE, chunked data) MUST monitor a CancellationToken or connection drop to emit clean EOF/trailers rather than panicking or leaking open server resources. - Components NEVER spawn unmanaged futures via tokio::spawn without binding them to a tracked lifecycle guard or TaskTracker instance during server shutdown. ## Bad vs Good Implementations ### Graceful Shutdown Server Pipeline and Drain Barrier #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: The server terminates abruptly upon receiving a process signal (SIGTERM/SIGINT). Any in-flight HTTP connections and detached tokio::spawn futures are dropped immediately, leaving database transactions in half-committed rollbacks and triggering RST_STREAM errors on downstream clients. ```rust use axum::{routing::get, Router}; use tokio::net::TcpListener; #[tokio::main] async fn main() { let app = Router::new().route("/process", get(|| async { // ANTI-PATTERN: Spawning untracked background work that drops // mid-transaction when SIGTERM abruptly cancels the runtime. tokio::spawn(async { tokio::time::sleep(std::time::Duration::from_secs(5)).await; // Database commit aborted silently on pod eviction }); "Accepted" })); let listener = TcpListener::bind("0.0.0.0:3000").await.unwrap(); // Raw serve with no graceful signal handling or connection drain barrier axum::serve(listener, app).await.unwrap(); } ``` #### Production Standard (Correct) > **Standard**: This pattern registers a standard UNIX signal listener, signals the cancellation token, allows Axum 0.8's native with_graceful_shutdown to stop accepting new connections, and uses tokio_util::task::TaskTracker with a hard timeout barrier to drain in-flight operations before exiting. ```rust use axum::{routing::get, Router, extract::State}; use std::time::Duration; use tokio::net::TcpListener; use tokio::signal::unix::{signal, SignalKind}; use tokio_util::sync::CancellationToken; use tokio_util::task::TaskTracker; #[derive(Clone)] struct AppState { tracker: TaskTracker, token: CancellationToken, } async fn shutdown_signal(token: CancellationToken) { let mut sigterm = signal(SignalKind::terminate()).expect("failed to install SIGTERM handler"); let mut sigint = signal(SignalKind::interrupt()).expect("failed to install SIGINT handler"); tokio::select! { _ = sigterm.recv() => {} _ = sigint.recv() => {} } token.cancel(); } #[tokio::main] async fn main() { let tracker = TaskTracker::new(); let token = CancellationToken::new(); let state = AppState { tracker: tracker.clone(), token: token.clone() }; let app = Router::new() .route("/process", get(|State(s): State<AppState>| async move { s.tracker.spawn(async move { // Tracked critical work guaranteed to be waited on during drain tokio::time::sleep(Duration::from_secs(2)).await; }); "Processing started" })) .with_state(state); let listener = TcpListener::bind("0.0.0.0:3000").await.unwrap(); // Axum 0.8 graceful shutdown binding let server = axum::serve(listener, app) .with_graceful_shutdown(shutdown_signal(token.clone())); if let Err(err) = server.await { eprintln!("Server error: {err}"); } // Drain barrier: close tracker to new tasks and await in-flight tasks with timeout tracker.close(); tokio::select! { _ = tracker.wait() => eprintln!("All in-flight requests drained cleanly."), _ = tokio::time::sleep(Duration::from_secs(10)) => eprintln!("Drain timeout exceeded. Forcing exit."), } } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Cancel-Safe Graceful Shutdown and In-Flight Request Drain Barrier

Axum 0.8 Cancel-Safe Graceful Shutdown and In-Flight Request Drain Barrier defines an industrial-grade behavioral standard for backend engineering. Enforces cancel-safe execution guarantees, transactional commit protection, and streaming response drain barriers during rolling container evictions in Axum 0.8. Prevents silent rollback of in-flight business mutations and abrupt HTTP/2 RST_STREAM errors on active clients. 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: Truncating in-flight streaming responses and rolling back database transactions via unmanaged future drops during SIGTERM 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	Truncating in-flight streaming responses and rolling back database transactions via unmanaged future drops during SIGTERM	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 integrate tokio_util

Engineers MUST ALWAYS integrate tokio_util::task::TaskTracker with axum::serve::with_graceful_shutdown to track active background pipelines and ongoing critical requests.

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.