Tower Service and Layer — HTTP middleware chains with hyper

Contents

  1. 1. A bare handler
  2. 2. Service trait
  3. 3. A Logger middleware
  4. 4. Layer trait
  5. 5. hyper’s Service trait

When people talk about Rust HTTP middleware, Tower comes up fast.

Tower is protocol-agnostic middleware plumbing; Service and Layer are how you stack Logger, timeout, and handler layers.

A bare handler

Start from hyper’s hello-world handler:

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
use http_body_util::Full;
use hyper::{
body::{Bytes, Incoming},
server::conn::http1,
Request, Response,
};
use hyper_util::rt::TokioIo;
use std::{convert::Infallible, net::SocketAddr};
use tokio::net::TcpListener;

async fn handler(_: Request<Incoming>) -> Result<Response<Full<Bytes>>, Infallible> {
Ok(Response::new(Full::new(Bytes::from("Hello, World!"))))
}
#[tokio::main]
async fn main() -> Result<(), Box<dyn std::error::Error + Send + Sync>> {
let addr = SocketAddr::from(([127, 0, 0, 1], 3000));
let listener = TcpListener::bind(addr).await?;
loop {
let (stream, _) = listener.accept().await?;
let io = TokioIo::new(stream);
tokio::spawn(async move {
// the handler becomes a Service here
let svc = hyper::service::service_fn(handler);
if let Err(err) = http1::Builder::new().serve_connection(io, svc).await {
eprintln!("server error: {}", err);
}
});
}
}

service_fn turns the async fn into something that implements Service—what the server actually calls. That’s the hook middleware wraps.

After hyper v1, this Service is not literally tower’s trait, but the shape matches. We’ll contrast the interfaces later.

To add logging and a five-second timeout around the handler:

tower-service

1
2
3
4
5
6
7
8
let svc = hyper::service::service_fn(handler);
// two layer middlewares
let svc = ServiceBuilder::new()
.layer_fn(Logger::new)
.layer_fn(|s| Timeout::new(s, std::time::Duration::from_secs(5)))
.service(svc);
// ignore the adapter below for now — covered later
// let svc = TowerToHyperService::new(svc);

Service trait

Each middleware is another link in a chain: handle side effects, then delegate inward.

Tower’s Service:

1
2
3
4
5
6
7
8
9
pub trait Service<Request> {
type Response;
type Error;
type Future: Future<Output = Result<Self::Response, Self::Error>>;
// whether a call is allowed now
fn poll_ready(&mut self, cx: &mut Context<'_>) -> Poll<Result<(), Self::Error>>;
// handle the request
fn call(&mut self, req: Request) -> Self::Future;
}

poll_ready gates call. call returns a Future so slow work doesn’t block the caller’s ability to accept other requests.

Why Future instead of async fn in the trait? Historical—async in traits wasn’t stable yet. Since Rust 1.75 you could write:

1
2
3
4
5
trait Service<Request> {
type Response;
type Error;
async fn call(&mut self, req: Request) -> Result<Self::Response, Self::Error>;
}

A Logger middleware

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
use tower::Service;

#[derive(Debug, Clone)]
pub struct Logger<S> {
inner: S,
}
impl<S> Logger<S> {
pub fn new(inner: S) -> Self {
Logger { inner }
}
}
type Req = hyper::Request<Incoming>;
impl<S> Service<Req> for Logger<S>
where
S: Service<Req> + Clone,
{
// Logger wraps another Service; response/error types pass through
type Response = S::Response;
type Error = S::Error;
type Future = S::Future;

fn poll_ready(
&mut self,
cx: &mut std::task::Context<'_>,
) -> std::task::Poll<Result<(), Self::Error>> {
// no extra readiness logic
self.inner.poll_ready(cx)
}

fn call(&mut self, req: Req) -> Self::Future {
println!("processing request: {} {}", req.method(), req.uri().path());
// delegate to the inner Service
self.inner.call(req)
}
}

Wire it manually:

1
let svc = Logger::new(svc);

Then timeout:

1
let svc = Timeout::new(svc, std::time::Duration::from_secs(5));

That’s awkward—last wrapped runs first—and not chain-friendly. Layer fixes ordering and ergonomics.

Layer trait

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

Implement it for Logger:

1
2
3
4
5
6
impl<S> Layer<S> for Logger<S> {
type Service = Logger<S>;
fn layer(&self, inner: S) -> Self::Service {
Logger { inner }
}
}

Then build in call order:

1
2
3
4
tower::ServiceBuilder::new()
.layer(LoggerLayer)
.layer_fn(|s| Timeout::new(s, std::time::Duration::from_secs(5)))
.service(svc);

layer_fn adapts closures into Layer. Middleware runs in the same order you .layer() it.

hyper’s Service trait

Hyper used to depend on tower’s Service. Before v1 stabilized, it switched to its own trait:

  • tower wasn’t stable yet
  • hyper wanted a thinner surface: drop poll_ready, and take &self in call (shared state via Arc<Mutex<_>> if you need mutation)
1
2
3
4
5
6
7
pub trait Service<Request> {
type Response;
type Error;
type Future: Future<Output = Result<Self::Response, Self::Error>>;

fn call(&self, req: Request) -> Self::Future;
}

Reusing tower middleware (e.g. Timeout) against hyper often needs an adapter:

1
let svc = TowerToHyperService::new(svc);

Frameworks built on hyper—Axum, Actix Web, and others—also integrate tower, so middleware written once tends to travel.

Tower’s Service/Layer split looks obvious in hindsight; getting Future-returning call right took real design work. Tokio’s write-up is worth it: Inventing the Service trait.

For a live build-through: David Pedersen’s Tower deep dive (search “Tower deep dive” on Bilibili if YouTube is blocked).

Questions? Leave a comment below or email: newbvirgil@gmail.com