Deep Dive: How Axum 0.7 Handles HTTP Routing for High-Throughput Rust 1.85 Services

// Required dependencies (Cargo.toml):
// [dependencies]
// axum = "0.7.3"
// tokio = { version = "1.37", features = ["full"] }
// tower = "0.4.13"
// tower-http = { version = "0.5.2", features = ["trace"] }
// serde = { version = "1.0.197", features = ["derive"] }
// serde_json = "1.0.113"
// tracing = "0.1.40"
// tracing-subscriber = { version = "0.3.18", features = ["env-filter"] }

use axum::{
    extract::{Path, State},
    http::StatusCode,
    response::{IntoResponse, Json},
    routing::{get, post},
    Router,
};
use serde::{Deserialize, Serialize};
use tower_http::trace::TraceLayer;

// Application state shared across handlers
#[derive(Clone)]
struct AppState {
    // Simulated database connection pool
    db_pool: String, // In real apps, use sqlx::PgPool or similar
}

// Request/response structs with validation
#[derive(Deserialize)]
struct CreateUserRequest {
    username: String,
    email: String,
}

#[derive(Serialize)]
struct UserResponse {
    id: u64,
    username: String,
    email: String,
}

// Custom error type for consistent error handling
enum AppError {
    NotFound(String),
    InternalServerError(String),
    BadRequest(String),
}

// Implement IntoResponse to convert errors to HTTP responses
impl IntoResponse for AppError {
    fn into_response(self) -> axum::response::Response {
        let (status, message) = match self {
            AppError::NotFound(msg) => (StatusCode::NOT_FOUND, msg),
            AppError::InternalServerError(msg) => (StatusCode::INTERNAL_SERVER_ERROR, msg),
            AppError::BadRequest(msg) => (StatusCode::BAD_REQUEST, msg),
        };
        (status, message).into_response()
    }
}

// Static route handler: root endpoint
async fn root_handler() -> &'static str {
    "Axum 0.7 High-Throughput Routing Demo"
}

// Parameterized route handler: get user by ID
async fn get_user_handler(
    Path(user_id): Path,
    State(state): State,
) -> Result, AppError> {
    // Simulate database lookup
    if user_id == 0 {
        return Err(AppError::BadRequest("User ID must be non-zero".into()));
    }
    if user_id > 1000 {
        return Err(AppError::NotFound(format!("User {} not found", user_id)));
    }
    Ok(Json(UserResponse {
        id: user_id,
        username: format!("user_{}", user_id),
        email: format!("user_{}@example.com", user_id),
    }))
}

// POST handler for creating users
async fn create_user_handler(
    State(state): State,
    Json(payload): Json,
) -> Result<(StatusCode, Json), AppError> {
    if payload.username.is_empty() || payload.email.is_empty() {
        return Err(AppError::BadRequest("Username and email are required".into()));
    }
    // Simulate user creation
    let new_user = UserResponse {
        id: 12345, // In real apps, auto-increment from DB
        username: payload.username,
        email: payload.email,
    };
    Ok((StatusCode::CREATED, Json(new_user)))
}

#[tokio::main]
async fn main() {
    // Initialize tracing for logging
    tracing_subscriber::fmt()
        .with_env_filter("axum_routing_demo=debug,tower_http=debug")
        .init();

    // Initialize application state
    let state = AppState {
        db_pool: "postgres://user:pass@localhost/db".into(),
    };

    // Build router with routes, nesting, and middleware
    let app = Router::new()
        .route("/", get(root_handler))
        .route("/users", post(create_user_handler))
        .route("/users/:user_id", get(get_user_handler))
        // Nest admin routes under /admin
        .nest("/admin", Router::new().route("/health", get(|| async { "OK" })))
        // Add tracing middleware for request logging
        .layer(TraceLayer::new_for_http())
        // Attach shared state
        .with_state(state);

    // Bind to port 3000 and start server
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    println!("Server running on http://0.0.0.0:3000");
    axum::serve(listener, app).await.unwrap();
}

// Required dependencies (Cargo.toml):
// [dependencies]
// axum = "0.7.3"
// tokio = { version = "1.37", features = ["full"] }
// criterion = "0.5.1"
// http-body-util = "0.1.0"
// tower = "0.4.13"
// tower-test = "0.4.4"

use axum::{
    extract::Path,
    routing::get,
    Router,
};
use criterion::{criterion_group, criterion_main, Criterion};
use tower::ServiceExt; // for `oneshot` method

// Static route handler
async fn static_handler() -> &'static str {
    "static response"
}

// Parameterized route handler
async fn param_handler(Path(id): Path) -> String {
    format!("param response: {}", id)
}

// Build router for benchmarking
fn build_router() -> Router {
    Router::new()
        .route("/", get(static_handler))
        .route("/users/:id", get(param_handler))
}

// Benchmark static route matching
fn bench_static_route(c: &mut Criterion) {
    let mut group = c.benchmark_group("axum_0_7_static_routing");
    group.sample_size(1000); // 1000 iterations per benchmark

    let router = build_router();

    group.bench_function("static_route_match", |b| {
        b.iter(|| {
            // Create a test request for the static route
            let request = http::Request::builder()
                .uri("/")
                .body(axum::body::Body::empty())
                .unwrap();

            // Execute the request against the router
            let response = tokio::runtime::Runtime::new()
                .unwrap()
                .block_on(router.clone().oneshot(request))
                .unwrap();

            // Assert response is successful
            assert_eq!(response.status(), http::StatusCode::OK);
        })
    });

    group.finish();
}

// Benchmark parameterized route matching
fn bench_param_route(c: &mut Criterion) {
    let mut group = c.benchmark_group("axum_0_7_param_routing");
    group.sample_size(1000);

    let router = build_router();

    group.bench_function("param_route_match", |b| {
        b.iter(|| {
            // Create a test request for the parameterized route
            let request = http::Request::builder()
                .uri("/users/12345")
                .body(axum::body::Body::empty())
                .unwrap();

            // Execute the request
            let response = tokio::runtime::Runtime::new()
                .unwrap()
                .block_on(router.clone().oneshot(request))
                .unwrap();

            // Assert response is successful
            assert_eq!(response.status(), http::StatusCode::OK);
        })
    });

    group.finish();
}

// Benchmark nested route matching (common in real apps)
fn bench_nested_route(c: &mut Criterion) {
    let mut group = c.benchmark_group("axum_0_7_nested_routing");
    group.sample_size(1000);

    // Build nested router: /api/v1/users/:id
    let router = Router::new()
        .nest(
            "/api/v1",
            Router::new()
                .route("/users/:id", get(param_handler))
        );

    group.bench_function("nested_route_match", |b| {
        b.iter(|| {
            let request = http::Request::builder()
                .uri("/api/v1/users/67890")
                .body(axum::body::Body::empty())
                .unwrap();

            let response = tokio::runtime::Runtime::new()
                .unwrap()
                .block_on(router.clone().oneshot(request))
                .unwrap();

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

    group.finish();
}

criterion_group!(benches, bench_static_route, bench_param_route, bench_nested_route);
criterion_main!(benches);

// Required dependencies (Cargo.toml):
// [dependencies]
// axum = "0.7.3"
// tokio = { version = "1.37", features = ["full"] }
// serde = { version = "1.0.197", features = ["derive"] }
// jsonwebtoken = "9.2.0"
// base64 = "0.21.7"

use axum::{
    extract::{FromRequestParts, Path, RequestPartsExt},
    http::{request::Parts, StatusCode},
    response::{IntoResponse, Json},
    routing::get,
    Router,
};
use jsonwebtoken::{decode, DecodingKey, Validation};
use serde::{Deserialize, Serialize};

// Custom JWT claims struct
#[derive(Debug, Serialize, Deserialize)]
struct Claims {
    sub: String, // User ID
    exp: usize,  // Expiration time
    role: String,
}

// Custom extractor to validate JWT from Authorization header
struct AuthenticatedUser(Claims);

// Implement FromRequestParts to extract and validate JWT
impl FromRequestParts for AuthenticatedUser
where
    S: Send + Sync,
{
    type Rejection = (StatusCode, String);

    async fn from_request_parts(parts: &mut Parts, _state: &S) -> Result {
        // Extract Authorization header
        let auth_header = parts
            .headers
            .get("Authorization")
            .ok_or((StatusCode::UNAUTHORIZED, "Missing Authorization header".into()))?
            .to_str()
            .map_err(|_| (StatusCode::UNAUTHORIZED, "Invalid Authorization header".into()))?;

        // Check for Bearer token
        if !auth_header.starts_with("Bearer ") {
            return Err((StatusCode::UNAUTHORIZED, "Invalid token format".into()));
        }
        let token = &auth_header[7..];

        // Decode and validate JWT (using a hardcoded secret for demo; use env vars in prod)
        let secret = "my-secret-key-do-not-use-in-prod";
        let decoding_key = DecodingKey::from_secret(secret.as_bytes());
        let validation = Validation::default();

        let token_data = decode::(token, &decoding_key, &validation)
            .map_err(|e| (StatusCode::UNAUTHORIZED, format!("Invalid token: {}", e)))?;

        Ok(AuthenticatedUser(token_data.claims))
    }
}

// Protected route handler that uses the custom extractor
async fn protected_profile_handler(
    AuthenticatedUser(claims): AuthenticatedUser,
) -> Result, (StatusCode, String)> {
    Ok(Json(serde_json::json!({
        "user_id": claims.sub,
        "role": claims.role,
        "message": "Access granted to protected profile"
    })))
}

// Admin-only route with role check
async fn admin_dashboard_handler(
    AuthenticatedUser(claims): AuthenticatedUser,
) -> Result, (StatusCode, String)> {
    if claims.role != "admin" {
        return Err((StatusCode::FORBIDDEN, "Admin role required".into()));
    }
    Ok(Json(serde_json::json!({
        "message": "Welcome to admin dashboard",
        "user_id": claims.sub
    })))
}

// Fallback handler for unmatched routes
async fn fallback_handler() -> (StatusCode, &'static str) {
    (StatusCode::NOT_FOUND, "Route not found")
}

#[tokio::main]
async fn main() {
    // Build router with protected routes and fallback
    let app = Router::new()
        .route("/profile", get(protected_profile_handler))
        .route("/admin/dashboard", get(admin_dashboard_handler))
        // Add fallback for 404s
        .fallback(fallback_handler);

    // Start server
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3001").await.unwrap();
    println!("Protected server running on http://0.0.0.0:3001");
    axum::serve(listener, app).await.unwrap();
}

// Example: Nested routing for /api/v1
let api_v1_routes = Router::new()
    .route("/users", get(list_users))
    .route("/users/:id", get(get_user))
    .route("/transactions", post(create_transaction));

let app = Router::new()
    .nest("/api/v1", api_v1_routes)
    .route("/health", get(health_check));

// Bad: Regex validation in handler
async fn bad_uuid_handler(Path(raw_uuid): Path) -> Result, AppError> {
    let uuid = regex::Regex::new(r"^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$")
        .unwrap()
        .captures(&raw_uuid)
        .ok_or(AppError::BadRequest("Invalid UUID".into()))?
        .get(0)
        .unwrap()
        .as_str();
    // ... fetch resource
}

// Good: Use Uuid type with Path extractor
async fn good_uuid_handler(Path(resource_id): Path) -> Result, AppError> {
    // resource_id is already a valid Uuid, no regex needed
    // ... fetch resource
}

// Custom JSON fallback handler
async fn json_fallback_handler() -> (StatusCode, Json) {
    (
        StatusCode::NOT_FOUND,
        Json(serde_json::json!({
            "error": "route_not_found",
            "message": "The requested route does not exist"
        })),
    )
}

// Attach to router
let app = Router::new()
    .route("/health", get(health_check))
    .fallback(json_fallback_handler);