axum

axum-core provides the fundamental types and traits used by the axum web framework. It serves as the foundational layer for the ecosystem's core abstractions.

Key characteristics:

• Safety: The crate uses #![forbid(unsafe_code)], ensuring all implementations are in 100% safe Rust.
• MSRV: The Minimum Supported Rust Version is 1.75.

The axum-macros crate provides procedural macros designed specifically for use with the axum web framework. These macros help automate common tasks in defining handlers and working with the axum ecosystem.

Requirements:

• Minimum Supported Rust Version (MSRV): 1.75
• The crate is implemented using 100% safe Rust (#![forbid(unsafe_code)]).

Axum provides several high-level features for building HTTP services:

• Macro-free Routing: Route requests to handlers without needing complex macros.
• Declarative Extraction: Use extractors to parse request components (like JSON, query params, or headers) directly in handler arguments.
• Predictable Error Handling: A simple model for managing errors.
• Minimal Boilerplate: Generate responses easily.
• Tower Compatibility: Full support for tower and tower-http middleware and utilities.

In axum, a handler is an asynchronous function that serves as the core of your application logic. To be a valid handler, a function must satisfy two requirements:

1. Arguments: It must accept zero or more extractors as arguments.
2. Return Type: It must return a type that can be converted into a response.

Axum applications are constructed by defining routes that map incoming requests to these handlers.

When using .nest() with dynamic segments in the outer path (e.g., /{version}/api), the nested router will capture those outer segments. If you use a Path extractor in the nested handler, it will contain both the segments defined in the nested router and the segments captured by the outer nesting path.

use axum::{extract::Path, routing::get, Router};
use std::collections::HashMap;

async fn users_get(Path(params): Path<HashMap<String, String>>) {
    // Both `version` and `id` are captured even though `users_api` only
    // explicitly captures `id`.
    let version = params.get("version");
    let id = params.get("id");
}

let users_api = Router::new().route("/users/{id}", get(users_get));

// The 'version' segment from the nest is passed into users_api
let app = Router::new().nest("/{version}/api", users_api);
# let _: Router = app;

The fallback defined via Router::fallback is also merged during a merge operation. However, Router only supports a single fallback.

Warning: If you attempt to merge two routers that both have a fallback defined, the application will panic.

axum does not have a bespoke middleware system; instead, it integrates directly with tower. This allows you to use the entire ecosystem of tower and tower-http middleware.

To use middleware, you can apply it at different levels of granularity:

• Entire routers: Use Router::layer or Router::route_layer.
• Method routers: Use MethodRouter::layer or MethodRouter::route_layer.
• Individual handlers: Use Handler::layer.

use axum::{Router, routing::get};
use tower_http::trace::TraceLayer;

async fn handler() {}

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

Wildcards match all remaining segments in a path and store them in a single key. Use the syntax /{*key}.

Key Rules:

• Wildcards do not match empty segments. For example, /{*key} matches /a or /a/, but does not match the root /.
• The leading slash of the captured portion is excluded. For a route /foo/{*rest} and a request to /foo/bar/baz, the captured value of rest is bar/baz.

Extract wildcard values using the Path extractor.

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

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

async fn handler(Path(path): Path<String>) -> String {
    path
}