Axum 0.8 Type-Safe State Subtyping & Tower Panic-Resilient Middleware Composition

--- description: Axum 0.8 Type-Safe State Subtyping & Tower Panic-Resilient Middleware Composition - Enforces Axum 0.8 compile-time type-safe state sharing using FromRef sub-states instead of dynamic Extensions, alongside resilient Tower middleware stacks. Mandates CatchPanicLayer boundary encapsulation, deterministic middleware execution ordering, and total elimination of unhandled extractor panics through explicit IntoResponse rejection handling. 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-resilience-guardrail" --- # Axum 0.8 Type-Safe State Subtyping & Tower Panic-Resilient Middleware Composition > **Severity**: CRITICAL | **Category**: backend > **Anti-Pattern Warning**: Relying on dynamic Extension extraction for shared state and omitting CatchPanicLayer or FromRef sub-state delegation in Axum routers ## System Constraints You are a Principal Rust Systems Architect enforcing Axum 0.8 and Tower service standards. Mandate compile-time type safety via axum::extract::State and FromRef, strict middleware evaluation ordering via tower::ServiceBuilder, and deterministic panic isolation across all HTTP boundaries. ## Strict Guidelines - Engineers MUST ALWAYS use `axum::extract::State` paired with `axum::extract::FromRef` implementations for modular sub-state extraction instead of `axum::Extension` to ensure compile-time dependency verification. - Engineers MUST wrap all public Axum routers with `tower_http::catch_panic::CatchPanicLayer` before converting to an incoming listener service to prevent thread panics from dropping TCP connections silently. - Engineers MUST compose Tower middleware layers via `tower::ServiceBuilder` where outer layers execute first on incoming requests: `TraceLayer` -> `CatchPanicLayer` -> `TimeoutLayer` -> `ConcurrencyLimitLayer`. - Custom extractors MUST ALWAYS implement `FromRequest` or `FromRequestParts` with a concrete `Rejection` type that implements `IntoResponse`; panicking or unhandled `.unwrap()` calls inside extractors are strictly forbidden. - Sub-routers MUST NOT define independent monolithic states; they MUST extract modular sub-states using the outer router's state via `FromRef` to maintain clean separation of concerns and testability. ## Bad vs Good Implementations ### Dynamic Extension Extraction and Fragile Tower Layering (Anti-Pattern) #### Bad Antipattern (AI Common Hallucination) > **Why it fails**: Using Extension defers state dependency checking to runtime, yielding a 500 error if omitted. Raw unwrapping without CatchPanicLayer causes abrupt TCP connection drops and bypasses structured telemetry. ```rust use axum::{routing::get, Extension, Router, Json}; use std::sync::Arc; use tower_http::trace::TraceLayer; struct AppState { db_pool: String, } // ANTI-PATTERN: Fails at runtime if Extension is missing from Router. // No panic layer, no FromRef sub-state, and unwrapping inside handler causes connection drops. async fn get_user(Extension(state): Extension<Arc<AppState>>) -> Json<String> { let val = state.db_pool.parse::<i32>().unwrap(); // Unhandled panic resets connection Json(format!("User: {}", val)) } pub fn build_router(state: Arc<AppState>) -> Router { Router::new() .route("/user", get(get_user)) .layer(TraceLayer::new_for_http()) .layer(Extension(state)) // Dynamic runtime injection without compile-time guarantees } ``` #### Production Standard (Correct) > **Standard**: Leverages Axum 0.8 `State` combined with `FromRef` for sub-states, ensuring compile-time safety. Employs `CatchPanicLayer` and explicit `IntoResponse` error typing to eliminate dropped connections and unhandled runtime panics. ```rust use axum::{ extract::{FromRef, State}, http::StatusCode, response::{IntoResponse, Response}, routing::get, Json, Router, }; use std::sync::Arc; use tower::ServiceBuilder; use tower_http::{ catch_panic::CatchPanicLayer, trace::TraceLayer, }; #[derive(Clone)] pub struct DatabaseConfig { pub pool_id: Arc<str>, } #[derive(Clone)] pub struct AppState { pub db: DatabaseConfig, } // Invariant: Implement FromRef for modular sub-state extraction impl FromRef<AppState> for DatabaseConfig { fn from_ref(app_state: &AppState) -> Self { app_state.db.clone() } } #[derive(Debug)] pub enum AppError { InvalidFormat, } impl IntoResponse for AppError { fn into_response(self) -> Response { let (status, msg) = match self { AppError::InvalidFormat => (StatusCode::BAD_REQUEST, "Invalid state format"), }; (status, Json(serde_json::json!({ "error": msg }))).into_response() } } // Type-safe handler extracting only the sub-state it requires async fn get_user(State(db): State<DatabaseConfig>) -> Result<Json<serde_json::Value>, AppError> { let _parsed = db.pool_id.parse::<i32>().map_err(|_| AppError::InvalidFormat)?; Ok(Json(serde_json::json!({ "status": "connected" }))) } pub fn build_router(state: AppState) -> Router { // Invariant: CatchPanicLayer ensures panics are caught and serialized into 500 responses let middleware = ServiceBuilder::new() .layer(TraceLayer::new_for_http()) .layer(CatchPanicLayer::new()); Router::new() .route("/user", get(get_user)) .with_state(state) .layer(middleware) } ```

Architectural Specification & Invariant Rationale

Architectural Invariant Design: Axum 0.8 Type-Safe State Subtyping & Tower Panic-Resilient Middleware Composition

Axum 0.8 Type-Safe State Subtyping & Tower Panic-Resilient Middleware Composition defines an industrial-grade behavioral standard for backend engineering. Enforces Axum 0.8 compile-time type-safe state sharing using FromRef sub-states instead of dynamic Extensions, alongside resilient Tower middleware stacks. Mandates CatchPanicLayer boundary encapsulation, deterministic middleware execution ordering, and total elimination of unhandled extractor panics through explicit IntoResponse rejection handling. 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: Relying on dynamic Extension extraction for shared state and omitting CatchPanicLayer or FromRef sub-state delegation in Axum routers 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	Relying on dynamic Extension extraction for shared state and omitting CatchPanicLayer or FromRef sub-state delegation in Axum routers	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` paired with `axum::extract::FromRef` implementations for modular sub-state extraction instead of `axum::Extension` to ensure compile-time dependency verification.

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.