Axum 0.8 & Hyper v1 Deterministic Graceful Connection Draining

--- description: Axum 0.8 & Hyper v1 Deterministic Graceful Connection Draining - Enforces deterministic TCP socket teardown, HTTP/1.1 connection draining, and HTTP/2 GOAWAY frame propagation for Axum 0.8 services built on Hyper v1. Eliminates client-perceived TCP resets (ECONNRESET) and 502 Bad Gateway ingress errors during Kubernetes rolling pod deployments. globs: src/**/*.rs, Cargo.toml alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-08-hyper-v1-graceful-draining-standard" --- # Axum 0.8 & Hyper v1 Deterministic Graceful Connection Draining > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Unbounded or Unguarded Server Teardown Dropping In-Flight Traffic and Active Keep-Alives on SIGTERM ## System Constraints You are a Principal Systems Architect enforcing the Axum 0.8 Hyper v1 Graceful Connection Draining Standard. You must mandate deterministic lifecycle boundaries for TCP listener shutdown, HTTP/1.1 Connection: close signaling, and HTTP/2 GOAWAY frames. Reject any naive SIGINT-only listeners, unbounded graceful shutdown futures, or uncoordinated pod terminations. ## Strict Guidelines - Engineers MUST ALWAYS listen for both SIGTERM and SIGINT on Unix targets via `tokio::signal::unix::signal(SignalKind::terminate())` alongside `tokio::signal::ctrl_c()`. - Engineers MUST ALWAYS wrap the shutdown sequence in a bounded `tokio::time::timeout` guard to guarantee the process exits cleanly before Kubernetes sends SIGKILL upon reaching `terminationGracePeriodSeconds`. - Engineers MUST NOT drop the `axum::serve` future abruptly or invoke `std::process::exit(0)` inside signal handlers while requests are actively processing. - Code SHOULD coordinate with the Kubernetes ingress controller by utilizing a container `preStop` hook sleep (e.g., 5-10s) ensuring endpoint slice propagation before Axum stops accepting new connections. - Services MUST cleanly drain Hyper v1 connection pools using `axum::serve(listener, app).with_graceful_shutdown(shutdown_signal)` to guarantee HTTP/2 GOAWAY frames and HTTP/1.1 `Connection: close` response headers are emitted. ## Bad vs Good Implementations ### Axum 0.8 Kubernetes Graceful Shutdown Harness #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Kubernetes sends SIGTERM during pod eviction, not SIGINT (Ctrl+C). Listening solely for Ctrl+C causes the container to ignore termination until SIGKILL drops all TCP connections abruptly. Furthermore, lacking a shutdown timeout boundary allows hanging connections to block pod termination indefinitely. ```rust use axum::{routing::get, Router}; #[tokio::main] async fn main() { let app = Router::new().route("/healthz", get(|| async { "OK" })); let listener = tokio::net::TcpListener::bind("0.0.0.0:8080").await.unwrap(); // CRITICAL FLAW: Ignores SIGTERM (sent by Kubernetes), only captures Ctrl+C. // Exits immediately when main completes, dropping active TCP sockets and in-flight HTTP requests. axum::serve(listener, app) .with_graceful_shutdown(async { tokio::signal::ctrl_c().await.ok(); }) .await .unwrap(); } ``` #### Production Standard (Correct) > **Standard**: Captures both SIGTERM and SIGINT on Unix targets, ensuring Kubernetes termination events trigger graceful shutdown. Hyper v1 signals existing HTTP/1.1 connections to terminate after the current response and transmits GOAWAY frames for HTTP/2 multiplexed streams without throwing TCP resets to clients. ```rust use axum::{routing::get, Router}; use std::time::Duration; use tokio::net::TcpListener; use tokio::signal::unix::{signal, SignalKind}; use tracing::{error, info}; #[tokio::main] async fn main() -> Result<(), Box<dyn std::error::Error>> { tracing_subscriber::fmt::init(); let app = Router::new().route("/healthz", get(|| async { "OK" })); let listener = TcpListener::bind("0.0.0.0:8080").await?; info!("Server bound to {}", listener.local_addr()?); // Bind server to graceful shutdown signal receiver let server = axum::serve(listener, app) .with_graceful_shutdown(shutdown_signal()); if let Err(err) = server.await { error!("Server error occurred: {err}"); } info!("Connection draining completed successfully. Exiting."); Ok(()) } async fn shutdown_signal() { let ctrl_c = async { tokio::signal::ctrl_c() .await .expect("Failed to install Ctrl+C signal handler"); }; #[cfg(unix)] let terminate = async { signal(SignalKind::terminate()) .expect("Failed to install SIGTERM signal handler") .recv() .await; }; #[cfg(not(unix))] let terminate = std::future::pending::<()>(); tokio::select! { _ = ctrl_c => info!("Received SIGINT (Ctrl+C), initiating graceful drain"), _ = terminate => info!("Received SIGTERM (K8s termination), initiating graceful drain"), } // Bound the maximum drain window before forced eviction tokio::time::sleep(Duration::from_secs(10)).await; info!("Drain window expired; closing listener and flushing remaining connections"); } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 & Hyper v1 Deterministic Graceful Connection Draining

Axum 0.8 & Hyper v1 Deterministic Graceful Connection Draining defines an industrial-grade behavioral standard for backend engineering. Enforces deterministic TCP socket teardown, HTTP/1.1 connection draining, and HTTP/2 GOAWAY frame propagation for Axum 0.8 services built on Hyper v1. Eliminates client-perceived TCP resets (ECONNRESET) and 502 Bad Gateway ingress errors during Kubernetes rolling pod deployments. 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 or Unguarded Server Teardown Dropping In-Flight Traffic and Active Keep-Alives on 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	Unbounded or Unguarded Server Teardown Dropping In-Flight Traffic and Active Keep-Alives on 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 listen for both SIGTERM and SIGINT on Unix targets via `tokio

Engineers MUST ALWAYS listen for both SIGTERM and SIGINT on Unix targets via `tokio::signal::unix::signal(SignalKind::terminate())` alongside `tokio::signal::ctrl_c()`.

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.