Axum Web Framework

A comprehensive skill for building production-ready web applications and APIs using Axum, the ergonomic and modular Rust web framework built on Tokio and Tower. Master routing, extractors, middleware, state management, error handling, and deployment patterns.

When to Use This Skill

Use this skill when:

Building REST APIs with Rust and async/await Creating high-performance web services with type safety Developing microservices with Tokio ecosystem integration Implementing WebSocket servers or Server-Sent Events (SSE) Building GraphQL APIs with Rust backend Creating middleware-heavy applications requiring Tower integration Developing production-ready web applications requiring robust error handling Building systems requiring fine-grained control over HTTP request/response handling Implementing authentication, authorization, and security middleware Creating real-time web applications with async Rust Developing APIs requiring request validation and transformation Building web services with complex routing and nested routers Implementing rate limiting, timeout, and backpressure handling Creating web applications requiring custom extractors and response types Core Concepts Axum Architecture Philosophy

Axum is built on three fundamental pillars:

Tower Services: Everything in Axum is built on Tower's Service trait, providing composability and middleware integration Type-Safe Extractors: Request data extraction is compile-time checked, eliminating runtime parsing errors Minimal Boilerplate: Ergonomic APIs that reduce ceremony while maintaining explicitness The Router

The Router is the central building block in Axum. It maps HTTP requests to handlers based on path and method.

Key Properties:

Routes are matched in the order they're defined Routers can be nested for modular organization Middleware can be applied at router, route, or method level Generic over state type for flexible state management Implements Tower's Service trait for composability

Router Creation:

use axum::{Router, routing::get};

let app = Router::new() .route("/", get(handler)) .route("/users/:id", get(get_user)) .route("/posts", get(list_posts).post(create_post));

Handlers

Handlers are async functions that process requests and return responses. Axum supports multiple handler signatures through its powerful type system.

Handler Requirements:

Must be async functions Can extract data from requests using extractors Must return types implementing IntoResponse Can have up to 16 parameters (all must be extractors)

Common Handler Patterns:

// Simple handler async fn handler() -> &'static str { "Hello, World!" }

// Handler with path parameter async fn get_user(Path(user_id): Path) -> String { format!("User ID: {}", user_id) }

// Handler with multiple extractors async fn create_user( State(state): State, Json(payload): Json, ) -> Result, StatusCode> { // Implementation }

Extractors

Extractors are types that implement FromRequest or FromRequestParts, allowing type-safe extraction of data from requests.

Built-in Extractors:

Path - Extract path parameters Query - Extract query string parameters Json - Parse JSON request body Form - Parse form-encoded request body State - Access shared application state Extension - Access request extensions Headers - Access request headers Method - Get HTTP method Uri - Get request URI Request - Get full request Bytes - Raw request body as bytes String - Request body as UTF-8 string Multipart - Handle multipart/form-data

Extractor Ordering:

Extractors that consume the request body must come last Multiple body extractors in one handler will cause compilation errors State and other non-body extractors can be in any order Responses

Any type implementing IntoResponse can be returned from handlers. Axum provides many built-in implementations.

Built-in Response Types:

String, &'static str - Text responses Json - JSON responses Html - HTML responses StatusCode - Status-only responses (StatusCode, T) - Status with body (Parts, T) - Custom headers with body Response - Full control over response Result - Error handling (where E: IntoResponse) State Management

Axum uses the State extractor to share data across handlers. State must implement Clone and is typically wrapped in Arc for shared ownership.

State Patterns:

Simple State:

[derive(Clone)]

struct AppState { api_key: String, }

let app = Router::new() .route("/", get(handler)) .with_state(AppState { api_key: "secret".to_string(), });

Shared State with Arc:

[derive(Clone)]

struct AppState { db_pool: Arc, cache: Arc>, }

Multiple State Types: // Define separate state types for different router sections let api_router: Router = Router::new() .route("/api/data", get(api_handler));

let app_router: Router = Router::new() .route("/app", get(app_handler));

// Combine with final state let app = Router::new() .nest("/", app_router.with_state(app_state)) .nest("/", api_router.with_state(api_state));

Middleware

Middleware in Axum comes from Tower and provides request/response transformation, logging, authentication, and more.

Middleware Categories:

Tower Middleware - From tower and tower-http crates Custom Middleware - Using middleware::from_fn Service Middleware - Implementing Tower's Service trait Layer Pattern - Using Tower's Layer for composability

Middleware Application Order:

Applied with .layer() executes bottom-to-top (wrapping previous layers) Applied with ServiceBuilder executes top-to-bottom (more intuitive) Middleware on Router::layer runs after routing Middleware around Router (using Layer::layer) runs before routing Error Handling

Axum's error handling is built on the IntoResponse trait, allowing custom error types to be converted to HTTP responses.

Error Handling Strategies:

Result Types: async fn handler() -> Result, StatusCode> { // Returns 200 OK or error status code }

Custom Error Types: enum AppError { Database(sqlx::Error), NotFound, Unauthorized, }

impl IntoResponse for AppError { fn into_response(self) -> Response { // Convert to HTTP response } }

HandleErrorLayer: use axum::error_handling::HandleErrorLayer;

let app = Router::new() .layer( ServiceBuilder::new() .layer(HandleErrorLayer::new(handle_error)) .layer(TimeoutLayer::new(Duration::from_secs(30))) );

Tower Integration

Axum is built on Tower, enabling powerful middleware composition and service abstraction.

Key Tower Concepts:

Service Trait - Asynchronous request processing Layer Trait - Middleware factory pattern ServiceBuilder - Ergonomic middleware composition Timeout - Request timeout handling RateLimit - Request rate limiting LoadShed - Backpressure management Buffer - Request buffering Routing Basic Routing

Routes map HTTP methods and paths to handlers:

use axum::{ Router, routing::{get, post, put, delete, patch}, };

let app = Router::new() .route("/", get(root)) .route("/users", get(list_users).post(create_user)) .route("/users/:id", get(get_user).put(update_user).delete(delete_user)) .route("/posts/:id/comments", get(get_comments).post(add_comment));

Path Parameters

Extract dynamic segments from paths:

use axum::extract::Path; use serde::Deserialize;

// Single parameter async fn get_user(Path(user_id): Path) -> String { format!("User {}", user_id) }

// Multiple parameters

[derive(Deserialize)]

struct PostPath { user_id: u32, post_id: u32, }

async fn get_post(Path(params): Path) -> String { format!("User {} Post {}", params.user_id, params.post_id) }

// Using tuple for multiple params async fn get_comment( Path((post_id, comment_id)): Path<(u32, u32)> ) -> String { format!("Post {} Comment {}", post_id, comment_id) }

Wildcard Routes

Capture remaining path segments:

// Captures all remaining path async fn handler(Path(path): Path) -> String { format!("Captured path: {}", path) }

let app = Router::new() .route("/{*key}", get(handler));

// GET /foo/bar/baz -> path = "foo/bar/baz"

Important: Nested routers strip matched prefixes, but wildcard routes retain the full URI.

Nested Routers

Organize routes into modules using router nesting:

use axum::{Router, routing::get};

fn api_routes() -> Router { Router::new() .route("/users", get(list_users)) .route("/users/:id", get(get_user)) .route("/posts", get(list_posts)) }

fn admin_routes() -> Router { Router::new() .route("/dashboard", get(dashboard)) .route("/settings", get(settings)) }

let app = Router::new() .nest("/api", api_routes()) .nest("/admin", admin_routes()) .route("/", get(root));

Nesting Behavior:

Matched prefix is stripped from URI before passing to nested router Handlers in nested routers only see path relative to nest point Fallback handlers are inherited from parent if not defined in child Middleware can be applied before or after nesting Fallback Handlers

Handle unmatched routes:

use axum::{http::StatusCode, handler::Handler};

async fn fallback() -> (StatusCode, &'static str) { (StatusCode::NOT_FOUND, "Not Found") }

let app = Router::new() .route("/", get(handler)) .fallback(fallback);

Fallback Inheritance:

async fn api_fallback() -> (StatusCode, &'static str) { (StatusCode::NOT_FOUND, "API endpoint not found") }

let api = Router::new() .route("/users", get(list_users)) .fallback(api_fallback);

let app = Router::new() .nest("/api", api) .fallback(fallback); // Used for non-/api routes

Method Routing

Handle multiple HTTP methods on the same route:

use axum::routing::{get, post, MethodRouter};

// Multiple methods on one route let app = Router::new() .route("/users", get(list_users).post(create_user));

// Different handlers per method let app = Router::new() .route("/resource", get(get_resource) .post(create_resource) .put(update_resource) .delete(delete_resource) .patch(patch_resource) );

Extractors Deep Dive Path Extractor

Extract typed path parameters:

use axum::extract::Path; use serde::Deserialize;

// Simple extraction async fn user_by_id(Path(id): Path) -> String { format!("User {}", id) }

// Complex extraction

[derive(Deserialize)]

struct Params { org: String, repo: String, issue: u32, }

async fn github_issue(Path(params): Path) -> String { format!("{}/{} issue #{}", params.org, params.repo, params.issue) }

let app = Router::new() .route("/users/:id", get(user_by_id)) .route("/repos/:org/:repo/issues/:issue", get(github_issue));

Query Extractor

Extract query string parameters:

use axum::extract::Query; use serde::Deserialize;

[derive(Deserialize)]

struct Pagination { page: Option, per_page: Option, }

async fn list_users(Query(pagination): Query) -> String { let page = pagination.page.unwrap_or(1); let per_page = pagination.per_page.unwrap_or(20); format!("Page {} with {} items", page, per_page) }

// GET /users?page=2&per_page=50

Json Extractor

Parse JSON request bodies:

use axum::extract::Json; use serde::{Deserialize, Serialize};

[derive(Deserialize)]

struct CreateUser { username: String, email: String, }

[derive(Serialize)]

struct User { id: u32, username: String, email: String, }

async fn create_user(Json(payload): Json) -> Json { let user = User { id: 123, username: payload.username, email: payload.email, }; Json(user) }

JSON Error Handling:

use axum::extract::rejection::JsonRejection; use axum::http::StatusCode;

async fn create_user( payload: Result, JsonRejection> ) -> Result, (StatusCode, String)> { match payload { Ok(Json(create_user)) => { // Valid JSON Ok(Json(User { / ... / })) } Err(JsonRejection::MissingJsonContentType()) => { Err(( StatusCode::BAD_REQUEST, "Missing Content-Type: application/json".to_string(), )) } Err(JsonRejection::JsonDataError(err)) => { Err(( StatusCode::BAD_REQUEST, format!("Invalid JSON: {}", err), )) } Err(JsonRejection::JsonSyntaxError(err)) => { Err(( StatusCode::BAD_REQUEST, format!("JSON syntax error: {}", err), )) } Err() => { Err(( StatusCode::INTERNAL_SERVER_ERROR, "Unknown error".to_string(), )) } } }

State Extractor

Access shared application state:

use axum::extract::State; use std::sync::Arc;

[derive(Clone)]

struct AppState { db_pool: Arc, api_key: String, }

async fn handler(State(state): State) -> String { format!("API Key: {}", state.api_key) }

let state = AppState { db_pool: Arc::new(DatabasePool::new()), api_key: "secret".to_string(), };

let app = Router::new() .route("/", get(handler)) .with_state(state);

Extension Extractor

Access request extensions (useful for middleware):

use axum::extract::Extension;

[derive(Clone)]

struct CurrentUser { id: u32, username: String, }

async fn handler(Extension(user): Extension) -> String { format!("Hello, {}", user.username) }

// Set by middleware: async fn auth_middleware( mut req: Request, next: Next, ) -> Result { let user = CurrentUser { id: 1, username: "alice".to_string(), }; req.extensions_mut().insert(user); Ok(next.run(req).await) }

Form Extractor

Parse form-encoded request bodies:

use axum::extract::Form; use serde::Deserialize;

[derive(Deserialize)]

struct LoginForm { username: String, password: String, }

async fn login(Form(form): Form) -> String { format!("Logging in user: {}", form.username) }

Headers Extractor

Access request headers:

use axum::http::HeaderMap;

async fn handler(headers: HeaderMap) -> String { let user_agent = headers .get("user-agent") .and_then(|v| v.to_str().ok()) .unwrap_or("unknown"); format!("User-Agent: {}", user_agent) }

Custom Extractors

Create custom extractors by implementing FromRequest or FromRequestParts:

use axum::{ extract::{FromRequest, Request}, response::{IntoResponse, Response}, http::StatusCode, async_trait, };

struct AuthenticatedUser { id: u32, username: String, }

[async_trait]

impl FromRequestParts for AuthenticatedUser where S: Send + Sync, { type Rejection = Response;

async fn from_request_parts(
    parts: &mut Parts,
    state: &S,
) -> Result<Self, Self::Rejection> {
    // Extract and validate auth token
    let auth_header = parts
        .headers
        .get("authorization")
        .and_then(|v| v.to_str().ok())
        .ok_or_else(|| {
            (StatusCode::UNAUTHORIZED, "Missing authorization header")
                .into_response()
        })?;

    // Validate token and return user
    Ok(AuthenticatedUser {
        id: 1,
        username: "alice".to_string(),
    })
}

if let Some(auth_header) = auth_header {
    if validate_token(auth_header).await {
        Ok(next.run(req).await)
    } else {
        Err(StatusCode::UNAUTHORIZED)
    }
} else {
    Err(StatusCode::UNAUTHORIZED)
}

if let Some(user) = authorize_user(auth_header).await {
    req.extensions_mut().insert(user);
    Ok(next.run(req).await)
} else {
    Err(StatusCode::UNAUTHORIZED)
}

fn layer(&self, inner: S) -> Self::Service {
    MyMiddleware { inner }
}

fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
    self.inner.poll_ready(cx)
}

fn call(&mut self, request: Request) -> Self::Future {
    // Process request
    let future = self.inner.call(request);
    Box::pin(async move {
        let response: Response = future.await?;
        // Process response
        Ok(response)
    })
}

fn layer(&self, inner: S) -> Self::Service {
    MyService {
        inner,
        state: self.state.clone(),
    }
}

fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>> {
    self.inner.poll_ready(cx)
}

fn call(&mut self, req: Request) -> Self::Future {
    // Use self.state here
    self.inner.call(req)
}

// Access cache (read)
let cache = state.cache.read().await;
let value = cache.get("key");

// Access cache (write)
drop(cache); // Release read lock
let mut cache = state.cache.write().await;
cache.insert("new_key".to_string(), "value".to_string());

Ok("Success".to_string())

    let body = Json(ErrorResponse {
        error: status.to_string(),
        message: error_message.to_string(),
    });

    (status, body).into_response()
}

// Process create_user
Ok(Json(user))

async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
    let Json(data) = Json::<T>::from_request(req, state)
        .await
        .map_err(|err| {
            (
                StatusCode::BAD_REQUEST,
                format!("Invalid JSON: {}", err),
            ).into_response()
        })?;

    data.validate().map_err(|err| {
        (
            StatusCode::BAD_REQUEST,
            format!("Validation error: {}", err),
        ).into_response()
    })?;

    Ok(ValidatedJson(data))
}

let body = Body::from_stream(tokio_util::io::ReaderStream::new(file));

Ok(Response::builder()
    .status(StatusCode::OK)
    .header(header::CONTENT_TYPE, "application/pdf")
    .header(
        header::CONTENT_DISPOSITION,
        "attachment; filename=\"file.pdf\"",
    )
    .body(body)
    .unwrap())

Ok(Json(user))

let state = AppState { db };

let app = Router::new()
    .route("/users/:id", get(get_user))
    .with_state(state);

let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
axum::serve(listener, app).await.unwrap();

let db = PgPoolOptions::new()
    .connect(&settings.database_url)
    .await
    .expect("Failed to connect to database");

let state = AppState {
    settings: settings.clone(),
    db,
};

let app = Router::new()
    .route("/", get(handler))
    .with_state(state);

let addr = format!("0.0.0.0:{}", settings.port);
let listener = tokio::net::TcpListener::bind(addr).await.unwrap();
axum::serve(listener, app).await.unwrap();

info!("Starting server");

let app = Router::new()
    .route("/", get(handler))
    .layer(TraceLayer::new_for_http());

let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
info!("Listening on {}", listener.local_addr().unwrap());
axum::serve(listener, app).await.unwrap();

match get_user_from_db(id).await {
    Ok(user) => {
        info!("Successfully retrieved user {}", id);
        Ok(format!("User: {}", user))
    }
    Err(e) => {
        error!("Failed to get user {}: {}", id, e);
        Err(AppError::Database(e))
    }
}

#[cfg(unix)]
let terminate = async {
    signal::unix::signal(signal::unix::SignalKind::terminate())
        .expect("failed to install signal handler")
        .recv()
        .await;
};

#[cfg(not(unix))]
let terminate = std::future::pending::<()>();

tokio::select! {
    _ = ctrl_c => {},
    _ = terminate => {},
}

println!("Signal received, starting graceful shutdown");

let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
axum::serve(listener, app)
    .with_graceful_shutdown(shutdown_signal())
    .await
    .unwrap();

let cache_status = match state.redis.ping().await {
    Ok(_) => "healthy",
    Err(_) => "unhealthy",
};

Json(HealthResponse {
    status: if db_status == "healthy" && cache_status == "healthy" {
        "healthy".to_string()
    } else {
        "degraded".to_string()
    },
    database: db_status.to_string(),
    cache: cache_status.to_string(),
})

async fn from_request(req: Request, state: &S) -> Result<Self, Self::Rejection> {
    let Json(data) = Json::<T>::from_request(req, state)
        .await
        .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?;

    data.validate()
        .map_err(|e| (StatusCode::BAD_REQUEST, e.to_string()))?;

    Ok(ValidatedJson(data))
}

#[tokio::test]
async fn test_handler() {
    let app = Router::new().route("/", get(handler));

    let response = app
        .oneshot(Request::builder().uri("/").body(Body::empty()).unwrap())
        .await
        .unwrap();

    assert_eq!(response.status(), StatusCode::OK);
}

#[tokio::test]
async fn test_create_user() {
    let state = AppState::test();
    let app = create_app(state);

    let request_body = json!({
        "username": "testuser",
        "email": "test@example.com"
    });

    let response = app
        .oneshot(
            Request::builder()
                .method(Method::POST)
                .uri("/users")
                .header("content-type", "application/json")
                .body(Body::from(request_body.to_string()))
                .unwrap()
        )
        .await
        .unwrap();

    assert_eq!(response.status(), StatusCode::CREATED);
}