How does `axum::Extension` state differ from using `axum::State` for sharing application data?

axum::Extension and axum::State are both mechanisms for sharing application data with handlers, but they differ fundamentally in type safety, performance, and intended use cases. State is the primary, type-safe mechanism where the state type is encoded directly in the router and extracted via State<S> extractors—the router owns the state and handlers receive references with the exact type. Extension uses a type-erased Extensions map internally, storing values as Box<dyn Any> and requiring downcasting at runtime. State should be your default choice for application state; Extension exists primarily for middleware-added data and legacy compatibility. The key trade-off is that State provides compile-time type guarantees and direct references, while Extension offers flexibility at the cost of runtime checks and reference counting.

Basic State Usage

use axum::{
    Router,
    extract::State,
    routing::get,
    response::IntoResponse,
};
use std::sync::Arc;
 
// Define your application state
#[derive(Clone)]
struct AppState {
    db_pool: DbPool,
    config: Config,
    counter: Arc<atomic::AtomicU64>,
}
 
struct DbPool;
struct Config;
 
// Handler receives typed state via State extractor
async fn get_user(State(state): State<AppState>) -> impl IntoResponse {
    // state is AppState, typed and ready to use
    let count = state.counter.load(std::sync::atomic::Ordering::Relaxed);
    format!("Count: {}", count)
}
 
async fn health_check(State(state): State<AppState>) -> impl IntoResponse {
    // Same state type, same direct access
    "OK"
}
 
#[tokio::main]
async fn main() {
    let state = AppState {
        db_pool: DbPool,
        config: Config,
        counter: Arc::new(atomic::AtomicU64::new(0)),
    };
    
    // State is passed to the router with .with_state()
    let app = Router::new()
        .route("/user", get(get_user))
        .route("/health", get(health_check))
        .with_state(state);
    
    // Run the app
    // axum::Server::bind(...).serve(app.into_make_service()).await
}

State provides typed access to application state with compile-time guarantees.

Basic Extension Usage

use axum::{
    Router,
    Extension,
    routing::get,
    response::IntoResponse,
};
use std::sync::Arc;
 
#[derive(Clone)]
struct SharedData {
    value: Arc<String>,
}
 
// Handler receives Extension via Extension extractor
async fn get_data(Extension(data): Extension<SharedData>) -> impl IntoResponse {
    // data is SharedData, extracted from type-erased map
    data.value.clone()
}
 
async fn get_data_ref(Extension(data): Extension<Arc<SharedData>>) -> impl IntoResponse {
    // Can also use Arc directly
    data.value.clone()
}
 
#[tokio::main]
async fn main() {
    let shared = SharedData {
        value: Arc::new("Hello".to_string()),
    };
    
    // Extension is added via .layer()
    let app = Router::new()
        .route("/data", get(get_data))
        .layer(Extension(shared));
    
    // Note: Extension uses tower::ServiceBuilder internally
}

Extension wraps data in a type-erased map and requires runtime extraction.

Type Safety Differences

use axum::{
    Router,
    extract::State,
    Extension,
    routing::get,
    response::IntoResponse,
};
 
// === STATE: Compile-time type safety ===
 
#[derive(Clone)]
struct MyState {
    value: String,
}
 
async fn state_handler(State(state): State<MyState>) -> impl IntoResponse {
    // Compiler knows state is MyState
    state.value.clone()
}
 
// This would NOT compile - wrong state type:
// async fn wrong_state(State(state): State<String>) -> impl IntoResponse {
//     state
// }
 
// === EXTENSION: Runtime type checking ===
 
#[derive(Clone)]
struct MyExtension {
    value: String,
}
 
async fn extension_handler(Extension(ext): Extension<MyExtension>) -> impl IntoResponse {
    ext.value.clone()
}
 
// This WOULD compile but PANIC at runtime - wrong type:
// async fn wrong_extension(Extension(ext): Extension<String>) -> impl IntoResponse {
//     ext
// }
// Panics with: "Extension extraction failed: no extension of type String found"

State enforces types at compile time; Extension panics at runtime on type mismatch.

How Extension Works Internally

use axum::Extension;
use std::any::Any;
use std::sync::Arc;
 
// Simplified view of Extension internals
mod extension_internals {
    use std::any::{Any, TypeId};
    use std::collections::HashMap;
    use std::sync::Arc;
    
    // The actual Extensions type is a type-erased map
    pub struct Extensions {
        map: HashMap<TypeId, Box<dyn Any + Send + Sync>>,
    }
    
    impl Extensions {
        pub fn insert<T: Clone + Send + Sync + 'static>(&mut self, value: T) {
            self.map.insert(TypeId::of::<T>(), Box::new(value));
        }
        
        pub fn get<T: Clone + Send + Sync + 'static>(&self) -> Option<&T> {
            self.map
                .get(&TypeId::of::<T>())
                .and_then(|v| v.downcast_ref::<T>())
        }
    }
}
 
// Extension<T> extracts T from this map at runtime
// This requires:
// 1. TypeId lookup in HashMap
// 2. downcast_ref to convert Any to concrete type
// 3. Clone to return owned value

Extension uses type erasure with Box<dyn Any> and runtime downcasting.

How State Works Internally

use axum::extract::State;
 
// Simplified view of State mechanism
mod state_internals {
    // The router stores the state directly with its type
    // Handlers receive &S or S depending on Clone
    
    // State extractor implementation (simplified)
    pub struct State<S>(pub S);
    
    // The extractor receives the state from the request extensions
    // but the TYPE is known at compile time from the router
    // 
    // Router::with_state::<S>(state) stores S in request
    // State<S> extractor retrieves it with the known type
    // 
    // Key: The state type S is part of the Router's type:
    // Router<(), S> where S is the state type
}

State maintains full type information throughout the request pipeline.

Performance Comparison

use axum::{extract::State, Extension, response::IntoResponse};
use std::sync::Arc;
use std::time::Instant;
 
#[derive(Clone)]
struct Data {
    value: Arc<String>,
}
 
// State: Direct reference, no allocation
async fn state_handler(State(data): State<Data>) -> impl IntoResponse {
    // Single pointer dereference
    data.value.as_str()
}
 
// Extension: Type-erased lookup + downcast + clone
async fn extension_handler(Extension(data): Extension<Data>) -> impl IntoResponse {
    // 1. HashMap lookup by TypeId
    // 2. downcast_ref from Any
    // 3. Clone (required by Extension)
    data.value.as_str()
}
 
// Performance difference:
// - State: O(1), no allocation, no runtime checks
// - Extension: O(1) HashMap lookup + downcast + clone
// 
// The difference is small per-request but measurable under load:
// - State has lower latency
// - State has better cache locality
// - Extension allocates on each extraction (clone)

State is more efficient: no type erasure, no downcasting, no mandatory cloning.

Multiple State Types vs Extensions

use axum::{
    Router,
    extract::State,
    Extension,
    routing::get,
    response::IntoResponse,
};
use std::sync::Arc;
 
#[derive(Clone)]
struct Database {
    url: String,
}
 
#[derive(Clone)]
struct Cache {
    addr: String,
}
 
#[derive(Clone)]
struct Config {
    debug: bool,
}
 
// === Using State with combined struct ===
 
#[derive(Clone)]
struct AppState {
    db: Database,
    cache: Cache,
    config: Config,
}
 
async fn state_db(State(state): State<AppState>) -> impl IntoResponse {
    state.db.url.clone()
}
 
// === Using Extension for multiple types ===
 
async fn extension_db(Extension(db): Extension<Database>) -> impl IntoResponse {
    db.url.clone()
}
 
async fn extension_cache(Extension(cache): Extension<Cache>) -> impl IntoResponse {
    cache.addr.clone()
}
 
async fn extension_config(Extension(config): Extension<Config>) -> impl IntoResponse {
    format!("Debug: {}", config.debug)
}
 
#[tokio::main]
async fn main() {
    // State approach: single struct
    let state = AppState {
        db: Database { url: "postgres://...".to_string() },
        cache: Cache { addr: "localhost:6379".to_string() },
        config: Config { debug: true },
    };
    
    let state_app = Router::new()
        .route("/db", get(state_db))
        .with_state(state);
    
    // Extension approach: multiple extensions
    let ext_app = Router::new()
        .route("/db", get(extension_db))
        .route("/cache", get(extension_cache))
        .route("/config", get(extension_config))
        .layer(Extension(Database { url: "postgres://...".to_string() }))
        .layer(Extension(Cache { addr: "localhost:6379".to_string() }))
        .layer(Extension(Config { debug: true }));
}

State uses a single struct; Extension allows multiple independent types.

Middleware and Extension

use axum::{
    Router,
    Extension,
    routing::get,
    response::IntoResponse,
    middleware::{self, Next},
    http::Request,
};
use std::sync::Arc;
 
// Extension is ideal for middleware-added data
#[derive(Clone)]
struct RequestId(String);
 
async fn add_request_id<B>(
    Extension(request_id): Extension<RequestId>,
    mut request: Request<B>,
    next: Next<B>,
) -> impl IntoResponse {
    // Add request ID to request extensions for handlers
    let id = uuid::Uuid::new_v4().to_string();
    request.extensions_mut().insert(RequestId(id.clone()));
    
    next.run(request).await
}
 
async fn handler(Extension(request_id): Extension<RequestId>) -> impl IntoResponse {
    format!("Request ID: {}", request_id.0)
}
 
// This is where Extension shines: cross-cutting concerns
// added by middleware that handlers didn't anticipate

Extension is the natural choice for middleware-injected data.

Sub-routers and State

use axum::{
    Router,
    extract::State,
    routing::get,
    response::IntoResponse,
};
 
#[derive(Clone)]
struct AppState {
    value: String,
}
 
async fn root_handler(State(state): State<AppState>) -> impl IntoResponse {
    state.value.clone()
}
 
async fn api_handler(State(state): State<AppState>) -> impl IntoResponse {
    state.value.clone()
}
 
#[tokio::main]
async fn main() {
    let state = AppState {
        value: "shared".to_string(),
    };
    
    // State flows to sub-routers automatically
    let api_routes = Router::new()
        .route("/users", get(api_handler));
    
    let app = Router::new()
        .route("/", get(root_handler))
        .nest("/api", api_routes)
        .with_state(state);
    
    // Both root and api handlers receive the same AppState
}

State naturally propagates to nested routers with the same type.

Sub-routers and Extensions

use axum::{
    Router,
    Extension,
    routing::get,
    response::IntoResponse,
};
 
#[derive(Clone)]
struct SharedData {
    value: String,
}
 
async fn handler(Extension(data): Extension<SharedData>) -> impl IntoResponse {
    data.value.clone()
}
 
#[tokio::main]
async fn main() {
    let shared = SharedData {
        value: "shared".to_string(),
    };
    
    // Extensions need to be added at the right layer level
    let api_routes = Router::new()
        .route("/users", get(handler));
    
    let app = Router::new()
        .route("/", get(handler))
        .nest("/api", api_routes)
        .layer(Extension(shared));
    
    // Extension added here applies to ALL routes
    // Layer ordering matters!
}

Extension layers must be positioned carefully for proper scope.

When to Use State

use axum::{
    Router,
    extract::State,
    routing::{get, post},
    response::IntoResponse,
    Json,
};
use std::sync::Arc;
use tokio::sync::RwLock;
 
// Use State for core application state
 
#[derive(Clone)]
struct AppState {
    // Database connections
    db: DbPool,
    // Configuration
    config: Arc<Config>,
    // Shared mutable state
    cache: Arc<RwLock<Cache>>,
    // Business logic services
    user_service: UserService,
}
 
struct DbPool;
struct Config;
struct Cache;
struct UserService;
 
// Handlers receive the full application state
async fn get_user(
    State(state): State<AppState>,
) -> impl IntoResponse {
    // All application context available
    let db = &state.db;
    let config = &state.config;
    // ...
    "user data"
}
 
async fn create_user(
    State(state): State<AppState>,
    Json(payload): Json<CreateUser>,
) -> impl IntoResponse {
    // Same state, same type safety
    "created"
}
 
struct CreateUser;
 
#[tokio::main]
async fn main() {
    let state = AppState {
        db: DbPool,
        config: Arc::new(Config),
        cache: Arc::new(RwLock::new(Cache)),
        user_service: UserService,
    };
    
    let app = Router::new()
        .route("/users", get(get_user))
        .route("/users", post(create_user))
        .with_state(state);
}

Use State for primary application state that handlers depend on.

When to Use Extension

use axum::{
    Router,
    Extension,
    routing::get,
    response::IntoResponse,
    middleware::{self, Next},
    http::Request,
};
use std::sync::Arc;
 
// Use Extension for middleware-added data
 
// Request-scoped data added by middleware
#[derive(Clone)]
struct RequestContext {
    request_id: String,
    user_id: Option<String>,
    start_time: std::time::Instant,
}
 
// Legacy integration where type isn't known at router build time
#[derive(Clone)]
struct LegacyData {
    value: String,
}
 
async fn middleware_example<B>(
    Extension(mut ctx): Extension<RequestContext>,
    req: Request<B>,
    next: Next<B>,
) -> impl IntoResponse {
    // Modify context per-request
    next.run(req).await
}
 
async fn handler(
    Extension(ctx): Extension<RequestContext>,
    Extension(legacy): Extension<LegacyData>,
) -> impl IntoResponse {
    format!("Request: {}, Legacy: {}", ctx.request_id, legacy.value)
}
 
#[tokio::main]
async fn main() {
    let app = Router::new()
        .route("/handler", get(handler))
        .layer(Extension(RequestContext {
            request_id: String::new(),
            user_id: None,
            start_time: std::time::Instant::now(),
        }))
        .layer(Extension(LegacyData {
            value: "legacy".to_string(),
        }));
}

Use Extension for middleware-injected data and cross-cutting concerns.

Clone Requirements

use axum::{
    Router,
    extract::State,
    Extension,
    routing::get,
    response::IntoResponse,
};
use std::sync::Arc;
 
#[derive(Clone)]
struct MyData {
    value: Arc<String>,
}
 
// State: Can receive reference or owned
async fn state_ref(State(data): State<MyData>) -> impl IntoResponse {
    // data is MyData (cloned, but Arc clone is cheap)
    data.value.as_str()
}
 
// Can also receive Arc directly for more control
#[derive(Clone)]
struct MyData2 {
    value: Arc<String>,
}
 
async fn state_arc(State(data): State<Arc<MyData2>>) -> impl IntoResponse {
    // data is Arc<MyData2>, single reference
    data.value.as_str()
}
 
// Extension: Always requires Clone
async fn extension_handler(Extension(data): Extension<MyData>) -> impl IntoResponse {
    // Extension extraction ALWAYS clones
    // MyData must be Clone
    data.value.as_str()
}
 
// If clone is expensive, wrap in Arc
#[derive(Clone)]
struct ExpensiveData {
    big_data: Arc<Vec<u8>>,
}
 
async fn expensive_extension(
    Extension(data): Extension<Arc<ExpensiveData>>
) -> impl IntoResponse {
    // Arc clone is cheap
    format!("{} bytes", data.big_data.len())
}

Both require Clone, but State gives more control over the reference type.

Combining State and Extension

use axum::{
    Router,
    extract::State,
    Extension,
    routing::get,
    response::IntoResponse,
    middleware::{self, Next},
    http::Request,
};
use std::sync::Arc;
 
#[derive(Clone)]
struct AppState {
    db: Database,
    config: Config,
}
 
struct Database;
struct Config;
 
// Middleware adds per-request context
#[derive(Clone)]
struct RequestContext {
    request_id: String,
}
 
async fn auth_middleware<B>(
    State(state): State<AppState>,
    Extension(ctx): Extension<RequestContext>,
    req: Request<B>,
    next: Next<B>,
) -> impl IntoResponse {
    // Can use both State and Extension in middleware
    next.run(req).await
}
 
// Handler uses both State and Extension
async fn handler(
    State(state): State<AppState>,
    Extension(ctx): Extension<RequestContext>,
) -> impl IntoResponse {
    format!("Request {} using {:?}", ctx.request_id, state.db)
}
 
#[tokio::main]
async fn main() {
    let state = AppState {
        db: Database,
        config: Config,
    };
    
    let app = Router::new()
        .route("/api", get(handler))
        .layer(Extension(RequestContext {
            request_id: "default".to_string(),
        }))
        .with_state(state);
}

State and Extension can be used together for different purposes.

Migration from Extension to State

use axum::{
    Router,
    extract::State,
    Extension,
    routing::get,
    response::IntoResponse,
};
 
// BEFORE: Using Extension for everything
#[derive(Clone)]
struct Config {
    db_url: String,
}
 
async fn old_handler(Extension(config): Extension<Config>) -> impl IntoResponse {
    config.db_url.clone()
}
 
// AFTER: Migrate to State
 
#[derive(Clone)]
struct AppState {
    config: Config,
}
 
async fn new_handler(State(state): State<AppState>) -> impl IntoResponse {
    state.config.db_url.clone()
}
 
// Gradual migration: support both during transition
async fn transition_handler(
    Extension(config): Extension<Config>,
    State(state): State<AppState>,
) -> impl IntoResponse {
    // Prefer State, fall back to Extension during migration
    state.config.db_url.clone()
}
 
#[tokio::main]
async fn main() {
    let state = AppState {
        config: Config { db_url: "postgres://...".to_string() },
    };
    
    let app = Router::new()
        .route("/new", get(new_handler))
        .route("/transition", get(transition_handler))
        .layer(Extension(state.config.clone()))  // Still support Extension
        .with_state(state);
}

Gradual migration allows moving from Extension to State incrementally.

Summary Comparison

| Aspect | State | Extension | |--------|---------|-------------| | Type safety | Compile-time | Runtime (panics on mismatch) | | Performance | Direct reference | HashMap lookup + downcast + clone | | Ownership | Router owns, handlers reference | Shared via Clone | | Use case | Application state | Middleware-added data | | Multiple values | Single struct | Multiple Extensions | | Router type | Router<(), S> | Any router | | Propagation | Automatic to nested routers | Requires layer ordering | | Error handling | Compile error | Runtime panic |

Synthesis

State and Extension serve different purposes in Axum:

Use State for:

Core application state (database pools, config, services)
Data known at router build time
When type safety matters
When performance matters
When you want compile-time guarantees

Use Extension for:

Middleware-injected data (request IDs, auth info)
Cross-cutting concerns
Data added dynamically
Legacy integration
When you need multiple independent types

Key insight: State is the idiomatic choice for application state because it encodes the state type in the router's type signature, enabling compile-time verification that handlers receive the correct type. Extension exists as a more flexible mechanism suitable for middleware-added data where the handler doesn't choose what it receives. The flexibility of Extension comes at a cost: runtime type checking, mandatory cloning, and the possibility of panics. For primary application state, prefer State; reserve Extension for cross-cutting middleware concerns.

Loading page…

How does axum::Extension state differ from using axum::State for sharing application data?

Basic State Usage

Basic Extension Usage

Type Safety Differences

How Extension Works Internally

How State Works Internally

Performance Comparison

Multiple State Types vs Extensions

Middleware and Extension

Sub-routers and State

Sub-routers and Extensions

When to Use State

When to Use Extension

Clone Requirements

Combining State and Extension

Migration from Extension to State

Summary Comparison

Synthesis

How does axum::Extension state differ from using axum::State for sharing application data?

Basic State Usage

Basic Extension Usage

Type Safety Differences

How Extension Works Internally

How State Works Internally

Performance Comparison

Multiple State Types vs Extensions

Middleware and Extension

Sub-routers and State

Sub-routers and Extensions

When to Use State

When to Use Extension

Clone Requirements

Combining State and Extension

Migration from Extension to State

Summary Comparison

Synthesis

How does `axum::Extension` state differ from using `axum::State` for sharing application data?

How does `axum::Extension` state differ from using `axum::State` for sharing application data?