Skip to content
Tutorials Center
My learning

Topics

Lesson 22 of 38 ยท Async, Tokio and Tower

Tower Services and Layers

Learn the Tower Service and Layer traits that power Axum middleware, how ServiceBuilder orders layers, and how tower-http adds tracing, CORS, compression and timeouts, with a runnable stand-in.

Axum does not invent its own middleware system. It is built on Tower, a small library of two traits, Service and Layer, that describe "something that turns a request into a response" and "something that wraps one service in another". Every Axum Router is a Tower service, every handler is wrapped into one, and the large tower-http crate offers ready-made layers for logging, compression, CORS and timeouts.

If you understand these two traits you understand every middleware you will ever install. This lesson shows them in real code (read-only) and then rebuilds the idea in plain Rust you can run, because the Tower crates are not available on this site's runner.

The Service trait

Rust
// Simplified from the tower crate.
pub trait Service<Request> {
    type Response;
    type Error;
    type Future: Future<Output = Result<Self::Response, Self::Error>>;

    fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
    fn call(&mut self, req: Request) -> Self::Future;
}

Two methods: poll_ready asks "can you accept a request right now?" (this is how back pressure and concurrency limits work), and call takes the request and returns a future of the response. A service is generic over the request type, so the same abstraction covers HTTP, gRPC or any protocol. In Axum the request type is http::Request<Body> and the response is http::Response<Body>.

The Layer trait

Rust
pub trait Layer<S> {
    type Service;
    fn layer(&self, inner: S) -> Self::Service;
}

A layer is a service factory: give it an inner service and it hands back a new service that wraps it. A timeout layer returns a Timeout<S> which calls inner.call(req) but races it with a timer. Because the output is again a service, layers stack like Russian dolls.

Rust Services and layers, rebuilt (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Notice the call order in the output: the outer layer sees the request first and the response last. The AuthLayer can answer on its own without ever calling the handler. That is exactly how Axum's from_fn middleware and tower_http::auth work.

ServiceBuilder and ordering

Writing A.layer(B.layer(C.layer(handler))) gets unreadable. tower::ServiceBuilder reads top to bottom:

Rust
// Real Axum code: read-only.
use axum::{routing::get, Router};
use std::time::Duration;
use tower::ServiceBuilder;
use tower_http::{compression::CompressionLayer, timeout::TimeoutLayer, trace::TraceLayer};

let app = Router::new()
    .route("/", get(|| async { "hi" }))
    .layer(
        ServiceBuilder::new()
            .layer(TraceLayer::new_for_http())          // runs first
            .layer(TimeoutLayer::new(Duration::from_secs(10)))
            .layer(CompressionLayer::new()),            // runs last, closest to the handler
    );

With ServiceBuilder the first layer listed is the outermost: it sees requests first. With repeated Router::layer calls the last call is outermost, a classic source of confusion. Prefer one ServiceBuilder so the order reads naturally.

The ordering rule is easy to check with plain closures. Each wrapper below prints on the way in and on the way out:

Rust Layer order: outermost sees the request first (stand-in)

Press Run (or Ctrl + Enter) to see the result here.

Program input ยท what you'd type while the program runs

Type the answers before you press Run, one per line. Each time the program reads a line (with io::stdin().read_line()), it gets the next line from this box.

Router::layer vs route_layer

Router::layer wraps every route, including the fallback (404). route_layer only wraps matched routes, so a request to an unknown path skips it. Use route_layer for authentication so unknown URLs get 404 rather than 401.

Handy tower-http layers

Layer Purpose
TraceLayer structured request/response logs via tracing
CorsLayer cross-origin headers for browser clients
CompressionLayer gzip, brotli, zstd bodies
TimeoutLayer return 408 when a request takes too long
RequestBodyLimitLayer reject huge uploads early
ServeDir static files (a service, not a layer)
SetResponseHeaderLayer add security headers

Writing your own with from_fn

You rarely implement Service by hand. For app-specific middleware, axum::middleware::from_fn turns an async function into a layer. The middleware lessons from earlier in this course cover it in detail; below is the shape for comparison with the stand-in.

Rust
use axum::{extract::Request, middleware::Next, response::Response};

async fn log_requests(req: Request, next: Next) -> Response {
    println!("-> {}", req.uri());
    let res = next.run(req).await;
    println!("<- {}", res.status());
    res
}
// app.layer(axum::middleware::from_fn(log_requests))

next.run(req) is the inner.call(req) of the stand-in. Return early without calling it and you have short-circuited the chain.

Check your understanding

Quick check ยท 4 questions

of 4 answered You scored / 4 ยท perfect!

  1. 1. What is a Tower Layer?

    Layer::layer takes an inner service and returns a new service that wraps it, so layers can be stacked.
  2. 2. In ServiceBuilder::new().layer(A).layer(B), which layer sees the request first?

    ServiceBuilder lists layers from outermost to innermost, so A runs first on the way in.
  3. 3. Why use route_layer for an auth middleware?

    route_layer only wraps routes that exist. The fallback handler is not wrapped, so a missing page stays a plain 404.
  4. 4. What does poll_ready in Service enable?

    Concurrency limits and rate limits use poll_ready to delay callers until capacity is available.

Summary

  • Tower models everything as a Service (request to response) and a Layer (service wrapper).
  • Axum routers, handlers and middleware are all Tower services.
  • ServiceBuilder lists layers outermost first; repeated .layer() calls do the opposite.
  • tower-http supplies tracing, CORS, compression, timeouts and body limits.
  • from_fn is the easy way to write your own layer.

Next: Graceful Shutdown and Timeouts