Axum 0.8 Deterministic HTTP/2 Graceful Draining Barrier

--- description: Axum 0.8 Deterministic HTTP/2 Graceful Draining Barrier - Enforces a two-phase connection draining barrier for Axum 0.8 and Tokio servers during orchestrated rolling deployments. Prevents client-side TCP resets and dropped HTTP/2 multiplexed streams by ensuring network mesh/ingress deregistration delays precede server shutdown, followed by deterministic HTTP/2 GOAWAY frame emission and in-flight request draining. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-tokio-graceful-connection-draining-barrier" --- # Axum 0.8 Deterministic HTTP/2 Graceful Draining Barrier > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Immediate Process Termination and Abrupt Socket Drops During Ingress Rollouts ## System Constraints You are a Principal Systems Engineer enforcing strict connection lifecycle management for Axum 0.8 and Hyper on Tokio runtime. Mandate that all production service listeners implement a two-phase graceful shutdown barrier: first, a configurable deregistration buffer period permitting cluster load balancers (e.g., Kubernetes Endpoints, Envoy, AWS ALB) to detach the pod from routing tables without dropping new handshakes; second, a deterministic server-level graceful draining signal that dispatches HTTP/2 GOAWAY frames with NO_ERROR and waits for active requests to complete under a strict bounded deadline. ## Strict Guidelines - Engineers MUST ALWAYS implement a two-stage shutdown barrier that sleeps for an ingress-propagation window (typically 5-15s) upon receiving SIGTERM before triggering server socket closure. - Engineers MUST NOT abruptly abort Tokio listener tasks or invoke `std::process::exit()` while active HTTP/1.1 keep-alive or HTTP/2 multiplexed TCP streams exist. - Services MUST utilize Axum 0.8's native `.with_graceful_shutdown(...)` or Hyper's `GracefulShutdown` primitives instead of wrapping `axum::serve` in a canceling `tokio::select!` branch. - Code SHOULD configure HTTP/2 keep-alive intervals, adaptive ping timeouts, and max concurrent streams to prevent ghost connections during deployment boundaries. - Components NEVER drop in-flight request futures without enforcing a bounded drain timeout to avoid zombie worker deadlocks during graceful shutdowns. ## Bad vs Good Implementations ### Two-Phase Graceful Draining Barrier in Axum 0.8 #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Canceling `axum::serve` directly inside `tokio::select!` or invoking `std::process::exit` immediately severs active TCP sockets. In HTTP/2, this drops multiplexed streams without transmitting a final GOAWAY frame. Additionally, failing to wait for load-balancer deregistration leads to 502 Bad Gateway errors as in-flight requests hit terminating pods. ```rust use axum::{routing::get, Router}; use tokio::net::TcpListener; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let app = Router::new().route("/health", get(|| async { "OK" })); let listener = TcpListener::bind("0.0.0.0:8080").await?; // ANTI-PATTERN: Wrapping axum::serve inside tokio::select with abrupt cancellation. // Terminating immediately on SIGINT/SIGTERM abruptly drops active TCP sockets, // triggers client-side ECONNRESET, and drops HTTP/2 multiplexed streams without GOAWAY. tokio::select! { res = axum::serve(listener, app) => res?, _ = tokio::signal::ctrl_c() => { eprintln!("Received shutdown signal. Exiting immediately."); std::process::exit(0); } } Ok(()) } ``` #### Production Standard (Correct) > **Standard**: By decoupling the initial SIGTERM detection from Hyper's graceful shutdown trigger, Kubernetes kube-proxy and cloud load balancers have time to evict the pod endpoint before connection acceptance ceases. Axum's native `with_graceful_shutdown` then initiates hyper's graceful shutdown sequence, sending HTTP/2 GOAWAY frames and allowing in-flight requests to complete cleanly. ```rust use axum::{routing::get, Router}; use std::time::Duration; use tokio::net::TcpListener; use tokio::signal::unix::{signal, SignalKind}; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { let app = Router::new().route("/health", get(|| async { "OK" })); let listener = TcpListener::bind("0.0.0.0:8080").await?; // PRODUCTION INVARIANT: Use native with_graceful_shutdown with a two-phase barrier axum::serve(listener, app) .with_graceful_shutdown(shutdown_barrier(Duration::from_secs(10))) .await?; Ok(()) } async fn shutdown_barrier(ingress_propagation_delay: Duration) { 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() => tracing::info!("SIGTERM received: initiating shutdown barrier"), _ = sigint.recv() => tracing::info!("SIGINT received: initiating shutdown barrier"), } // Phase 1: Wait for Kubernetes Endpoints / Service Mesh to route traffic away tracing::info!("Phase 1: Sleeping for ingress deregistration window"); tokio::time::sleep(ingress_propagation_delay).await; // Phase 2: Signal Axum/Hyper to stop accepting new sockets and send HTTP/2 GOAWAY frames tracing::info!("Phase 2: Signaling server connection draining"); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Deterministic HTTP/2 Graceful Draining Barrier

Axum 0.8 Deterministic HTTP/2 Graceful Draining Barrier defines an industrial-grade behavioral standard for backend engineering. Enforces a two-phase connection draining barrier for Axum 0.8 and Tokio servers during orchestrated rolling deployments. Prevents client-side TCP resets and dropped HTTP/2 multiplexed streams by ensuring network mesh/ingress deregistration delays precede server shutdown, followed by deterministic HTTP/2 GOAWAY frame emission and in-flight request draining. 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: Immediate Process Termination and Abrupt Socket Drops During Ingress Rollouts 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	Immediate Process Termination and Abrupt Socket Drops During Ingress Rollouts	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 implement a two-stage shutdown barrier that sleeps for an ingress-propagation window (typically 5-15s) upon receiving SIGTERM before triggering server socket closure.

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.