Middlewares — Pitfalls and solutions

A middleware (a "layer" in Tower) wraps the next service. The request goes through the layers from the outside to the inside, and the response goes back through them in the other direction.

A layer can:

Consequence: a layer can only use what more outer layers have prepared. CSRF reads the session: the session must be outside CSRF.

This pitfall caused a bug while building Runique: CSRF ended up outside the session. It looked for a token in a session that was not loaded yet, and rejected every POST request with a 403, without a clear message.

The bug is not always visible right away: if CSRF is disabled or bypassed in development, it can reach production without ever having been visible.

Rather than depend on writing order, Runique gives each middleware a fixed slot number. At build time, the layers are sorted by slot and applied in the right order, whatever order the developer configures them in.

Reading: a low slot is outer. The request goes through in increasing order:

Each position has a reason, written in the comment:

Technique: sorting by slot turns a rule the developer had to remember into a rule the framework enforces. It is the same idea as column types (a mistake becomes impossible) or the builder's typestate (course traits-avances).

CSRF protection relies on a secret token tied to the session, which each form must send back. The CSRF middleware must read this token to validate a POST request.

The slots fix Session(50) → SessionUpgrade(55) → Auth(57) → CSRF(60). CSRF is always active: there is no method to disable it globally.

The only planned exception is explicit and limited to specific paths, for entry points called by a third-party service that signs its requests:

RuniqueAppBuilder::new(config)
    .middleware(|m| {
        m.csrf_exempt(vec!["/webhook/stripe", "/webhook/github"])
    })

These routes must then check the service's signature themselves (in constant time): the exemption replaces one protection with another, it does not remove it.

Add an X-Response-Time header to every response.

use axum::{extract::Request, middleware::Next, response::Response};
use std::time::Instant;

// 1. An async function with from_fn (the simplest)
async fn response_time(req: Request, next: Next) -> Response {
    let start = Instant::now();
    let mut response = next.run(req).await;                // before: nothing; after: we modify the response
    let ms = start.elapsed().as_millis().to_string();
    if let Ok(v) = ms.parse() {
        response.headers_mut().insert("x-response-time", v);
    }
    response
}

let app = axum::Router::new()
    .route("/", axum::routing::get(|| async { "ok" }))
    .layer(axum::middleware::from_fn(response_time));

// 2. With shared state: from_fn_with_state
#[derive(Clone)]
struct AppState { prefix: &'static str }

async fn with_state(
    axum::extract::State(state): axum::extract::State<AppState>,
    req: Request,
    next: Next,
) -> Response {
    tracing::info!("{} {}", state.prefix, req.uri());
    next.run(req).await
}

// .layer(axum::middleware::from_fn_with_state(AppState { prefix: "web" }, with_state))

// 3. A ready-made tower-http layer
// .layer(tower_http::timeout::TimeoutLayer::new(Duration::from_secs(10)))

A request body is a stream: bytes arrive from the network and are consumed when read. There is no going back.

async fn handler(req: axum::extract::Request) {
    let body = axum::body::to_bytes(req.into_body(), 2 * 1024 * 1024).await;
    // req was consumed by into_body: there is no body left to read
}

The type system shows it: into_body(self) takes the request. Reading it again is impossible, it is a compile error.

If a middleware reads the body (to log, validate...), the handler receives an empty body, unless the body is rebuilt.

The body is read only once, by the Request extractor. This is why Request is always the last parameter of a handler: axum requires the extractor that consumes the body to come last.

The parsed data is kept in the request (request.prisme), and request.form("name") builds the form from it, without reading the stream again. Middlewares never touch the body; what they need goes through the extensions (section 5.3).

pub async fn login(request: Request) -> AppResult<Response> {
    let form: LoginForm = request.form("login");   // filled from the already parsed data
    // ...
}

Size limits are checked before and during this single read (Content-Length header, then a limit while reading: 2 MB for a form, RUNIQUE_MAX_UPLOAD_MB per file, RUNIQUE_MAX_BODY_MB for the whole request): a body that is too large is rejected with a 413 without having been loaded into memory.

On display (GET), filling ignores password fields: a password is never shown again in the page. On submission (POST, PUT, PATCH), request.form("name") fills them like the other fields.

add_value(name, value) sets a value from code (pre-filling, a column the visitor does not choose):

let mut form: LoginForm = request.form("login");
form.add_value("username", &value);

It is tempting to write only the POST handler. But the HTML form must first have been displayed: this is when the hidden CSRF token and the form name are inserted into the page.

// Only a POST: the page containing the form was never rendered by Runique,
// so the browser has neither a CSRF token nor a form name to send back.

The middlewares configured by the builder (session, CSRF, CSP, host validation...) apply to all routes. This is intended: a security protection with exceptions is a potential hole, and a forgotten route must not end up unprotected.

For a need specific to one route, Runique provides router extensions. Real example, the attempt limit on account deletion on runique.io:

// demo-app/src/url.rs (extract)
.rate_limit(
    "/profil/supprimer",
    "supprimer_compte",
    view!(supprimer_compte),
    3,                       // at most 3 requests...
    300,                     // ...per window of 300 seconds
    vec![Method::POST],      // only submissions count
)

rate_limit creates the limiter, puts it as a route_layer on this single route, and starts its periodic cleanup (course concurrence, section 13). For any other layer, route_layer on an axum Router is still possible.

During development, a non-existent URL did not return 404: it redirected to /admin/login.

GET /a-page-that-does-not-exist  →  302  →  /admin/login

The admin's authentication guard was set with layer on the whole router: it intercepted all unauthenticated requests, including those that matched no route (section 8.1), before the router could answer 404.

Request → admin guard (redirects if not signed in) → router (never reached)

The guard must only concern the admin routes: it is set as a route_layer, on the admin routes only.

let admin = axum::Router::new()
    .route("/admin/{*path}", axum::routing::get(handler))
    .route_layer(axum::middleware::from_fn(admin_guard));

In the current admin, this guard is declared_route_access (runique/src/admin/middleware/admin_middleware.rs), set on the admin routes only. Public routes are no longer intercepted, and 404s go up normally to the error handler.

A flash message is stored in the session to be displayed on the next request, typically after a redirect.

success!(request.notices => "Profile updated.");
return Ok(Redirect::to("/profil").into_response());
// stored in session → displayed on /profil, then erased

This is the "POST, then redirect, then GET" pattern: reloading the page after the redirect does not send the form a second time.

Automatic detection (store in session if the response is a redirect, inject otherwise) would require inspecting the response after the handler, then modifying the render already produced. The explicit choice between two syntaxes stays simpler and more predictable.

In which order does the request go through these layers?

Router::new()
    .route("/", get(h))
    .layer(a)
    .layer(b)
    .layer(ServiceBuilder::new().layer(c).layer(d));

Answer: c, d, b, a, then the handler. The ServiceBuilder is added last, so it is the outermost, and inside it, c comes before d.

Write a middleware that rejects with 401 a request without an x-api-key header equal to a known key, comparing in constant time.

// Solution:
use subtle::ConstantTimeEq;

async fn api_key(req: Request, next: Next) -> Response {
    const KEY: &[u8] = b"demo-secret-key";
    let provided = req.headers().get("x-api-key").map(|v| v.as_bytes()).unwrap_or(b"");
    if provided.ct_eq(KEY).unwrap_u8() == 0 {
        return axum::http::StatusCode::UNAUTHORIZED.into_response();
    }
    next.run(req).await
}

ct_eq compares all bytes whatever the position of the first difference: the duration does not reveal the correct start of the key. (A real key is read from the configuration, never hard-coded.)

A guard that redirects to the login page is set with .layer() on the public router. What is the symptom, and the fix?

Answer: every non-existent URL redirects to the login instead of returning 404 (section 9). Fix: .route_layer(), on the protected routes only.