Struct axum::routing::Router[][src]

pub struct Router<S> { /* fields omitted */ }
Expand description

The router type for composing handlers and services.

Implementations

Create a new Router.

Unless you add additional routes this will respond to 404 Not Found to all requests.

Add another route to the router.

path is a string of path segments separated by /. Each segment can be either concrete or a capture:

  • /foo/bar/baz will only match requests where the path is /foo/bar/bar.
  • /:foo will match any route with exactly one segment and it will capture the first segment and store it at the key foo.

service is the Service that should receive the request if the path matches path.

Example

use axum::{handler::{get, delete}, Router};

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_thing));

async fn root() { /* ... */ }

async fn list_users() { /* ... */ }

async fn create_user() { /* ... */ }

async fn show_user() { /* ... */ }

async fn do_thing() { /* ... */ }

Panics

Panics if path doesn’t start with /.

Nest a group of routes (or a Service) at some path.

This allows you to break your application into smaller pieces and compose them together.

use axum::{
    handler::get,
    Router,
};
use http::Uri;

async fn users_get(uri: Uri) {
    // `uri` will be `/users` since `nest` strips the matching prefix.
    // use `OriginalUri` to always get the full URI.
}

async fn users_post() {}

async fn careers() {}

let users_api = Router::new().route("/users", get(users_get).post(users_post));

let app = Router::new()
    .nest("/api", users_api)
    .route("/careers", get(careers));

Note that nested routes will not see the orignal request URI but instead have the matched prefix stripped. This is necessary for services like static file serving to work. Use OriginalUri if you need the original request URI.

Take care when using nest together with dynamic routes as nesting also captures from the outer routes:

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

async fn users_get(Path(params): Path<HashMap<String, String>>) {
    // Both `version` and `id` were 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));

let app = Router::new().nest("/:version/api", users_api);

nest also accepts any Service. This can for example be used with tower_http::services::ServeDir to serve static files from a directory:

use axum::{
    Router,
    service::get,
};
use tower_http::services::ServeDir;

// Serves files inside the `public` directory at `GET /public/*`
let serve_dir_service = ServeDir::new("public");

let app = Router::new().nest("/public", get(serve_dir_service));

If necessary you can use Router::boxed to box a group of routes making the type easier to name. This is sometimes useful when working with nest.

Create a boxed route trait object.

This makes it easier to name the types of routers to, for example, return them from functions:

use axum::{
    body::Body,
    handler::get,
    Router,
    routing::BoxRoute
};

async fn first_handler() { /* ... */ }

async fn second_handler() { /* ... */ }

async fn third_handler() { /* ... */ }

fn app() -> Router<BoxRoute> {
    Router::new()
        .route("/", get(first_handler).post(second_handler))
        .route("/foo", get(third_handler))
        .boxed()
}

It also helps with compile times when you have a very large number of routes.

Apply a tower::Layer to the router.

All requests to the router will be processed by the layer’s corresponding middleware.

This can be used to add additional processing to a request for a group of routes.

Note this differs from handler::Layered which adds a middleware to a single handler.

Example

Adding the tower::limit::ConcurrencyLimit middleware to a group of routes can be done like so:

use axum::{
    handler::get,
    Router,
};
use tower::limit::{ConcurrencyLimitLayer, ConcurrencyLimit};

async fn first_handler() { /* ... */ }

async fn second_handler() { /* ... */ }

async fn third_handler() { /* ... */ }

// All requests to `handler` and `other_handler` will be sent through
// `ConcurrencyLimit`
let app = Router::new().route("/", get(first_handler))
    .route("/foo", get(second_handler))
    .layer(ConcurrencyLimitLayer::new(64))
    // Request to `GET /bar` will go directly to `third_handler` and
    // wont be sent through `ConcurrencyLimit`
    .route("/bar", get(third_handler));

This is commonly used to add middleware such as tracing/logging to your entire app:

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

async fn first_handler() { /* ... */ }

async fn second_handler() { /* ... */ }

async fn third_handler() { /* ... */ }

let app = Router::new()
    .route("/", get(first_handler))
    .route("/foo", get(second_handler))
    .route("/bar", get(third_handler))
    .layer(TraceLayer::new_for_http());

Convert this router into a MakeService, that is a Service who’s response is another service.

This is useful when running your application with hyper’s Server:

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

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

axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
    .serve(app.into_make_service())
    .await
    .expect("server failed");

Convert this router into a MakeService, that will store C’s associated ConnectInfo in a request extension such that ConnectInfo can extract it.

This enables extracting things like the client’s remote address.

Extracting std::net::SocketAddr is supported out of the box:

use axum::{
    extract::ConnectInfo,
    handler::get,
    Router,
};
use std::net::SocketAddr;

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

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

axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
    .serve(
        app.into_make_service_with_connect_info::<SocketAddr, _>()
    )
    .await
    .expect("server failed");

You can implement custom a Connected like so:

use axum::{
    extract::connect_info::{ConnectInfo, Connected},
    handler::get,
    Router,
};
use hyper::server::conn::AddrStream;

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

async fn handler(
    ConnectInfo(my_connect_info): ConnectInfo<MyConnectInfo>,
) -> String {
    format!("Hello {:?}", my_connect_info)
}

#[derive(Clone, Debug)]
struct MyConnectInfo {
    // ...
}

impl Connected<&AddrStream> for MyConnectInfo {
    type ConnectInfo = MyConnectInfo;

    fn connect_info(target: &AddrStream) -> Self::ConnectInfo {
        MyConnectInfo {
            // ...
        }
    }
}

axum::Server::bind(&"0.0.0.0:3000".parse().unwrap())
    .serve(
        app.into_make_service_with_connect_info::<MyConnectInfo, _>()
    )
    .await
    .expect("server failed");

See the unix domain socket example for an example of how to use this to collect UDS connection info.

Merge two routers into one.

This is useful for breaking apps into smaller pieces and combining them into one.

use axum::{
    handler::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 = user_routes.or(team_routes);

Handle errors services in this router might produce, by mapping them to responses.

Unhandled errors will close the connection without sending a response.

Example

use axum::{
    handler::get,
    http::StatusCode,
    Router,
};
use tower::{BoxError, timeout::TimeoutLayer};
use std::{time::Duration, convert::Infallible};

// This router can never fail, since handlers can never fail.
let app = Router::new().route("/", get(|| async {}));

// Now the router can fail since the `tower::timeout::Timeout`
// middleware will return an error if the timeout elapses.
let app = app.layer(TimeoutLayer::new(Duration::from_secs(10)));

// With `handle_error` we can handle errors `Timeout` might produce.
// Our router now cannot fail, that is its error type is `Infallible`.
let app = app.handle_error(|error: BoxError| {
    if error.is::<tower::timeout::error::Elapsed>() {
        Ok::<_, Infallible>((
            StatusCode::REQUEST_TIMEOUT,
            "request took too long to handle".to_string(),
        ))
    } else {
        Ok::<_, Infallible>((
            StatusCode::INTERNAL_SERVER_ERROR,
            format!("Unhandled error: {}", error),
        ))
    }
});

You can return Err(_) from the closure if you don’t wish to handle some errors:

use axum::{
    handler::get,
    http::StatusCode,
    Router,
};
use tower::{BoxError, timeout::TimeoutLayer};
use std::time::Duration;

let app = Router::new()
    .route("/", get(|| async {}))
    .layer(TimeoutLayer::new(Duration::from_secs(10)))
    .handle_error(|error: BoxError| {
        if error.is::<tower::timeout::error::Elapsed>() {
            Ok((
                StatusCode::REQUEST_TIMEOUT,
                "request took too long to handle".to_string(),
            ))
        } else {
            // return the error as is
            Err(error)
        }
    });

Check that your service cannot fail.

That is, its error type is Infallible.

Trait Implementations

Returns a copy of the value. Read more

Performs copy-assignment from source. Read more

Formats the value using the given formatter. Read more

Returns the “default value” for a type. Read more

Responses given by the service.

Errors produced by the service.

The future response value.

Returns Poll::Ready(Ok(())) when the service is able to process requests. Read more

Process the request and return the response asynchronously. Read more

Auto Trait Implementations

Blanket Implementations

Gets the TypeId of self. Read more

Immutably borrows from an owned value. Read more

Mutably borrows from an owned value. Read more

Converts self into T using Into<T>. Read more

Converts self into a target type. Read more

Causes self to use its Binary implementation when Debug-formatted.

Causes self to use its Display implementation when Debug-formatted. Read more

Causes self to use its LowerExp implementation when Debug-formatted. Read more

Causes self to use its LowerHex implementation when Debug-formatted. Read more

Causes self to use its Octal implementation when Debug-formatted.

Causes self to use its Pointer implementation when Debug-formatted. Read more

Causes self to use its UpperExp implementation when Debug-formatted. Read more

Causes self to use its UpperHex implementation when Debug-formatted. Read more

Performs the conversion.

Instruments this type with the provided Span, returning an Instrumented wrapper. Read more

Instruments this type with the current Span, returning an Instrumented wrapper. Read more

Performs the conversion.

Responses given by the service

Errors produced by the service

The Service value created by this factory

Errors produced while building a service.

The future of the Service instance.

Returns Poll::Ready when the factory is able to create more services. Read more

Create and return a new service value asynchronously.

Consume this MakeService and convert it into a Service. Read more

Convert this MakeService into a Service without consuming the original MakeService. Read more

Pipes by value. This is generally the method you want to use. Read more

Borrows self and passes that borrow into the pipe function. Read more

Mutably borrows self and passes that borrow into the pipe function. Read more

Borrows self, then passes self.borrow() into the pipe function. Read more

Mutably borrows self, then passes self.borrow_mut() into the pipe function. Read more

Borrows self, then passes self.as_ref() into the pipe function.

Mutably borrows self, then passes self.as_mut() into the pipe function. Read more

Borrows self, then passes self.deref() into the pipe function.

Mutably borrows self, then passes self.deref_mut() into the pipe function. Read more

Pipes a value into a function that cannot ordinarily be called in suffix position. Read more

Pipes a trait borrow into a function that cannot normally be called in suffix position. Read more

Pipes a trait mutable borrow into a function that cannot normally be called in suffix position. Read more

Pipes a trait borrow into a function that cannot normally be called in suffix position. Read more

Pipes a trait mutable borrow into a function that cannot normally be called in suffix position. Read more

Pipes a dereference into a function that cannot normally be called in suffix position. Read more

Pipes a mutable dereference into a function that cannot normally be called in suffix position. Read more

Pipes a reference into a function that cannot ordinarily be called in suffix position. Read more

Pipes a mutable reference into a function that cannot ordinarily be called in suffix position. Read more

Create a new Policy that returns Action::Follow only if self and other return Action::Follow. Read more

Create a new Policy that returns Action::Follow if either self or other returns Action::Follow. Read more

Should always be Self

Yields a mutable reference to the service when it is ready to accept a request.

👎 Deprecated since 0.4.6:

please use the ServiceExt::ready method instead

Yields a mutable reference to the service when it is ready to accept a request.

Yields the service when it is ready to accept a request.

Consume this Service, calling with the providing request once it is ready.

Process all requests from the given Stream, and produce a Stream of their responses. Read more

Executes a new future after this service’s future resolves. This does not alter the behaviour of the poll_ready method. Read more

Maps this service’s response value to a different value. This does not alter the behaviour of the poll_ready method. Read more

Maps this service’s error value to a different value. This does not alter the behaviour of the poll_ready method. Read more

Maps this service’s result type (Result<Self::Response, Self::Error>) to a different value, regardless of whether the future succeeds or fails. Read more

Composes a function in front of the service. Read more

Composes this service with a Filter that conditionally accepts or rejects requests based on a predicate. Read more

Composes this service with an AsyncFilter that conditionally accepts or rejects requests based on an [async predicate]. Read more

Composes an asynchronous function after this service. Read more

Composes a function that transforms futures produced by the service. Read more

Immutable access to a value. Read more

Mutable access to a value. Read more

Immutable access to the Borrow<B> of a value. Read more

Mutable access to the BorrowMut<B> of a value. Read more

Immutable access to the AsRef<R> view of a value. Read more

Mutable access to the AsMut<R> view of a value. Read more

Immutable access to the Deref::Target of a value. Read more

Mutable access to the Deref::Target of a value. Read more

Calls .tap() only in debug builds, and is erased in release builds.

Calls .tap_mut() only in debug builds, and is erased in release builds. Read more

Calls .tap_borrow() only in debug builds, and is erased in release builds. Read more

Calls .tap_borrow_mut() only in debug builds, and is erased in release builds. Read more

Calls .tap_ref() only in debug builds, and is erased in release builds. Read more

Calls .tap_ref_mut() only in debug builds, and is erased in release builds. Read more

Calls .tap_deref() only in debug builds, and is erased in release builds. Read more

Calls .tap_deref_mut() only in debug builds, and is erased in release builds. Read more

Provides immutable access for inspection. Read more

Calls tap in debug builds, and does nothing in release builds.

Provides mutable access for modification. Read more

Calls tap_mut in debug builds, and does nothing in release builds.

Provides immutable access to the reference for inspection.

Calls tap_ref in debug builds, and does nothing in release builds.

Provides mutable access to the reference for modification.

Calls tap_ref_mut in debug builds, and does nothing in release builds.

Provides immutable access to the borrow for inspection. Read more

Calls tap_borrow in debug builds, and does nothing in release builds.

Provides mutable access to the borrow for modification.

Calls tap_borrow_mut in debug builds, and does nothing in release builds. Read more

Immutably dereferences self for inspection.

Calls tap_deref in debug builds, and does nothing in release builds.

Mutably dereferences self for modification.

Calls tap_deref_mut in debug builds, and does nothing in release builds. Read more

The resulting type after obtaining ownership.

Creates owned data from borrowed data, usually by cloning. Read more

🔬 This is a nightly-only experimental API. (toowned_clone_into)

recently added

Uses borrowed data to replace owned data, usually by cloning. Read more

Attempts to convert self into T using TryInto<T>. Read more

Attempts to convert self into a target type. Read more

The type returned in the event of a conversion error.

Performs the conversion.

The type returned in the event of a conversion error.

Performs the conversion.