pub struct MethodRouter<S = (), E = Infallible> { /* private fields */ }
Expand description
A Service
that accepts requests based on a MethodFilter
and
allows chaining additional handlers and services.
§When does MethodRouter
implement Service
?
Whether or not MethodRouter
implements Service
depends on the state type it requires.
use tower::Service;
use axum::{routing::get, extract::{State, Request}, body::Body};
// this `MethodRouter` doesn't require any state, i.e. the state is `()`,
let method_router = get(|| async {});
// and thus it implements `Service`
assert_service(method_router);
// this requires a `String` and doesn't implement `Service`
let method_router = get(|_: State<String>| async {});
// until you provide the `String` with `.with_state(...)`
let method_router_with_state = method_router.with_state(String::new());
// and then it implements `Service`
assert_service(method_router_with_state);
// helper to check that a value implements `Service`
fn assert_service<S>(service: S)
where
S: Service<Request>,
{}
Implementations§
§impl<S> MethodRouter<S>where
S: Clone,
impl<S> MethodRouter<S>where
S: Clone,
pub fn on<H, T>(self, filter: MethodFilter, handler: H) -> MethodRouter<S>
pub fn on<H, T>(self, filter: MethodFilter, handler: H) -> MethodRouter<S>
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) -> MethodRouter<S>
pub fn delete<H, T>(self, handler: H) -> MethodRouter<S>
Chain an additional handler that will only accept DELETE
requests.
See MethodRouter::get
for an example.
pub fn get<H, T>(self, handler: H) -> MethodRouter<S>
pub fn get<H, T>(self, handler: H) -> MethodRouter<S>
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 `POST /` will go to `handler` and `GET /` 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) -> MethodRouter<S>
pub fn head<H, T>(self, handler: H) -> MethodRouter<S>
Chain an additional handler that will only accept HEAD
requests.
See MethodRouter::get
for an example.
pub fn options<H, T>(self, handler: H) -> MethodRouter<S>
pub fn options<H, T>(self, handler: H) -> MethodRouter<S>
Chain an additional handler that will only accept OPTIONS
requests.
See MethodRouter::get
for an example.
pub fn patch<H, T>(self, handler: H) -> MethodRouter<S>
pub fn patch<H, T>(self, handler: H) -> MethodRouter<S>
Chain an additional handler that will only accept PATCH
requests.
See MethodRouter::get
for an example.
pub fn post<H, T>(self, handler: H) -> MethodRouter<S>
pub fn post<H, T>(self, handler: H) -> MethodRouter<S>
Chain an additional handler that will only accept POST
requests.
See MethodRouter::get
for an example.
pub fn put<H, T>(self, handler: H) -> MethodRouter<S>
pub fn put<H, T>(self, handler: H) -> MethodRouter<S>
Chain an additional handler that will only accept PUT
requests.
See MethodRouter::get
for an example.
pub fn trace<H, T>(self, handler: H) -> MethodRouter<S>
pub fn trace<H, T>(self, handler: H) -> MethodRouter<S>
Chain an additional handler that will only accept TRACE
requests.
See MethodRouter::get
for an example.
§impl MethodRouter
impl MethodRouter
pub fn into_make_service(self) -> IntoMakeService<MethodRouter>
pub fn into_make_service(self) -> IntoMakeService<MethodRouter>
Convert the router into a MakeService
.
This allows you to serve a single MethodRouter
if you don’t need any
routing based on the path:
use axum::{
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 `{method} {uri}` with body `{body:?}`")
}
let router = get(handler).post(handler);
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
axum::serve(listener, router.into_make_service()).await.unwrap();
pub fn into_make_service_with_connect_info<C>(
self
) -> IntoMakeServiceWithConnectInfo<MethodRouter, C>
pub fn into_make_service_with_connect_info<C>( self ) -> IntoMakeServiceWithConnectInfo<MethodRouter, 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::{
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);
let listener = tokio::net::TcpListener::bind("0.0.0.0:3000").await.unwrap();
axum::serve(listener, router.into_make_service()).await.unwrap();
§impl<S, E> MethodRouter<S, E>where
S: Clone,
impl<S, E> MethodRouter<S, E>where
S: Clone,
pub fn new() -> MethodRouter<S, E>
pub fn new() -> MethodRouter<S, E>
Create a default MethodRouter
that will respond with 405 Method Not Allowed
to all
requests.
pub fn with_state<S2>(self, state: S) -> MethodRouter<S2, E>
pub fn with_state<S2>(self, state: S) -> MethodRouter<S2, E>
Provide the state for the router.
pub fn on_service<T>(self, filter: MethodFilter, svc: T) -> MethodRouter<S, E>
pub fn on_service<T>(self, filter: MethodFilter, svc: T) -> MethodRouter<S, E>
Chain an additional service that will accept requests matching the given
MethodFilter
.
§Example
use axum::{
extract::Request,
Router,
routing::{MethodFilter, on_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 `DELETE /` will go to `service`
let app = Router::new().route("/", on_service(MethodFilter::DELETE, service));
pub fn delete_service<T>(self, svc: T) -> MethodRouter<S, E>
pub fn delete_service<T>(self, svc: T) -> MethodRouter<S, E>
Chain an additional service that will only accept DELETE
requests.
See MethodRouter::get_service
for an example.
pub fn get_service<T>(self, svc: T) -> MethodRouter<S, E>
pub fn get_service<T>(self, svc: T) -> MethodRouter<S, E>
Chain an additional service that will only accept GET
requests.
§Example
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));
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<T>(self, svc: T) -> MethodRouter<S, E>
pub fn head_service<T>(self, svc: T) -> MethodRouter<S, E>
Chain an additional service that will only accept HEAD
requests.
See MethodRouter::get_service
for an example.
pub fn options_service<T>(self, svc: T) -> MethodRouter<S, E>
pub fn options_service<T>(self, svc: T) -> MethodRouter<S, E>
Chain an additional service that will only accept OPTIONS
requests.
See MethodRouter::get_service
for an example.
pub fn patch_service<T>(self, svc: T) -> MethodRouter<S, E>
pub fn patch_service<T>(self, svc: T) -> MethodRouter<S, E>
Chain an additional service that will only accept PATCH
requests.
See MethodRouter::get_service
for an example.
pub fn post_service<T>(self, svc: T) -> MethodRouter<S, E>
pub fn post_service<T>(self, svc: T) -> MethodRouter<S, E>
Chain an additional service that will only accept POST
requests.
See MethodRouter::get_service
for an example.
pub fn put_service<T>(self, svc: T) -> MethodRouter<S, E>
pub fn put_service<T>(self, svc: T) -> MethodRouter<S, E>
Chain an additional service that will only accept PUT
requests.
See MethodRouter::get_service
for an example.
pub fn trace_service<T>(self, svc: T) -> MethodRouter<S, E>
pub fn trace_service<T>(self, svc: T) -> MethodRouter<S, E>
Chain an additional service that will only accept TRACE
requests.
See MethodRouter::get_service
for an example.
pub fn fallback_service<T>(self, svc: T) -> MethodRouter<S, E>
pub fn fallback_service<T>(self, svc: T) -> MethodRouter<S, E>
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);
let app = Router::new().route("/", handler);
async fn fallback(method: Method, uri: Uri) -> (StatusCode, String) {
(StatusCode::NOT_FOUND, format!("`{method}` not allowed for {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);
let two = post(|| async {}).fallback(fallback_two);
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, NewError>(self, layer: L) -> MethodRouter<S, NewError>where
L: Layer<Route<E>> + Clone + Send + 'static,
<L as Layer<Route<E>>>::Service: Service<Request<Body>> + Clone + Send + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Response: IntoResponse + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Error: Into<NewError> + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Future: Send + 'static,
E: 'static,
S: 'static,
NewError: 'static,
pub fn layer<L, NewError>(self, layer: L) -> MethodRouter<S, NewError>where
L: Layer<Route<E>> + Clone + Send + 'static,
<L as Layer<Route<E>>>::Service: Service<Request<Body>> + Clone + Send + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Response: IntoResponse + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Error: Into<NewError> + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Future: Send + 'static,
E: 'static,
S: 'static,
NewError: 'static,
Apply a tower::Layer
to all routes in the router.
This can be used to add additional processing to a request for a group of routes.
Note that the middleware is only applied to existing routes. So you have to
first add your routes (and / or fallback) and then call layer
afterwards. Additional
routes added after layer
is called will not have the middleware added.
Works similarly to Router::layer
. See that method for
more details.
§Example
use axum::{routing::get, Router};
use tower::limit::ConcurrencyLimitLayer;
async fn handler() {}
let app = Router::new().route(
"/",
// All requests to `GET /` will be sent through `ConcurrencyLimitLayer`
get(handler).layer(ConcurrencyLimitLayer::new(64)),
);
pub fn route_layer<L>(self, layer: L) -> MethodRouter<S, E>where
L: Layer<Route<E>> + Clone + Send + 'static,
<L as Layer<Route<E>>>::Service: Service<Request<Body>, Error = E> + Clone + Send + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Response: IntoResponse + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Future: Send + 'static,
E: 'static,
S: 'static,
pub fn route_layer<L>(self, layer: L) -> MethodRouter<S, E>where
L: Layer<Route<E>> + Clone + Send + 'static,
<L as Layer<Route<E>>>::Service: Service<Request<Body>, Error = E> + Clone + Send + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Response: IntoResponse + 'static,
<<L as Layer<Route<E>>>::Service as Service<Request<Body>>>::Future: Send + 'static,
E: 'static,
S: 'static,
Apply a tower::Layer
to the router that will only run if the request matches
a route.
Note that the middleware is only applied to existing routes. So you have to
first add your routes (and / or fallback) and then call route_layer
afterwards. Additional routes added after route_layer
is called will not have
the middleware added.
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::validate_request::ValidateRequestHeaderLayer;
let app = Router::new().route(
"/foo",
get(|| async {})
.route_layer(ValidateRequestHeaderLayer::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<S, E>) -> MethodRouter<S, E>
pub fn merge(self, other: MethodRouter<S, E>) -> MethodRouter<S, E>
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<S>where
F: Clone + Send + Sync + 'static,
HandleError<Route<E>, F, T>: Service<Request<Body>, Error = Infallible>,
<HandleError<Route<E>, F, T> as Service<Request<Body>>>::Future: Send,
<HandleError<Route<E>, F, T> as Service<Request<Body>>>::Response: IntoResponse + Send,
T: 'static,
E: 'static,
S: 'static,
pub fn handle_error<F, T>(self, f: F) -> MethodRouter<S>where
F: Clone + Send + Sync + 'static,
HandleError<Route<E>, F, T>: Service<Request<Body>, Error = Infallible>,
<HandleError<Route<E>, F, T> as Service<Request<Body>>>::Future: Send,
<HandleError<Route<E>, F, T> as Service<Request<Body>>>::Response: IntoResponse + Send,
T: 'static,
E: 'static,
S: 'static,
Apply a HandleErrorLayer
.
This is a convenience method for doing self.layer(HandleErrorLayer::new(f))
.
Trait Implementations§
§impl<S> Handler<(), S> for MethodRouter<S>where
S: Clone + 'static,
impl<S> Handler<(), S> for MethodRouter<S>where
S: Clone + 'static,
§type Future = InfallibleRouteFuture
type Future = InfallibleRouteFuture
§fn call(
self,
req: Request<Body>,
state: S
) -> <MethodRouter<S> as Handler<(), S>>::Future
fn call( self, req: Request<Body>, state: S ) -> <MethodRouter<S> as Handler<(), S>>::Future
§fn layer<L>(self, layer: L) -> Layered<L, Self, T, S>where
L: Layer<HandlerService<Self, T, S>> + Clone,
<L as Layer<HandlerService<Self, T, S>>>::Service: Service<Request<Body>>,
fn layer<L>(self, layer: L) -> Layered<L, Self, T, S>where
L: Layer<HandlerService<Self, T, S>> + Clone,
<L as Layer<HandlerService<Self, T, S>>>::Service: Service<Request<Body>>,
tower::Layer
to the handler. Read more§fn with_state(self, state: S) -> HandlerService<Self, T, S>
fn with_state(self, state: S) -> HandlerService<Self, T, S>
Service
by providing the state§impl<S, E> Clone for MethodRouter<S, E>
impl<S, E> Clone for MethodRouter<S, E>
§fn clone(&self) -> MethodRouter<S, E>
fn clone(&self) -> MethodRouter<S, E>
1.0.0 · source§fn clone_from(&mut self, source: &Self)
fn clone_from(&mut self, source: &Self)
source
. Read more§impl<S, E> Debug for MethodRouter<S, E>
impl<S, E> Debug for MethodRouter<S, E>
§impl<S, E> Default for MethodRouter<S, E>where
S: Clone,
impl<S, E> Default for MethodRouter<S, E>where
S: Clone,
§fn default() -> MethodRouter<S, E>
fn default() -> MethodRouter<S, E>
§impl Service<IncomingStream<'_>> for MethodRouter
impl Service<IncomingStream<'_>> for MethodRouter
§type Response = MethodRouter
type Response = MethodRouter
§type Error = Infallible
type Error = Infallible
§type Future = Ready<Result<<MethodRouter as Service<IncomingStream<'_>>>::Response, <MethodRouter as Service<IncomingStream<'_>>>::Error>>
type Future = Ready<Result<<MethodRouter as Service<IncomingStream<'_>>>::Response, <MethodRouter as Service<IncomingStream<'_>>>::Error>>
§fn poll_ready(
&mut self,
_cx: &mut Context<'_>
) -> Poll<Result<(), <MethodRouter as Service<IncomingStream<'_>>>::Error>>
fn poll_ready( &mut self, _cx: &mut Context<'_> ) -> Poll<Result<(), <MethodRouter as Service<IncomingStream<'_>>>::Error>>
Poll::Ready(Ok(()))
when the service is able to process requests. Read more§fn call(
&mut self,
_req: IncomingStream<'_>
) -> <MethodRouter as Service<IncomingStream<'_>>>::Future
fn call( &mut self, _req: IncomingStream<'_> ) -> <MethodRouter as Service<IncomingStream<'_>>>::Future
§impl<B, E> Service<Request<B>> for MethodRouter<(), E>
impl<B, E> Service<Request<B>> for MethodRouter<(), E>
§type Future = RouteFuture<E>
type Future = RouteFuture<E>
Auto Trait Implementations§
impl<S = (), E = Infallible> !Freeze for MethodRouter<S, E>
impl<S, E> RefUnwindSafe for MethodRouter<S, E>
impl<S, E> Send for MethodRouter<S, E>
impl<S, E> Sync for MethodRouter<S, E>
impl<S, E> Unpin for MethodRouter<S, E>
impl<S, E> UnwindSafe for MethodRouter<S, E>
Blanket Implementations§
source§impl<T> BorrowMut<T> for Twhere
T: ?Sized,
impl<T> BorrowMut<T> for Twhere
T: ?Sized,
source§fn borrow_mut(&mut self) -> &mut T
fn borrow_mut(&mut self) -> &mut T
§impl<H, T> HandlerWithoutStateExt<T> for H
impl<H, T> HandlerWithoutStateExt<T> for H
§fn into_service(self) -> HandlerService<H, T, ()>
fn into_service(self) -> HandlerService<H, T, ()>
Service
and no state.§fn into_make_service(self) -> IntoMakeService<HandlerService<H, T, ()>>
fn into_make_service(self) -> IntoMakeService<HandlerService<H, T, ()>>
MakeService
and no state. Read more§fn into_make_service_with_connect_info<C>(
self
) -> IntoMakeServiceWithConnectInfo<HandlerService<H, T, ()>, C>
fn into_make_service_with_connect_info<C>( self ) -> IntoMakeServiceWithConnectInfo<HandlerService<H, T, ()>, C>
MakeService
which stores information
about the incoming connection and has no state. Read more§impl<T> Instrument for T
impl<T> Instrument for T
§fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
fn instrument(self, span: Span) -> Instrumented<Self> ⓘ
§impl<M, S, Target, Request> MakeService<Target, Request> for M
impl<M, S, Target, Request> MakeService<Target, Request> for M
§fn poll_ready(
&mut self,
cx: &mut Context<'_>
) -> Poll<Result<(), <M as MakeService<Target, Request>>::MakeError>>
fn poll_ready( &mut self, cx: &mut Context<'_> ) -> Poll<Result<(), <M as MakeService<Target, Request>>::MakeError>>
Poll::Ready
when the factory is able to create more services. Read more§fn make_service(
&mut self,
target: Target
) -> <M as MakeService<Target, Request>>::Future
fn make_service( &mut self, target: Target ) -> <M as MakeService<Target, Request>>::Future
§fn into_service(self) -> IntoService<Self, Request>where
Self: Sized,
fn into_service(self) -> IntoService<Self, Request>where
Self: Sized,
§fn as_service(&mut self) -> AsService<'_, Self, Request>where
Self: Sized,
fn as_service(&mut self) -> AsService<'_, Self, Request>where
Self: Sized,
§impl<S, R> ServiceExt<R> for Swhere
S: Service<R>,
impl<S, R> ServiceExt<R> for Swhere
S: Service<R>,
§fn into_make_service(self) -> IntoMakeService<S>
fn into_make_service(self) -> IntoMakeService<S>
MakeService
, that is a Service
whose
response is another service. Read more§fn into_make_service_with_connect_info<C>(
self
) -> IntoMakeServiceWithConnectInfo<S, C>
fn into_make_service_with_connect_info<C>( self ) -> IntoMakeServiceWithConnectInfo<S, C>
MakeService
, that will store C
’s
associated ConnectInfo
in a request extension such that ConnectInfo
can extract it. Read more§fn handle_error<F, T>(self, f: F) -> HandleError<Self, F, T>
fn handle_error<F, T>(self, f: F) -> HandleError<Self, F, T>
HandleError
, that will handle errors
by converting them into responses. Read more§impl<T, Request> ServiceExt<Request> for T
impl<T, Request> ServiceExt<Request> for T
§fn ready(&mut self) -> Ready<'_, Self, Request> ⓘwhere
Self: Sized,
fn ready(&mut self) -> Ready<'_, Self, Request> ⓘwhere
Self: Sized,
§fn ready_and(&mut self) -> Ready<'_, Self, Request> ⓘwhere
Self: Sized,
fn ready_and(&mut self) -> Ready<'_, Self, Request> ⓘwhere
Self: Sized,
ServiceExt::ready
method instead§fn ready_oneshot(self) -> ReadyOneshot<Self, Request> ⓘwhere
Self: Sized,
fn ready_oneshot(self) -> ReadyOneshot<Self, Request> ⓘwhere
Self: Sized,
§fn oneshot(self, req: Request) -> Oneshot<Self, Request> ⓘwhere
Self: Sized,
fn oneshot(self, req: Request) -> Oneshot<Self, Request> ⓘwhere
Self: Sized,
Service
, calling with the providing request once it is ready.§fn and_then<F>(self, f: F) -> AndThen<Self, F>
fn and_then<F>(self, f: F) -> AndThen<Self, F>
poll_ready
method. Read more§fn map_response<F, Response>(self, f: F) -> MapResponse<Self, F>
fn map_response<F, Response>(self, f: F) -> MapResponse<Self, F>
poll_ready
method. Read more§fn map_err<F, Error>(self, f: F) -> MapErr<Self, F>
fn map_err<F, Error>(self, f: F) -> MapErr<Self, F>
poll_ready
method. Read more§fn map_result<F, Response, Error>(self, f: F) -> MapResult<Self, F>
fn map_result<F, Response, Error>(self, f: F) -> MapResult<Self, F>
Result<Self::Response, Self::Error>
)
to a different value, regardless of whether the future succeeds or
fails. Read more