Rust Axum 0.8 Compile-Time State Extraction and Tower Middleware Invariants

--- description: Rust Axum 0.8 Compile-Time State Extraction and Tower Middleware Invariants - Mandate compile-time type-safe state injection using Axum 0.8 State and FromRef traits instead of runtime Extension extractors. Enforce deterministic Tower middleware ordering via ServiceBuilder with CatchPanicLayer and customized rejection types to eliminate unhandled connection drops. globs: src/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rust-axum-state-tower-panic-resilience" --- # Rust Axum 0.8 Compile-Time State Extraction and Tower Middleware Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Runtime Panics from Untyped Extension Extractors, Unhandled Panics Crashing HTTP Connections, and Broken Middleware Stacks ## System Constraints You are a Principal Rust Architect enforcing Axum 0.8 and Tower invariants. Enforce compile-time State<S> guarantees with FromRef sub-states, deterministic Tower ServiceBuilder ordering, and zero-panic runtime resilience via CatchPanicLayer and custom rejection handlers. ## Strict Guidelines - Engineers MUST ALWAYS use `axum::extract::State` and implement `axum::extract::FromRef` for sub-states instead of using `axum::Extension` for core application dependencies. - Engineers MUST ALWAYS position body-consuming extractors (e.g., `axum::Json`, `axum::extract::RawBody`) as the final parameter in handler signatures to prevent premature stream consumption. - Code MUST wrap root routers with `tower_http::catch_panic::CatchPanicLayer` configured with a custom panic response generator to prevent abrupt TCP connection resets. - Services MUST compose middleware via `tower::ServiceBuilder` to enforce top-down, deterministic execution order (Outer layers: tracing -> timeout -> catch_panic -> authentication -> inner handler). - Components NEVER panic inside Axum extractors or Tower services; all extractor failures MUST map to explicitly typed `IntoResponse` rejection types. ## Bad vs Good Implementations ### Axum 0.8 State Extraction and Panic-Resilient Tower Stack #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using Extension defer resolution to runtime, which causes an unrecoverable 500 or panic if the extension is omitted. Placing Json before other extractors breaks extraction ordering. An unhandled panic drops the raw TCP connection rather than returning a structured 500 response. ```rust use axum::{routing::post, Extension, Json, Router}; use serde::Deserialize; use std::sync::Arc; #[derive(Clone)] struct AppState { db: Arc<String> } #[derive(Deserialize)] struct Payload { name: String } // ANTI-PATTERN: Body-consuming extractor is first; Extension fails at runtime if unregistered. async fn bad_handler( Json(payload): Json<Payload>, Extension(state): Extension<AppState>, ) -> String { // ANTI-PATTERN: Direct panic will drop connection without HTTP 500 response if payload.name.is_empty() { panic!("empty name"); } format!("Hello {}, db: {}", payload.name, state.db) } pub fn app() -> Router { // ANTI-PATTERN: Router lacks CatchPanicLayer and type-safe state registration Router::new().route("/user", post(bad_handler)) } ``` #### Production Standard (Correct) > **Standard**: Extracts state using compile-time checked State with FromRef, guarantees correct body parsing by placing Json last, maps business errors into explicit HTTP response codes, and wraps the router in CatchPanicLayer to safeguard connections. ```rust use axum::{ extract::{FromRef, State}, http::StatusCode, response::{IntoResponse, Response}, routing::post, Json, Router, }; use serde::Deserialize; use std::sync::Arc; use tower::ServiceBuilder; use tower_http::catch_panic::CatchPanicLayer; #[derive(Clone)] pub struct AppState { pub db: Arc<String>, } #[derive(Clone)] pub struct DbPool(pub Arc<String>); impl FromRef<AppState> for DbPool { fn from_ref(state: &AppState) -> Self { DbPool(state.db.clone()) } } #[derive(Deserialize)] pub struct Payload { pub name: String } fn handle_panic(_err: Box<dyn std::any::Any + Send + 'static>) -> Response { (StatusCode::INTERNAL_SERVER_ERROR, "Internal Server Error").into_response() } // PRODUCTION FIX: Compile-time State extractor, body extractor placed last async fn good_handler( State(DbPool(db)): State<DbPool>, Json(payload): Json<Payload>, ) -> Result<String, (StatusCode, &'static str)> { if payload.name.is_empty() { return Err((StatusCode::BAD_REQUEST, "Name cannot be empty")); } Ok(format!("Hello {}, db: {}", payload.name, db)) } pub fn app(state: AppState) -> Router { let middleware = ServiceBuilder::new() .layer(CatchPanicLayer::custom(handle_panic)); Router::new() .route("/user", post(good_handler)) .layer(middleware) .with_state(state) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Rust Axum 0.8 Compile-Time State Extraction and Tower Middleware Invariants

Rust Axum 0.8 Compile-Time State Extraction and Tower Middleware Invariants defines an industrial-grade behavioral standard for backend engineering. Mandate compile-time type-safe state injection using Axum 0.8 State and FromRef traits instead of runtime Extension extractors. Enforce deterministic Tower middleware ordering via ServiceBuilder with CatchPanicLayer and customized rejection types to eliminate unhandled connection drops. 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: Runtime Panics from Untyped Extension Extractors, Unhandled Panics Crashing HTTP Connections, and Broken Middleware Stacks 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	Runtime Panics from Untyped Extension Extractors, Unhandled Panics Crashing HTTP Connections, and Broken Middleware Stacks	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 use `axum

Engineers MUST ALWAYS use `axum::extract::State` and implement `axum::extract::FromRef` for sub-states instead of using `axum::Extension` for core application dependencies.

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.