Struct axum::routing::method_routing::MethodRouter

source ·
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§

source§

impl<S> MethodRouter<S, Infallible>
where S: Clone,

source

pub fn on<H, T>(self, filter: MethodFilter, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + '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));
source

pub fn delete<H, T>(self, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + 'static,

Chain an additional handler that will only accept DELETE requests.

See MethodRouter::get for an example.

source

pub fn get<H, T>(self, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + '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 `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.

source

pub fn head<H, T>(self, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + 'static,

Chain an additional handler that will only accept HEAD requests.

See MethodRouter::get for an example.

source

pub fn options<H, T>(self, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + 'static,

Chain an additional handler that will only accept OPTIONS requests.

See MethodRouter::get for an example.

source

pub fn patch<H, T>(self, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + 'static,

Chain an additional handler that will only accept PATCH requests.

See MethodRouter::get for an example.

source

pub fn post<H, T>(self, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + 'static,

Chain an additional handler that will only accept POST requests.

See MethodRouter::get for an example.

source

pub fn put<H, T>(self, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + 'static,

Chain an additional handler that will only accept PUT requests.

See MethodRouter::get for an example.

source

pub fn trace<H, T>(self, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + 'static,

Chain an additional handler that will only accept TRACE requests.

See MethodRouter::get for an example.

source

pub fn fallback<H, T>(self, handler: H) -> Self
where H: Handler<T, S>, T: 'static, S: Send + Sync + 'static,

Add a fallback Handler to the router.

source§

impl MethodRouter<(), Infallible>

source

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

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();
source

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::{
    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();
source§

impl<S, E> MethodRouter<S, E>
where S: Clone,

source

pub fn new() -> Self

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

source

pub fn with_state<S2>(self, state: S) -> MethodRouter<S2, E>

Provide the state for the router.

source

pub fn on_service<T>(self, filter: MethodFilter, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

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

pub fn delete_service<T>(self, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

Chain an additional service that will only accept DELETE requests.

See MethodRouter::get_service for an example.

source

pub fn get_service<T>(self, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

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.

source

pub fn head_service<T>(self, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

Chain an additional service that will only accept HEAD requests.

See MethodRouter::get_service for an example.

source

pub fn options_service<T>(self, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

Chain an additional service that will only accept OPTIONS requests.

See MethodRouter::get_service for an example.

source

pub fn patch_service<T>(self, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

Chain an additional service that will only accept PATCH requests.

See MethodRouter::get_service for an example.

source

pub fn post_service<T>(self, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

Chain an additional service that will only accept POST requests.

See MethodRouter::get_service for an example.

source

pub fn put_service<T>(self, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

Chain an additional service that will only accept PUT requests.

See MethodRouter::get_service for an example.

source

pub fn trace_service<T>(self, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

Chain an additional service that will only accept TRACE requests.

See MethodRouter::get_service for an example.

source

pub fn fallback_service<T>(self, svc: T) -> Self
where T: Service<Request, Error = E> + Clone + Send + 'static, T::Response: IntoResponse + 'static, T::Future: Send + 'static,

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.

source

pub fn layer<L, NewError>(self, layer: L) -> MethodRouter<S, NewError>
where L: Layer<Route<E>> + Clone + Send + 'static, L::Service: Service<Request> + Clone + Send + 'static, <L::Service as Service<Request>>::Response: IntoResponse + 'static, <L::Service as Service<Request>>::Error: Into<NewError> + 'static, <L::Service as Service<Request>>::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)),
);
source

pub fn route_layer<L>(self, layer: L) -> MethodRouter<S, E>
where L: Layer<Route<E>> + Clone + Send + 'static, L::Service: Service<Request, Error = E> + Clone + Send + 'static, <L::Service as Service<Request>>::Response: IntoResponse + 'static, <L::Service as Service<Request>>::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`
source

pub fn merge(self, other: MethodRouter<S, 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 /
source

pub fn handle_error<F, T>(self, f: F) -> MethodRouter<S, Infallible>
where F: Clone + Send + Sync + 'static, HandleError<Route<E>, F, T>: Service<Request, Error = Infallible>, <HandleError<Route<E>, F, T> as Service<Request>>::Future: Send, <HandleError<Route<E>, F, T> as Service<Request>>::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§

source§

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

source§

fn clone(&self) -> Self

Returns a copy of the value. Read more
1.0.0 · source§

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

Performs copy-assignment from source. Read more
source§

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

source§

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

Formats the value using the given formatter. Read more
source§

impl<S, E> Default for MethodRouter<S, E>
where S: Clone,

source§

fn default() -> Self

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

impl<S> Handler<(), S> for MethodRouter<S>
where S: Clone + 'static,

source§

type Future = InfallibleRouteFuture

The type of future calling this handler returns.
source§

fn call(self, req: Request, state: S) -> Self::Future

Call the handler with the given request.
source§

fn layer<L>(self, layer: L) -> Layered<L, Self, T, S>
where L: Layer<HandlerService<Self, T, S>> + Clone, L::Service: Service<Request>,

Apply a tower::Layer to the handler. Read more
source§

fn with_state(self, state: S) -> HandlerService<Self, T, S>

Convert the handler into a Service by providing the state
source§

impl Service<IncomingStream<'_>> for MethodRouter<()>

source§

type Response = MethodRouter

Responses given by the service.
source§

type Error = Infallible

Errors produced by the service.
source§

type Future = Ready<Result<<MethodRouter as Service<IncomingStream<'_>>>::Response, <MethodRouter as Service<IncomingStream<'_>>>::Error>>

The future response value.
source§

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

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

fn call(&mut self, _req: IncomingStream<'_>) -> Self::Future

Process the request and return the response asynchronously. Read more
source§

impl<B, E> Service<Request<B>> for MethodRouter<(), E>
where B: HttpBody<Data = Bytes> + Send + 'static, B::Error: Into<BoxError>,

source§

type Response = Response<Body>

Responses given by the service.
source§

type Error = E

Errors produced by the service.
source§

type Future = RouteFuture<E>

The future response value.
source§

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

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

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

Process the request and return the response asynchronously. Read more

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> Any for T
where T: 'static + ?Sized,

source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
source§

impl<T> Borrow<T> for T
where T: ?Sized,

source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
source§

impl<T> CloneToUninit for T
where T: Clone,

source§

unsafe fn clone_to_uninit(&self, dst: *mut T)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dst. Read more
source§

impl<T> From<T> for T

source§

fn from(t: T) -> T

Returns the argument unchanged.

source§

impl<T> FromRef<T> for T
where T: Clone,

source§

fn from_ref(input: &T) -> T

Converts to this type from a reference to the input type.
source§

impl<H, T> HandlerWithoutStateExt<T> for H
where H: Handler<T, ()>,

source§

fn into_service(self) -> HandlerService<H, T, ()>

Convert the handler into a Service and no state.
source§

fn into_make_service(self) -> IntoMakeService<HandlerService<H, T, ()>>

Convert the handler into a MakeService and no state. Read more
source§

fn into_make_service_with_connect_info<C>( self, ) -> IntoMakeServiceWithConnectInfo<HandlerService<H, T, ()>, C>

Convert the handler into a MakeService which stores information about the incoming connection and has no state. Read more
source§

impl<T> Instrument for T

source§

fn instrument(self, span: Span) -> Instrumented<Self>

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

fn in_current_span(self) -> Instrumented<Self>

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

impl<T, U> Into<U> for T
where U: From<T>,

source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

source§

impl<M, S, Target, Request> MakeService<Target, Request> for M
where M: Service<Target, Response = S>, S: Service<Request>,

source§

type Response = <S as Service<Request>>::Response

Responses given by the service
source§

type Error = <S as Service<Request>>::Error

Errors produced by the service
source§

type Service = S

The Service value created by this factory
source§

type MakeError = <M as Service<Target>>::Error

Errors produced while building a service.
source§

type Future = <M as Service<Target>>::Future

The future of the Service instance.
source§

fn poll_ready( &mut self, cx: &mut Context<'_>, ) -> Poll<Result<(), <M as MakeService<Target, Request>>::MakeError>>

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

fn make_service( &mut self, target: Target, ) -> <M as MakeService<Target, Request>>::Future

Create and return a new service value asynchronously.
source§

fn into_service(self) -> IntoService<Self, Request>
where Self: Sized,

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

fn as_service(&mut self) -> AsService<'_, Self, Request>
where Self: Sized,

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

impl<S, R> ServiceExt<R> for S
where S: Service<R>,

source§

fn into_make_service(self) -> IntoMakeService<S>

Convert this service into a MakeService, that is a Service whose response is another service. Read more
source§

fn into_make_service_with_connect_info<C>( self, ) -> IntoMakeServiceWithConnectInfo<S, C>

Convert this service into a MakeService, that will store C’s associated ConnectInfo in a request extension such that ConnectInfo can extract it. Read more
source§

fn handle_error<F, T>(self, f: F) -> HandleError<Self, F, T>

Convert this service into a HandleError, that will handle errors by converting them into responses. Read more
source§

impl<T, Request> ServiceExt<Request> for T
where T: Service<Request> + ?Sized,

source§

fn ready(&mut self) -> Ready<'_, Self, Request>
where Self: Sized,

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

fn ready_oneshot(self) -> ReadyOneshot<Self, Request>
where Self: Sized,

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

fn oneshot(self, req: Request) -> Oneshot<Self, Request>
where Self: Sized,

Consume this Service, calling it with the provided request once it is ready.
source§

fn call_all<S>(self, reqs: S) -> CallAll<Self, S>
where Self: Sized, S: Stream<Item = Request>,

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

fn and_then<F>(self, f: F) -> AndThen<Self, F>
where Self: Sized, F: Clone,

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

fn map_response<F, Response>(self, f: F) -> MapResponse<Self, F>
where Self: Sized, F: FnOnce(Self::Response) -> Response + Clone,

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

fn map_err<F, Error>(self, f: F) -> MapErr<Self, F>
where Self: Sized, F: FnOnce(Self::Error) -> Error + Clone,

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

fn map_result<F, Response, Error>(self, f: F) -> MapResult<Self, F>
where Self: Sized, Error: From<Self::Error>, F: FnOnce(Result<Self::Response, Self::Error>) -> Result<Response, Error> + Clone,

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
source§

fn map_request<F, NewRequest>(self, f: F) -> MapRequest<Self, F>
where Self: Sized, F: FnMut(NewRequest) -> Request,

Composes a function in front of the service. Read more
source§

fn then<F, Response, Error, Fut>(self, f: F) -> Then<Self, F>
where Self: Sized, Error: From<Self::Error>, F: FnOnce(Result<Self::Response, Self::Error>) -> Fut + Clone, Fut: Future<Output = Result<Response, Error>>,

Composes an asynchronous function after this service. Read more
source§

fn map_future<F, Fut, Response, Error>(self, f: F) -> MapFuture<Self, F>
where Self: Sized, F: FnMut(Self::Future) -> Fut, Error: From<Self::Error>, Fut: Future<Output = Result<Response, Error>>,

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

fn boxed(self) -> BoxService<Request, Self::Response, Self::Error>
where Self: Sized + Send + 'static, Self::Future: Send + 'static,

Convert the service into a Service + Send trait object. Read more
source§

fn boxed_clone(self) -> BoxCloneService<Request, Self::Response, Self::Error>
where Self: Sized + Clone + Send + 'static, Self::Future: Send + 'static,

Convert the service into a Service + Clone + Send trait object. Read more
source§

impl<T> ToOwned for T
where T: Clone,

source§

type Owned = T

The resulting type after obtaining ownership.
source§

fn to_owned(&self) -> T

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

fn clone_into(&self, target: &mut T)

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

impl<T, U> TryFrom<U> for T
where U: Into<T>,

source§

type Error = Infallible

The type returned in the event of a conversion error.
source§

fn try_from(value: U) -> Result<T, <T as TryFrom<U>>::Error>

Performs the conversion.
source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.
source§

impl<T> WithSubscriber for T

source§

fn with_subscriber<S>(self, subscriber: S) -> WithDispatch<Self>
where S: Into<Dispatch>,

Attaches the provided Subscriber to this type, returning a WithDispatch wrapper. Read more
source§

fn with_current_subscriber(self) -> WithDispatch<Self>

Attaches the current default Subscriber to this type, returning a WithDispatch wrapper. Read more