Module middleware

Expand description

§modo::middleware

Universal HTTP middleware for the modo web framework.

Provides a collection of Tower-compatible middleware layers covering the most common cross-cutting concerns — compression, request IDs, panic recovery, CORS, CSRF, centralised error rendering, security headers, request tracing, and rate limiting. Always available (no feature flag required).

§Relationship to `modo::middlewares`

This module ships the framework-universal layers. The virtual modo::middlewares module is a flat wiring-site index that re-exports both these universal middlewares and domain-specific layers from feature-gated modules (e.g. tenant, auth, flash, ip, tier, geolocation, template). Reach for modo::middlewares when you want a single namespace at your .layer(...) call sites; reach for modo::middleware when you only need the universal layers or the supporting configuration and extractor types.

§Provided items

Function / type	Purpose
`compression`	Compress responses (gzip, deflate, brotli, zstd)
`request_id`	Set / propagate `x-request-id` header
`catch_panic`	Convert handler panics into 500 responses
`cors` / `cors_with`	CORS headers (static or dynamic origins)
`CorsConfig`	CORS configuration
`subdomains` / `urls`	CORS origin predicates
`csrf` / `CsrfConfig`	Double-submit signed-cookie CSRF protection
`CsrfToken`	CSRF token in request/response extensions
`error_handler`	Centralised error-response rendering
`security_headers` / `SecurityHeadersConfig`	Security response headers
`tracing`	HTTP request/response lifecycle spans
`rate_limit` / `rate_limit_with`	Token-bucket rate limiting
`RateLimitConfig`	Rate-limit configuration
`RateLimitLayer`	Tower layer produced by `rate_limit` / `rate_limit_with`
`KeyExtractor`	Trait for custom rate-limit key extraction
`PeerIpKeyExtractor` / `GlobalKeyExtractor`	Built-in key extractors

§Quick start

use axum::{Router, routing::get};
use axum::response::IntoResponse;
use modo::middleware::*;

async fn render_error(err: modo::Error, _parts: http::request::Parts) -> axum::response::Response {
    (err.status(), err.message().to_string()).into_response()
}

let app: Router = Router::new()
    .route("/", get(|| async { "hello" }))
    .layer(error_handler(render_error))
    .layer(compression())
    .layer(request_id())
    .layer(catch_panic())
    .layer(tracing());

Structs§

CorsConfig: Configuration for CORS middleware.
CsrfConfig: Configuration for CSRF protection middleware.
CsrfToken: CSRF token newtype, stored in request and response extensions for handler/template access.
GlobalKeyExtractor: A key extractor that uses a single shared bucket for all requests.
PeerIpKeyExtractor: Extracts the rate-limit key from the peer IP address.
RateLimitConfig: Configuration for the rate-limiting middleware.
RateLimitLayer: A tower::Layer that applies token-bucket rate limiting to all requests.
SecurityHeadersConfig: Configuration for security response headers.

Traits§

KeyExtractor: Trait for extracting a rate-limit key from an incoming request.

Functions§

catch_panic: Returns a layer that catches panics in handlers and returns a 500 response.
compression: Returns a compression layer that automatically compresses response bodies.
cors: Returns a CorsLayer configured from static origin values.
cors_with: Returns a CorsLayer that delegates origin decisions to predicate.
csrf: Returns a Tower layer that applies CSRF protection using the double-submit signed cookie pattern.
error_handler: Creates an error-handler layer that intercepts responses containing a crate::error::Error in their extensions and rewrites them through the supplied handler function.
rate_limit: Returns a rate-limiting layer keyed by peer IP address.
rate_limit_with: Returns a rate-limiting layer with a custom key extractor.
request_id: Returns a layer that sets and propagates an x-request-id header.
security_headers: Returns a Tower layer that adds security headers to every response based on the provided configuration.
subdomains: Returns a predicate that matches any subdomain of domain (including the domain itself). Both http:// and https:// schemes are accepted.
tracing: Returns a tracing layer configured for HTTP request/response lifecycle logging.
urls: Returns a predicate that matches origins against an exact list of URLs.