Axum 0.8 Type-Safe State Extractors and Tower Middleware Invariants

--- description: Axum 0.8 Type-Safe State Extractors and Tower Middleware Invariants - Enforces compile-time verified state injection via Axum 0.8 State and FromRef patterns while prohibiting untyped Extension usage. Mandates structured Tower ServiceBuilder middleware composition with panic boundaries to eliminate unhandled panics and runtime injection failures. globs: src/**/*.rs, crates/**/*.rs alwaysApply: true verified_by: "agentrules.org" license: "CC-BY-4.0" source: "https://agentrules.org/rules/rust-axum-state-tower-service-invariants" --- # Axum 0.8 Type-Safe State Extractors and Tower Middleware Invariants > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Runtime Panics via Untyped Extensions and Missing Tower CatchPanic Layer ## System Constraints You are a Principal Rust Architect enforcing strict Axum 0.8 and Tower Service safety standards. Mandate compile-time verified State extraction using FromRef, deterministic middleware ordering via ServiceBuilder, and comprehensive panic boundary enforcement. ## Strict Guidelines - Engineers MUST ALWAYS use `axum::extract::State` with `axum::extract::FromRef` for hierarchical state decomposition instead of untyped `axum::Extension`. - Engineers MUST NOT use `.unwrap()` or `.expect()` inside Axum handler functions or custom extractors; all failures must be converted into types implementing `axum::response::IntoResponse`. - Routers MUST ALWAYS mount `tower_http::catch_panic::CatchPanicLayer` with a custom panic handler returning structured JSON errors to ensure zero unhandled panics. - Middleware stacks MUST be composed using `tower::ServiceBuilder` ensuring outward-facing layers (tracing, panic catching, timeout) enclose inward-facing layers (state, authentication, route handlers). - Sub-routers MUST be modularized by constraining sub-states through `FromRef<ParentState>` to maintain compile-time type verification during router composition. ## Bad vs Good Implementations ### Axum 0.8 State and Tower Middleware Composition #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using Extension bypasses Axum's compile-time dependency verification, causing the application to panic at runtime if an extension was omitted. Furthermore, the lack of a CatchPanicLayer and raw unwrap calls will terminate worker threads or abort connections unexpectedly. ```rust use axum::{routing::get, Extension, Router}; use std::sync::Arc; struct DatabasePool; // ANTI-PATTERN: Extension causes runtime panics if missing; // missing CatchPanicLayer; unhandled unwrap in handler. async fn get_user(Extension(pool): Extension<Arc<DatabasePool>>) -> String { let _conn = pool.get_connection().unwrap(); // Runtime panic risk "User details".to_string() } pub fn app() -> Router { Router::new() .route("/user", get(get_user)) // Pool omitted by mistake: compiles cleanly, crashes at runtime! } ``` #### Production Standard (Correct) > **Standard**: Type-safe State extraction via FromRef ensures state availability is validated at compile time. CatchPanicLayer converts any unexpected panics into predictable JSON 500 responses, and AppError guarantees proper IntoResponse mapping without panicking. ```rust use axum::{ extract::{FromRef, State}, http::StatusCode, response::{IntoResponse, Response}, routing::get, Json, Router, }; use serde_json::json; use std::sync::Arc; use tower::ServiceBuilder; use tower_http::catch_panic::CatchPanicLayer; use tower_http::trace::TraceLayer; #[derive(Clone)] pub struct AppState { pub db_pool: Arc<DatabasePool>, } #[derive(Clone)] pub struct DatabasePool; impl DatabasePool { fn get_connection(&self) -> Result<(), AppError> { Ok(()) } } impl FromRef<AppState> for Arc<DatabasePool> { fn from_ref(app_state: &AppState) -> Self { Arc::clone(&app_state.db_pool) } } #[derive(Debug)] pub enum AppError { DatabaseError, } impl IntoResponse for AppError { fn into_response(self) -> Response { let (status, msg) = match self { AppError::DatabaseError => (StatusCode::INTERNAL_SERVER_ERROR, "Database error"), }; (status, Json(json!({ "error": msg }))).into_response() } } async fn get_user( State(pool): State<Arc<DatabasePool>>, ) -> Result<Json<serde_json::Value>, AppError> { pool.get_connection()?; Ok(Json(json!({ "status": "success" }))) } pub fn app(state: AppState) -> Router { let middleware = ServiceBuilder::new() .layer(CatchPanicLayer::custom(|_panic_err| { Response::builder() .status(StatusCode::INTERNAL_SERVER_ERROR) .header("content-type", "application/json") .body(axum::body::Body::from(r#"{"error":"internal_panic"}"#)) .unwrap() })) .layer(TraceLayer::new_for_http()); Router::new() .route("/user", get(get_user)) .layer(middleware) .with_state(state) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Type-Safe State Extractors and Tower Middleware Invariants

Axum 0.8 Type-Safe State Extractors and Tower Middleware Invariants defines an industrial-grade behavioral standard for backend engineering. Enforces compile-time verified state injection via Axum 0.8 State and FromRef patterns while prohibiting untyped Extension usage. Mandates structured Tower ServiceBuilder middleware composition with panic boundaries to eliminate unhandled panics and runtime injection failures. 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 via Untyped Extensions and Missing Tower CatchPanic Layer 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 via Untyped Extensions and Missing Tower CatchPanic Layer	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` with `axum::extract::FromRef` for hierarchical state decomposition instead of untyped `axum::Extension`.

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.