Struct axum::routing::MethodRouter

pub struct MethodRouter<B = Body, E = Infallible> { /* private fields */ }

A Service that accepts requests based on a MethodFilter and allows chaining additional handlers and services.

Implementations

impl<B, E> MethodRouter<B, E>

pub fn new() -> Self

Create a default MethodRouter that will respond with 405 Method Not Allowed to all requests.

impl<B> MethodRouter<B, Infallible> where
    B: Send + 'static, 

pub fn on<H, T>(self, filter: MethodFilter, handler: H) -> Self where
    H: Handler<T, B>,
    T: 'static, 

Chain an additional handler that will accept requests matching the given MethodFilter.

Example

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

async fn handler() {}

async fn other_handler() {}

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

pub fn delete<H, T>(self, handler: H) -> Self where
    H: Handler<T, B>,
    T: 'static, 

Chain an additional handler that will only accept DELETE requests.

See MethodRouter::get for an example.

pub fn get<H, T>(self, handler: H) -> Self where
    H: Handler<T, B>,
    T: 'static, 

Chain an additional handler that will only accept GET requests.

Example

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

async fn handler() {}

async fn other_handler() {}

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

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.

pub fn head<H, T>(self, handler: H) -> Self where
    H: Handler<T, B>,
    T: 'static, 

Chain an additional handler that will only accept HEAD requests.

See MethodRouter::get for an example.

pub fn options<H, T>(self, handler: H) -> Self where
    H: Handler<T, B>,
    T: 'static, 

Chain an additional handler that will only accept OPTIONS requests.

See MethodRouter::get for an example.

pub fn patch<H, T>(self, handler: H) -> Self where
    H: Handler<T, B>,
    T: 'static, 

Chain an additional handler that will only accept PATCH requests.

See MethodRouter::get for an example.

pub fn post<H, T>(self, handler: H) -> Self where
    H: Handler<T, B>,
    T: 'static, 

Chain an additional handler that will only accept POST requests.

See MethodRouter::get for an example.

pub fn put<H, T>(self, handler: H) -> Self where
    H: Handler<T, B>,
    T: 'static, 

Chain an additional handler that will only accept PUT requests.

See MethodRouter::get for an example.

pub fn trace<H, T>(self, handler: H) -> Self where
    H: Handler<T, B>,
    T: 'static, 

Chain an additional handler that will only accept TRACE requests.

See MethodRouter::get for an example.

pub fn into_make_service(self) -> IntoMakeService<Self>

Convert the handler into a MakeService.

This allows you to serve a single handler if you don’t need any routing:

use axum::{
    Server,
    handler::Handler,
    http::{Uri, Method},
    response::IntoResponse,
    routing::get,
};
use std::net::SocketAddr;

async fn handler(method: Method, uri: Uri, body: String) -> String {
    format!("received `{} {}` with body `{:?}`", method, uri, body)
}

let router = get(handler).post(handler);

Server::bind(&SocketAddr::from(([127, 0, 0, 1], 3000)))
    .serve(router.into_make_service())
    .await?;

pub fn into_make_service_with_connect_info<C>(
    self
) -> IntoMakeServiceWithConnectInfo<Self, C>

Convert the router into a MakeService which stores information about the incoming connection.

See Router::into_make_service_with_connect_info for more details.

use axum::{
    Server,
    handler::Handler,
    response::IntoResponse,
    extract::ConnectInfo,
    routing::get,
};
use std::net::SocketAddr;

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

let router = get(handler).post(handler);

Server::bind(&SocketAddr::from(([127, 0, 0, 1], 3000)))
    .serve(router.into_make_service_with_connect_info::<SocketAddr>())
    .await?;

impl<ReqBody, E> MethodRouter<ReqBody, E>

pub fn on_service<S, ResBody>(self, filter: MethodFilter, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Chain an additional service that will accept requests matching the given MethodFilter.

Example

use axum::{
    http::Request,
    Router,
    routing::{MethodFilter, on_service},
};
use http::Response;
use std::convert::Infallible;
use hyper::Body;

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

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

pub fn delete_service<S, ResBody>(self, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Chain an additional service that will only accept DELETE requests.

See MethodRouter::get_service for an example.

pub fn get_service<S, ResBody>(self, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Chain an additional service that will only accept GET requests.

Example

use axum::{
    http::Request,
    Router,
    routing::post_service,
};
use http::Response;
use std::convert::Infallible;
use hyper::Body;

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

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

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

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.

pub fn head_service<S, ResBody>(self, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Chain an additional service that will only accept HEAD requests.

See MethodRouter::get_service for an example.

pub fn options_service<S, ResBody>(self, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Chain an additional service that will only accept OPTIONS requests.

See MethodRouter::get_service for an example.

pub fn patch_service<S, ResBody>(self, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Chain an additional service that will only accept PATCH requests.

See MethodRouter::get_service for an example.

pub fn post_service<S, ResBody>(self, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Chain an additional service that will only accept POST requests.

See MethodRouter::get_service for an example.

pub fn put_service<S, ResBody>(self, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Chain an additional service that will only accept PUT requests.

See MethodRouter::get_service for an example.

pub fn trace_service<S, ResBody>(self, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Chain an additional service that will only accept TRACE requests.

See MethodRouter::get_service for an example.

pub fn fallback<S, ResBody>(self, svc: S) -> Self where
    S: Service<Request<ReqBody>, Response = Response<ResBody>, Error = E> + Clone + Send + 'static,
    S::Future: Send + 'static,
    ResBody: HttpBody<Data = Bytes> + Send + 'static,
    ResBody::Error: Into<BoxError>, 

Add a fallback service to the router.

This service will be called if no routes matches the incoming request.

use axum::{
    Router,
    routing::get,
    handler::Handler,
    response::IntoResponse,
    http::{StatusCode, Method, Uri},
};

let handler = get(|| async {}).fallback(fallback.into_service());

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

async fn fallback(method: Method, uri: Uri) -> (StatusCode, String) {
    (StatusCode::NOT_FOUND, format!("`{}` not allowed for {}", method, uri))
}

When used with MethodRouter::merge

Two routers that both have a fallback cannot be merged. Doing so results in a panic:

use axum::{
    routing::{get, post},
    handler::Handler,
    response::IntoResponse,
    http::{StatusCode, Uri},
};

let one = get(|| async {})
    .fallback(fallback_one.into_service());

let two = post(|| async {})
    .fallback(fallback_two.into_service());

let method_route = one.merge(two);

async fn fallback_one() -> impl IntoResponse { /* ... */ }
async fn fallback_two() -> impl IntoResponse { /* ... */ }

Setting the Allow header

By default MethodRouter will set the Allow header when returning 405 Method Not Allowed. This is also done when the fallback is used unless the response generated by the fallback already sets the Allow header.

This means if you use fallback to accept additional methods, you should make sure you set the Allow header correctly.

pub fn layer<L, NewReqBody, NewResBody, NewError>(
    self,
    layer: L
) -> MethodRouter<NewReqBody, NewError> where
    L: Layer<Route<ReqBody, E>>,
    L::Service: Service<Request<NewReqBody>, Response = Response<NewResBody>, Error = NewError> + Clone + Send + 'static,
    <L::Service as Service<Request<NewReqBody>>>::Future: Send + 'static,
    NewResBody: HttpBody<Data = Bytes> + Send + 'static,
    NewResBody::Error: Into<BoxError>, 

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.

Works similarly to Router::layer. See that method for more details.

Example

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

async fn hander() {}

let app = Router::new().route(
    "/",
    // All requests to `GET /` will be sent through `ConcurrencyLimitLayer`
    get(hander).layer(ConcurrencyLimitLayer::new(64)),
);

pub fn route_layer<L, NewResBody>(self, layer: L) -> MethodRouter<ReqBody, E> where
    L: Layer<Route<ReqBody, E>>,
    L::Service: Service<Request<ReqBody>, Response = Response<NewResBody>, Error = E> + Clone + Send + 'static,
    <L::Service as Service<Request<ReqBody>>>::Future: Send + 'static,
    NewResBody: HttpBody<Data = Bytes> + Send + 'static,
    NewResBody::Error: Into<BoxError>, 

Apply a tower::Layer to the router that will only run if the request matches a route.

This works similarly to MethodRouter::layer except the middleware will only run if the request matches a route. This is useful for middleware that return early (such as authorization) which might otherwise convert a 405 Method Not Allowed into a 401 Unauthorized.

Example

use axum::{
    routing::get,
    Router,
};
use tower_http::auth::RequireAuthorizationLayer;

let app = Router::new().route(
    "/foo",
    get(|| async {})
        .route_layer(RequireAuthorizationLayer::bearer("password"))
);

// `GET /foo` with a valid token will receive `200 OK`
// `GET /foo` with a invalid token will receive `401 Unauthorized`
// `POST /FOO` with a invalid token will receive `405 Method Not Allowed`

pub fn merge(self, other: MethodRouter<ReqBody, E>) -> Self

Merge two routers into one.

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

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 /

pub fn handle_error<F, T>(self, f: F) -> MethodRouter<ReqBody, Infallible> where
    F: Clone + Send + 'static,
    HandleError<Route<ReqBody, E>, F, T>: Service<Request<ReqBody>, Response = Response, Error = Infallible>,
    <HandleError<Route<ReqBody, E>, F, T> as Service<Request<ReqBody>>>::Future: Send,
    T: 'static,
    E: 'static,
    ReqBody: 'static, 

Apply a HandleErrorLayer.

This is a convenience method for doing self.layer(HandleErrorLayer::new(f)).

Trait Implementations

impl<B, E> Clone for MethodRouter<B, E>

fn clone(&self) -> Self

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<B, E> Debug for MethodRouter<B, E>

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl<B, E> Default for MethodRouter<B, E> where
    B: Send + 'static, 

fn default() -> Self

Returns the “default value” for a type.

impl<B, E> Service<Request<B>> for MethodRouter<B, E> where
    B: HttpBody, 

type Response = Response<UnsyncBoxBody<Bytes, Error>>

Responses given by the service.

type Error = E

Errors produced by the service.

type Future = RouteFuture<B, E>

The future response value.

fn poll_ready(&mut self, _cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>

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

fn call(&mut self, req: Request<B>) -> Self::Future

Process the request and return the response asynchronously.