Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Layers

Two places take tower layers. The rustdoc of Server::operation_layer compares them:

Adds a tower layer between routing and the operations. It goes inside the layers added before. The first one added is the outermost as with the ServiceBuilder of tower. Pass one ServiceBuilder to read the order top to bottom.

A layer here and one on the axum Router that into_axum returns differ:

  • An operation_layer runs once routing found the operation and its credentials passed. Its extensions hold the operation, the credentials and, after authenticate, the principal. Its errors go out in the error schema of the description. It fits per-principal limits, permissions, signatures and timeouts.
  • An axum Router::layer runs on every request, also to unknown paths. It knows no operation yet, and its errors go out with the body that it writes. It fits CORS, compression and request IDs.

Inside

Layers inside the server answer in the error schema. Timeouts, load shedding and concurrency limits answer 503:

/// Limits that answer in the description's error schema: a `503` once a request takes too long or too many run.
fn limited() -> axum::Router {
    api::Server::new(Catalog::default())
        .operation_layer(tower::timeout::TimeoutLayer::new(Duration::from_secs(10)))
        .operation_layer(tower::load_shed::LoadShedLayer::new())
        .operation_layer(tower::limit::ConcurrencyLimitLayer::new(64))
        .into_axum()
}

Rate limits

OpenAPI cannot express a rate limit. Enforce one with tower’s AsyncFilterLayer. It runs before the body is read. The request’s extensions hold the operation and, after authenticate, the principal. An ApiError it returns goes out in the error schema:

/// At most `limit` requests. A real limiter keys its count by principal and time window. It keeps it in the same way in
/// an `Arc` because the layer is cloned for every request.
fn rate_limited(limit: u32) -> axum::Router {
    let used = Arc::new(AtomicU32::new(0));
    api::Server::new(Catalog::default())
        .operation_layer(tower::filter::AsyncFilterLayer::new(move |req: api::Request| {
            let over = used.fetch_add(1, Ordering::Relaxed) >= limit;
            let refusal = api::ApiError::new(api::http::StatusCode::TOO_MANY_REQUESTS, "rate limit exceeded")
                .with_header(api::http::header::RETRY_AFTER, api::http::HeaderValue::from_static("60"));
            std::future::ready(if over { Err(refusal) } else { Ok(req) })
        }))
        .into_axum()
}

req.extensions().get::<api::Operation>() is the generated api::Operation: one variant per operation. Match on it to treat operations apart. Rejection::operation of error_response, Context::operation of a handler and the operation of the wide event are the same enum:

/// Writes cost more than reads: only `createProduct` is limited. The match lists every operation, so one added to the
/// description fails to compile here until you decide its limit.
fn writes_limited(limit: u32) -> axum::Router {
    let used = Arc::new(AtomicU32::new(0));
    api::Server::new(Catalog::default())
        .operation_layer(tower::filter::AsyncFilterLayer::new(move |req: api::Request| {
            let limited = match req.extensions().get::<api::Operation>() {
                Some(api::Operation::CreateProduct) => true,
                Some(api::Operation::ListProducts | api::Operation::GetProduct) | None => false,
            };
            let over = limited && used.fetch_add(1, Ordering::Relaxed) >= limit;
            std::future::ready(if over {
                Err(api::ApiError::new(api::http::StatusCode::TOO_MANY_REQUESTS, "too many writes"))
            } else {
                Ok(req)
            })
        }))
        .into_axum()
}

A layer for any API

A plain tower Layer fits any honig server. Its service takes honig::Request and names the operation with the MatchedOperation in the extensions:

/// A tower layer for any honig server: it counts the requests of each operation by its name. It is a plain
/// `tower::Layer` over `http` requests that reads the `MatchedOperation` that the server puts in the extensions.
#[derive(Clone, Default)]
struct CountByOperationLayer(Arc<std::sync::Mutex<std::collections::BTreeMap<&'static str, u32>>>);

impl<S> tower::Layer<S> for CountByOperationLayer {
    type Service = CountByOperation<S>;

    fn layer(&self, inner: S) -> CountByOperation<S> {
        CountByOperation { inner, counts: Arc::clone(&self.0) }
    }
}

#[derive(Clone)]
struct CountByOperation<S> {
    inner: S,
    counts: Arc<std::sync::Mutex<std::collections::BTreeMap<&'static str, u32>>>,
}

impl<S: tower::Service<honig::Request>> tower::Service<honig::Request> for CountByOperation<S> {
    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<(), S::Error>> {
        self.inner.poll_ready(cx)
    }

    fn call(&mut self, req: honig::Request) -> S::Future {
        if let Some(routed) = req.extensions().get::<honig::MatchedOperation>() {
            *self.counts.lock().unwrap().entry(routed.name()).or_default() += 1;
        }
        self.inner.call(req)
    }
}

Outside

tower-http layers go outside the server. A layer outside that answers on its own can render the description’s error schema with errors():

/// tower-http layers outside the router. A layer outside that answers on its own renders the error schema of the
/// description with `errors()`. Here it answers for a path that the description does not declare.
fn with_cors() -> axum::Router {
    let server = api::Server::new(Catalog::default());
    let errors = server.errors();
    server
        .into_axum()
        .fallback(move || {
            std::future::ready(errors.response(api::http::StatusCode::NOT_FOUND, "no such page").into_response())
        })
        .layer(tower_http::cors::CorsLayer::permissive())
}

Recipes puts layers outside and inside the server and authenticate in one stack. It also maps the errors of outside layers that fail with a timeout or a full queue.