Axum

https://docs.rs/axum/latest/axum/
Admin
Axum is a web application framework for Rust that focuses on ergonomics and modularity, leveraging...
Tokens:1,502,059
Snippets:6,621
Trust Score:9.7
Update:10 hours ago
Show doc for...
Tokens:
Raw
### method_not_allowed_fallback example with Router

Source: https://docs.rs/axum/latest/axum/routing/struct.Router.html

Shows a Router with a route for GET /, a default fallback, and a method_not_allowed_fallback. A GET on / triggers hello_world, a POST triggers handle_405, and an unknown path triggers default_fallback.

```rust
use axum::{response::IntoResponse, routing::get, Router};

async fn hello_world() -> impl IntoResponse {
    "Hello, world!\n"
}

async fn default_fallback() -> impl IntoResponse {
    "Default fallback\n"
}

async fn handle_405() -> impl IntoResponse {
    "Method not allowed fallback"
}

#[tokio::main]
async fn main() {
    let router = Router::new()
        .route("/", get(hello_world))
        .fallback(default_fallback)
        .method_not_allowed_fallback(handle_405);

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

    axum::serve(listener, router).await.unwrap();
}
```

--------------------------------

### Routing example with Router and get/post methods

Source: https://docs.rs/axum/latest/axum/

Shows how to set up routes using Router::new().route() with get and post methods. Handlers are defined as async functions that return nothing.

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

// our router
let app = Router::new()
    .route("/", get(root))
    .route("/foo", get(get_foo).post(post_foo))
    .route("/foo/bar", get(foo_bar));

// which calls one of these handlers
async fn root() {}
async fn get_foo() {}
async fn post_foo() {}
async fn foo_bar() {}
```

--------------------------------

### Using without_v07_checks to allow colon and asterisk routes

Source: https://docs.rs/axum/latest/axum/routing/struct.Router.html

Example showing how to use without_v07_checks() to enable routes starting with ':' or '*', which are otherwise prohibited. The resulting app accepts GET /:colon and GET /*asterisk.

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

let app = Router::<()>::new()
    .without_v07_checks()
    .route("/:colon", get(|| async {}))
    .route("/*asterisk", get(|| async {}));

// Our app now accepts
// - GET /:colon
// - GET /*asterisk
```

--------------------------------

### Hello World example using axum and tokio

Source: https://docs.rs/axum/latest/axum/

Minimal axum application that serves 'Hello, World!' on the root path. Requires tokio's 'macros' and 'rt-multi-thread' features (or 'full') for #[tokio::main].

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

#[tokio::main]
async fn main() {
    // build our application with a single route
    let app = Router::new().route("/", get(|| async { "Hello, World!" }));

    // run our app with hyper, listening globally on port 3000
    let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
    axum::serve(listener, app).await.unwrap();
}
```

--------------------------------

### match_indices example

Source: https://docs.rs/axum/latest/axum/extract/ws/struct.Utf8Bytes.html

Shows how to use match_indices to get the start index of each match. For overlapping matches, only the first match's index is returned. The returned iterator is a DoubleEndedIterator if the pattern allows a reverse search and forward/reverse search yields the same elements.

```rust
let v: Vec<_> = "abcXXXabcYYYabc".match_indices("abc").collect();
assert_eq!(v, [(0, "abc"), (6, "abc"), (12, "abc")]);

let v: Vec<_> = "1abcabc2".match_indices("abc").collect();
assert_eq!(v, [(1, "abc"), (4, "abc")]);

let v: Vec<_> = "ababa".match_indices("aba").collect();
assert_eq!(v, [(0, "aba")]); // only the first `aba`
```

--------------------------------

### Basic usage of any

Source: https://docs.rs/axum/latest/axum/routing/method_routing/fn.any.html

Example showing how to use `any` to route all requests to `/` to a handler. The handler is an async function that does nothing.

```rust
use axum::{
    routing::any,
    Router,
};

async fn handler() {}

// All requests to `/` will go to `handler`.
let app = Router::new().route("/", any(handler));
```

--------------------------------

### Example usage of axum::routing::get

Source: https://docs.rs/axum/latest/axum/routing/method_routing/fn.get.html

Example showing how to use `get` to route GET requests to a handler. The handler is an async function that does nothing. The router routes `GET /` to the handler. Note that `get` routes also handle HEAD requests but with the response body removed.

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

async fn handler() {}

// Requests to `GET /` will go to `handler`.
let app = Router::new().route("/", get(handler));
```

--------------------------------

### Example usage of get_service

Source: https://docs.rs/axum/latest/axum/routing/method_routing/fn.get_service.html

Example showing how to use `get_service` to route GET requests to a service. It creates a `tower::service_fn` that returns an empty response, then mounts it at `/` in a `Router`. Note that GET routes also handle HEAD requests but with the response body removed.

```rust
use axum::{
    extract::Request,
    Router,
    routing::get_service,
    body::Body,
};
use http::Response;
use std::convert::Infallible;

let service = tower::service_fn(|request: Request| async {
    Ok::<_, Infallible>(Response::new(Body::empty()))
});

// Requests to `GET /` will go to `service`.
let app = Router::new().route("/", get_service(service));
```

--------------------------------

### More routing examples with captures and wildcards

Source: https://docs.rs/axum/latest/axum/routing/struct.Router.html

A comprehensive example showing multiple routes with static paths, captures, and wildcards, along with handler functions that extract path parameters.

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

let app = Router::new()
    .route("/", get(root))
    .route("/users", get(list_users).post(create_user))
    .route("/users/{id}", get(show_user))
    .route("/api/{version}/users/{id}/action", delete(do_users_action))
    .route("/assets/{*path}", get(serve_asset));

async fn root() {}

async fn list_users() {}

async fn create_user() {}

async fn show_user(Path(id): Path<u64>) {}

async fn do_users_action(Path((version, id)): Path<(String, u64)>) {}

async fn serve_asset(Path(path): Path<String>) {}
```

--------------------------------

### trim_start examples

Source: https://docs.rs/axum/latest/axum/extract/ws/struct.Utf8Bytes.html

Shows the trim_start method, which removes only leading whitespace. The first example demonstrates basic usage, and the second example shows directionality with English and Hebrew text, where 'start' refers to the first byte position.

```rust
let s = "\n Hello\tworld\t\n";
assert_eq!("Hello\tworld\t\n", s.trim_start());
```

```rust
let s = "  English  ";
assert!(Some('E') == s.trim_start().chars().next());

let s = "  עברית  ";
assert!(Some('ע') == s.trim_start().chars().next());
```

--------------------------------

### serve

Source: https://docs.rs/axum/latest/axum/all.html

Serves the application. This function starts the server and listens for incoming connections.

```APIDOC
## Function: serve

### Description
Serves the application.

### Signature
`pub async fn serve(listener: TcpListener, app: Router) -> Result<(), std::io::Error>`

### Parameters
- `listener` (TcpListener) - The TCP listener to accept connections on.
- `app` (Router) - The router to serve.

### Returns
- `Result<(), std::io::Error>` - Ok if the server runs successfully, or an error.
```

--------------------------------

### Example: using from_fn_with_state with State extractor

Source: https://docs.rs/axum/latest/axum/middleware/fn.from_fn_with_state.html

Shows a complete example of creating a middleware with from_fn_with_state, including an AppState struct, a middleware function that extracts State and Request, and a Router that applies the middleware with route_layer.

```rust
use axum::{
    Router,
    http::StatusCode,
    routing::get,
    response::{IntoResponse, Response},
    middleware::{self, Next},
    extract::{Request, State},
};

#[derive(Clone)]
struct AppState { /* ... */ }

async fn my_middleware(
    State(state): State<AppState>,
    // you can add more extractors here but the last
    // extractor must implement `FromRequest` which
    // `Request` does
    request: Request,
    next: Next,
) -> Response {
    // do something with `request`...

    let response = next.run(request).await;

    // do something with `response`...

    response
}

let state = AppState { /* ... */ };

let app = Router::new()
    .route("/", get(|| async { /* ... */ }))
    .route_layer(middleware::from_fn_with_state(state.clone(), my_middleware))
    .with_state(state);
```

--------------------------------

### Example: implementing IntoResponseParts for SetHeader

Source: https://docs.rs/axum/latest/axum/response/trait.IntoResponseParts.html

Complete example showing how to implement IntoResponseParts for a custom SetHeader type, including error handling for invalid header names/values, a recommended IntoResponse implementation, and usage in handlers.

```rust
use axum::{
    response::{ResponseParts, IntoResponse, IntoResponseParts, Response},
    http::{StatusCode, header::{HeaderName, HeaderValue}},
};

// Hypothetical helper type for setting a single header
struct SetHeader<'a>(&'a str, &'a str);

impl<'a> IntoResponseParts for SetHeader<'a> {
    type Error = (StatusCode, String);

    fn into_response_parts(self, mut res: ResponseParts) -> Result<ResponseParts, Self::Error> {
        match (self.0.parse::<HeaderName>(), self.1.parse::<HeaderValue>()) {
            (Ok(name), Ok(value)) => {
                res.headers_mut().insert(name, value);
            },
            (Err(_), _) => {
                return Err((
                    StatusCode::INTERNAL_SERVER_ERROR,
                    format!("Invalid header name {}", self.0),
                ));
            },
            (_, Err(_)) => {
                return Err((
                    StatusCode::INTERNAL_SERVER_ERROR,
                    format!("Invalid header value {}", self.1),
                ));
            },
        }

        Ok(res)
    }
}

// It's also recommended to implement `IntoResponse` so `SetHeader` can be used on its own as
// the response
impl<'a> IntoResponse for SetHeader<'a> {
    fn into_response(self) -> Response {
        // This gives an empty response with the header
        (self, ()).into_response()
    }
}

// We can now return `SetHeader` in responses
//
// Note that returning `impl IntoResponse` might be easier if the response has many parts to
// it. The return type is written out here for clarity.
async fn handler() -> (SetHeader<'static>, SetHeader<'static>, &'static str) {
    (
        SetHeader("server", "axum"),
        SetHeader("x-foo", "custom"),
        "body",
    )
}

// Or on its own as the whole response
async fn other_handler() -> SetHeader<'static> {
    SetHeader("x-foo", "custom")
}
```

--------------------------------

### Merge simple routers with Router::merge

Source: https://docs.rs/axum/latest/axum/routing/struct.Router.html

Shows how to combine multiple routers into one using Router::merge. The example defines user_routes and team_routes separately, then merges them into a single app. The resulting app accepts GET /users, GET /users/{id}, and GET /teams.

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

// define some routes separately
let user_routes = Router::new()
    .route("/users", get(users_list))
    .route("/users/{id}", get(users_show));

let team_routes = Router::new()
    .route("/teams", get(teams_list));

// combine them into one
let app = Router::new()
    .merge(user_routes)
    .merge(team_routes);

// could also do `user_routes.merge(team_routes)`

// Our app now accepts
// - GET /users
// - GET /users/{id}
// - GET /teams
```

--------------------------------

### get example: Safe subslicing with Option

Source: https://docs.rs/axum/latest/axum/extract/ws/struct.Utf8Bytes.html

Returns a subslice of str as an Option, returning None when the equivalent indexing operation would panic. The example demonstrates valid UTF-8 boundaries and out-of-bounds cases.

```rust
let v = String::from("🗻∈🌏");

assert_eq!(Some("🗻"), v.get(0..4));

// indices not on UTF-8 sequence boundaries
assert!(v.get(1..).is_none());
assert!(v.get(..8).is_none());

// out of bounds
assert!(v.get(..42).is_none());
```

--------------------------------

### get_service

Source: https://docs.rs/axum/latest/axum/routing/method_routing/struct.MethodRouter.html

Chains an additional service that will only accept GET requests. Includes an example showing how to combine with post_service.

```APIDOC
## get_service

### Description
Chains an additional service that will only accept `GET` requests. Note that `get` routes will also be called for `HEAD` requests but will have the response body removed. Make sure to add explicit `HEAD` routes afterwards.

### Method
GET

### Endpoint
N/A (MethodRouter method)

### Parameters
#### Type Parameters
- **T** (Service) - Required - The service to chain. Must implement `Service<Request, Error = E> + Clone + Send + Sync + 'static`, with `T::Response: IntoResponse + 'static` and `T::Future: Send + 'static`.

### Request Example
```rust
use axum::{
    extract::Request,
    Router,
    routing::post_service,
    body::Body,
};
use http::Response;
use std::convert::Infallible;

let service = tower::service_fn(|request: Request| async {
    Ok::<_, Infallible>(Response::new(Body::empty()))
});

let other_service = tower::service_fn(|request: Request| async {
    Ok::<_, Infallible>(Response::new(Body::empty()))
});

// Requests to `POST /` will go to `service` and `GET /` will go to
// `other_service`.
let app = Router::new().route("/", post_service(service).get_service(other_service));
```

### Response
#### Success Response (200)
- **Self** (MethodRouter) - The updated MethodRouter with the service chained.

#### Response Example
N/A

### Error Handling
N/A
```

--------------------------------

### Example: Using map_response_with_state with Router

Source: https://docs.rs/axum/latest/axum/middleware/fn.map_response_with_state.html

Example showing how to create a middleware that transforms a response with state. The middleware extracts AppState via State, and the layer is added with route_layer. The state is provided via with_state.

```rust
use axum::{
    Router,
    http::StatusCode,
    routing::get,
    response::Response,
    middleware::map_response_with_state,
    extract::State,
};

#[derive(Clone)]
struct AppState { /* ... */ }

async fn my_middleware<B>(
    State(state): State<AppState>,
    // you can add more extractors here but they must
    // all implement `FromRequestParts`
    // `FromRequest` is not allowed
    response: Response<B>,
) -> Response<B> {
    // do something with `state` and `response`...
    response
}

let state = AppState { /* ... */ };

let app = Router::new()
    .route("/", get(|| async { /* ... */ }))
    .route_layer(map_response_with_state(state.clone(), my_middleware))
    .with_state(state);
```

--------------------------------

### Convert Router to MakeService with into_make_service

Source: https://docs.rs/axum/latest/axum/routing/struct.Router.html

Basic example of converting a Router into a MakeService using into_make_service and serving it with axum::serve. Requires tokio for the async runtime.

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

let app = Router::new().route("/", get(|| async { "Hi!" }));

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

--------------------------------

### str::len example

Source: https://docs.rs/axum/latest/axum/extract/ws/struct.Utf8Bytes.html

Shows how to get the byte length of a string, not the character count. The example asserts that "foo" has length 3 and "ƒoo" has length 4, while its character count is 3.

```rust
let len = "foo".len();
assert_eq!(3, len);

assert_eq!("ƒoo".len(), 4); // fancy f!
assert_eq!("ƒoo".chars().count(), 3);
```

--------------------------------

### Example usage of axum::routing::on with MethodFilter::POST

Source: https://docs.rs/axum/latest/axum/routing/method_routing/fn.on.html

Example showing how to use `on` to route POST requests to a handler. It imports `on`, `Router`, and `MethodFilter`, defines an async handler, and creates a router with a route for `POST /`.

```rust
use axum::{
    routing::on,
    Router,
    routing::MethodFilter,
};

async fn handler() {}

// Requests to `POST /` will go to `handler`.
let app = Router::new().route("/", on(MethodFilter::POST, handler));

```

--------------------------------

### Panic example: adding colon route without without_v07_checks

Source: https://docs.rs/axum/latest/axum/routing/struct.Router.html

This example panics because it adds a route starting with ':' without calling without_v07_checks() first. It demonstrates the panic that occurs when such routes are added without disabling v0.7 checks.

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

// This panics...
let app = Router::<()>::new()
    .route("/:colon", get(|| async {}));
```

--------------------------------

### Chain a service for GET requests with MethodRouter::get_service

Source: https://docs.rs/axum/latest/axum/routing/method_routing/struct.MethodRouter.html

Shows how to chain a service that accepts only GET requests onto a MethodRouter. The example uses post_service(service).get_service(other_service) so POST / goes to service and GET / goes to other_service. Note that get routes also handle HEAD requests but the response body is removed, so explicit HEAD routes should be added afterwards.

```rust
use axum::{
    extract::Request,
    Router,
    routing::post_service,
    body::Body,
};
use http::Response;
use std::convert::Infallible;

let service = tower::service_fn(|request: Request| async {
    Ok::<_, Infallible>(Response::new(Body::empty()))
});

let other_service = tower::service_fn(|request: Request| async {
    Ok::<_, Infallible>(Response::new(Body::empty()))
});

// Requests to `POST /` will go to `service` and `GET /` will go to
// `other_service`.
let app = Router::new().route("/", post_service(service).get_service(other_service));
```

--------------------------------

### Serve a handler with connect info using into_make_service_with_connect_info

Source: https://docs.rs/axum/latest/axum/handler/struct.HandlerService.html

Converts a handler into a MakeService that stores connection information, available with the tokio feature. The example extracts ConnectInfo<SocketAddr> and State, then serves with axum::serve.

```rust
use axum::{
    handler::Handler,
    response::IntoResponse,
    extract::{ConnectInfo, State},
};
use std::net::SocketAddr;

#[derive(Clone)]
struct AppState {};

async fn handler(
    ConnectInfo(addr): ConnectInfo<SocketAddr>,
    State(state): State<AppState>,
) -> String {
    format!("Hello {addr}")
}

let app = handler.with_state(AppState {});

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

--------------------------------

### path() example: absolute URI

Source: https://docs.rs/axum/latest/axum/extract/struct.OriginalUri.html

Parses an absolute URI and asserts its path.

```rust
let uri: Uri = "http://example.org/hello/world".parse().unwrap();

assert_eq!(uri.path(), "/hello/world");
```

--------------------------------

### Merge two MethodRouters with get.merge(post)

Source: https://docs.rs/axum/latest/axum/routing/method_routing/struct.MethodRouter.html

Shows how to use the merge method to combine two MethodRouter instances into one. The example creates a GET and a POST router, merges them, and mounts the result at the root path. After merging, the app accepts both GET / and POST / requests.

```rust
use axum::{
    routing::{get, post},
    Router,
};

let get = get(|| async {});
let post = post(|| async {});

let merged = get.merge(post);

let app = Router::new().route("/", merged);

// Our app now accepts
// - GET /
// - POST /
```

--------------------------------

### strip_circumfix examples

Source: https://docs.rs/axum/latest/axum/extract/ws/struct.Utf8Bytes.html

Shows how strip_circumfix removes both a prefix and a suffix exactly once if the string starts with the prefix and ends with the suffix and they do not overlap, returning Some with the middle, or None otherwise.

```rust
assert_eq!("bar:hello:foo".strip_circumfix("bar:", ":foo"), Some("hello"));
assert_eq!("bar:foo".strip_circumfix("foo", "foo"), None);
assert_eq!("foo:bar;".strip_circumfix("foo:", ';'), Some("bar"));
assert_eq!("foo:bar:baz".strip_circumfix("foo:bar:", ":bar:baz"), None);
```
Tokens:
Raw