Axum 0.8 / Hyper 1.x HTTP/2 Graceful GOAWAY Stream Drain Invariant

--- description: Axum 0.8 / Hyper 1.x HTTP/2 Graceful GOAWAY Stream Drain Invariant - Enforces RFC 9113-compliant HTTP/2 graceful connection draining during rolling deployments in Axum 0.8 and Hyper 1.x. Prevents connection resets, ERR_HTTP2_PROTOCOL_ERROR, and 502 Bad Gateway errors by ensuring active multiplexed streams finish processing and GOAWAY frames propagate prior to socket closure. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/axum-hyper-h2-goaway-drain-invariant" --- # Axum 0.8 / Hyper 1.x HTTP/2 Graceful GOAWAY Stream Drain Invariant > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Abrupt TCP Socket Termination Dropping Inflight Multiplexed HTTP/2 Streams During Pod Termination ## System Constraints You are a Principal Systems and Backend Architect enforcing zero-downtime HTTP/2 graceful shutdown invariants in Axum 0.8 and Hyper 1.x. You must mandate correct propagation of GOAWAY frame sequences and stream draining before terminating process runtimes. ## Strict Guidelines - Engineers MUST ALWAYS invoke `Pin::new(&mut conn).graceful_shutdown()` when managing raw Hyper 1.x HTTP/2 connections rather than dropping connection handles upon receiving termination signals. - Engineers MUST NOT abruptly exit the Tokio runtime upon SIGTERM; the accept loop MUST stop accepting new TCP connections while existing connection tasks drain with a bounded timeout. - Services using `axum::serve` MUST pair `.with_graceful_shutdown(...)` with ingress preStop sleep hooks (minimum 5-15s) to allow upstream load balancers (Envoy, ALB) to deregister backend endpoints before the initial GOAWAY frame is emitted. - Code driving manual Hyper 1.x loops MUST use `tokio_util::task::TaskTracker` or `tokio::sync::watch` to broadcast termination signals to active HTTP/2 connection drivers. - HTTP/2 server configurations SHOULD set `builder.http2().keep_alive_interval(Some(Duration::from_secs(30)))` and provide explicit drain timeouts to avoid orphaned connection deadlocks from unresponsive clients. - Components NEVER drop Tokio `JoinSet` or background stream tasks during graceful shutdown until pending responses flush or the hard deadline elapses. ## Bad vs Good Implementations ### Hyper 1.x / Axum Connection Serving with HTTP/2 GOAWAY Drain #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Terminating the server future via tokio::select! instantly drops the server and listener. Active multiplexed HTTP/2 streams are severed without transmitting a GOAWAY frame, leading to dropped in-flight requests and 502 errors on downstream proxies. ```rust use axum::{routing::get, Router}; use tokio::net::TcpListener; #[tokio::main] async fn main() { let app = Router::new().route("/", get(|| async { "ok" })); let listener = TcpListener::bind("0.0.0.0:8080").await.unwrap(); // ANTI-PATTERN: select! drops the accept loop and listener immediately. // Inflight HTTP/2 multiplexed streams receive RST_STREAM or sudden TCP FIN, // causing 502 Bad Gateway / ERR_HTTP2_PROTOCOL_ERROR on ingress controllers. tokio::select! { _ = axum::serve(listener, app).into_future() => {}, _ = tokio::signal::ctrl_c() => { println!("Shutting down immediately!"); } } } ``` #### Production Standard (Correct) > **Standard**: Passing the shutdown future to .with_graceful_shutdown() enables Hyper's native HTTP/2 connection drainer. It stops accepting new TCP connections, transmits an initial GOAWAY frame, and allows existing multiplexed streams to complete cleanly before closing sockets. ```rust use axum::{routing::get, Router}; use std::time::Duration; use tokio::net::TcpListener; use tokio::signal; #[tokio::main] async fn main() { let app = Router::new().route("/", get(|| async { "ok" })); let listener = TcpListener::bind("0.0.0.0:8080").await.unwrap(); // PRODUCTION INVARIANT: Use axum::serve with explicit graceful shutdown signal. // In Axum 0.8 / Hyper 1.x, with_graceful_shutdown coordinates closing the listener, // emitting HTTP/2 GOAWAY frames with the maximum stream ID, and waiting for inflight streams. let server = axum::serve(listener, app) .with_graceful_shutdown(shutdown_signal()); if let Err(err) = server.await { eprintln!("Server error during graceful termination: {err}"); } } async fn shutdown_signal() { let ctrl_c = async { signal::ctrl_c().await.expect("Failed to install Ctrl+C handler"); }; #[cfg(unix)] let terminate = async { signal::unix::signal(signal::unix::SignalKind::terminate()) .expect("Failed to install SIGTERM handler") .recv() .await; }; #[cfg(not(unix))] let terminate = std::future::pending::<()>(); tokio::select! { _ = ctrl_c => {}, _ = terminate => {}, } // Ingress draining window: Give Kubernetes endpoint controllers time to deregister pod IP tokio::time::sleep(Duration::from_secs(5)).await; } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 / Hyper 1.x HTTP/2 Graceful GOAWAY Stream Drain Invariant

Axum 0.8 / Hyper 1.x HTTP/2 Graceful GOAWAY Stream Drain Invariant defines an industrial-grade behavioral standard for backend engineering. Enforces RFC 9113-compliant HTTP/2 graceful connection draining during rolling deployments in Axum 0.8 and Hyper 1.x. Prevents connection resets, ERR_HTTP2_PROTOCOL_ERROR, and 502 Bad Gateway errors by ensuring active multiplexed streams finish processing and GOAWAY frames propagate prior to socket closure. 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: Abrupt TCP Socket Termination Dropping Inflight Multiplexed HTTP/2 Streams During Pod Termination 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	Abrupt TCP Socket Termination Dropping Inflight Multiplexed HTTP/2 Streams During Pod Termination	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 invoke `Pin

Engineers MUST ALWAYS invoke `Pin::new(&mut conn).graceful_shutdown()` when managing raw Hyper 1.x HTTP/2 connections rather than dropping connection handles upon receiving termination signals.

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.