How does axum actually wire routes and handlers?

[nihalpasham]

Hi, new to web-dev, just started exploring axum.

question: I understand that a Router allows us to wire a given path to a supplied handler but how does axum perform the (actual) wiring under the hood?

In the example below, I have 2 handlers json_hello and json_bye that have been wired-up by a Router

let app = Router::new()
            .route("/hello/:name", get(json_hello));
            .route("/bye/:name", get(json_bye));

async fn json_hello(Path(name): Path<String>) -> impl IntoResponse {
    let greeting = name.as_str();
    let hello = String::from("Hello ");

    (StatusCode::OK, Json(json!({ "message": hello + greeting })))
}

async fn json_bye(Path(name): Path<String>) -> impl IntoResponse {
    let farewell = name.as_str();
    let hello = String::from("Bye ");

    (StatusCode::OK, Json(json!({ "message": hello + farewell })))
}

and axum provides handler implementations (that can take upto 16 arguments or extractors) that can be called via the .call method. I tried digging into the types (MethodRouter etc.) looking for where the .call actually gets called, but couldn't find it.

#[allow(non_snake_case)]
impl<F, Fut, B, Res, T1, T2> Handler<(T1, T2), B> for F
where
    F: FnOnce(T1, T2) -> Fut + Clone + Send + 'static,
    Fut: Future<Output = Res> + Send,
    B: Send + 'static,
    Res: IntoResponse,
    T1: FromRequest<B> + Send,
    T2: FromRequest<B> + Send,
{
    type Future = Pin<Box<dyn Future<Output = Response> + Send>>;
    fn call(self, req: Request<B>) -> Self::Future {
        Box::pin(async move {
            let mut req = RequestParts::new(req);
            let T1 = match T1::from_request(&mut req).await {
                Ok(value) => value,
                Err(rejection) => return rejection.into_response(),
            };
            let T2 = match T2::from_request(&mut req).await {
                Ok(value) => value,
                Err(rejection) => return rejection.into_response(),
            };
            let res = self(T1, T2).await;
            res.into_response()
        })
    }
}

So, any help in clearing this up would be great.

[davidpdrsn]

Great question!

I'm gonna talk about how it works in 0.6, things work similarly in 0.5.

• Router::route takes a path and a MethodRouter.
• The MethodRouter is is constructed via something like axum::routing::get.
• get, post, etc are all the same so they're defined in a macro here.
• That calls axum::routing::on which calls MethodRouter::on
• That calls MethodRouter::on_service but requires a service. Previously we've only received a H: Handler<T, S, B>. How the Handler trait works is a different question and somewhat orthogonal.
• So we convert the Handler into a Service with IntoServiceStateInExtension. That is why you never see Handler::call being called. Because we call it via IntoServiceStateInExtension::call.
• Then its a matter of seeing which HTTP methods the service should match and saving that inside the MethodRouter. That is done here.
• We now have a MethodRouter which we can call with a request and get a response or a 405 Method Not Allowed
• Then we're back in Router::route with our MethodRouter
• Router supports both any tower::Service but also has special handling for MethodRouter. That makes .route("/", get(_)).route("/", post(_)) work, which would otherwise create overlapping routes. So when you add a new route we check if there is already a MethodRouter there and if so we MethodRouter::merge them instead of panicking. That is done here.
• Router uses matchit internally to do the actual routing so its a matter of inserting the service to call into a matchit router.
• Then when Router receives a request via Service::call we look up the corresponding route in the matchit router and pass the request along.

Hopefully that makes things a bit more clear 😊 You're welcome to ask more questions.

[nihalpasham]

I assume the above apis are for 0.6

But I see 0.5.16 has similar types - MethodRouter::on_service_boxed_response_body replaced by MethodRouter::on_service and IntoService replaced by IntoServiceStateInExtension

The above now makes sense.

[davidpdrsn]

Yeah we made a bunch of changes for 0.6 to support type safe state. But the general flow of things is still the same.

[nihalpasham]

Cool, thank you for taking the time out to put together a rather nice explanation.

Just an observation: I guess a (somewhat) involved implementation is the cost of better ergonomics.

But for someone who has never worked on web stuff before, axum feels (actually kind of) intuitive. 👍

[davidpdrsn]

Thanks! Happy to hear. Making something simple and flexible is hard.

[nihalpasham]

• Router uses matchit internally to do the actual routing so its a matter of inserting the service to call into a matchit router.

just a quick clarification: routing is a 2 step process -right

• match it maps incoming requests (i.e. URL paths) to a RouteId, using a radix tree.
• and we use the RouteId as the key to a hashmap that holds the router's Route(s) (where the Route type is wrapper around the Service which in-turn wraps our async Handler(s)).