footing 0.6.6

Feature-gated foundations for Rust backend services
Documentation
//! Validated HTTP policy, settings, and middleware stack assembly.
//!
//! Available with `http-stack`. Assembly has three explicit steps:
//!
//! 1. Configure [`HttpMiddlewareSettings`] and call [`HttpMiddlewareSettings::build`]
//!    to validate them before starting the server.
//! 2. Inject application-owned stores, authentication, authorization, and metrics
//!    through [`HttpMiddlewareStackBuilder`], then call
//!    [`HttpMiddlewareStackBuilder::build`] to check the runtime dependencies.
//! 3. Apply the stack to the routes it should govern.
//!
//! This example accepts the application's existing router, credential verifier,
//! access policy, receipt store, and metric recorder. The authentication hook
//! validates credentials and returns [`crate::http::VerifiedAuthentication`]; the
//! authorization hook enforces current access on every attempt, including replays.
//!
//! ```
//! use std::sync::Arc;
//! use axum::Router;
//! use footing::{
//!     http::{
//!         HttpAuthenticationHook, HttpAuthorizationHook, HttpIdempotencySettings,
//!         HttpMiddlewareSettings, HttpMiddlewareStack, IdempotencyStore,
//!     },
//!     observability::MetricRecorder,
//! };
//!
//! fn api_router(
//!     routes: Router,
//!     authentication: Arc<dyn HttpAuthenticationHook>,
//!     authorization: Arc<dyn HttpAuthorizationHook>,
//!     receipts: Arc<dyn IdempotencyStore>,
//!     metrics: Arc<dyn MetricRecorder>,
//! ) -> Result<Router, Box<dyn std::error::Error>> {
//!     let settings = HttpMiddlewareSettings::new()
//!         .with_max_concurrent_requests(Some(128))
//!         .with_idempotency(HttpIdempotencySettings::default().with_enabled(true));
//!     let config = settings.build()?;
//!     let stack = HttpMiddlewareStack::builder(config)
//!         .with_authentication_hook(authentication)
//!         .with_authorization_hook(authorization)
//!         .with_idempotency_store(receipts)
//!         .with_metrics(metrics)
//!         .build()?;
//!     Ok(stack.apply(routes))
//! }
//! ```
//!
//! Enabling rate limiting requires a [`crate::http::RateLimitStore`]; principal
//! and tenant keys also require an authentication hook. Enabling idempotency
//! requires an [`IdempotencyStore`](crate::http::IdempotencyStore). Configuration validation checks
//! that each replayable route's response timeout is shorter than its processing
//! lease. The application supplies store instances and schedules any periodic
//! cleanup required by its chosen backend.
//!
//! Choose the finishing operation that matches your route declarations:
//!
//! - [`HttpMiddlewareStack::apply`] wraps an existing Axum router.
//! - [`crate::http::EndpointRouter::into_router`] validates the registered
//!   contracts against the stack before applying it. Contracts describe access
//!   requirements; application hooks and handlers enforce them.
//! - With `openapi`, `OpenApiRouter::into_parts_with_stack` performs contract
//!   validation and returns the router together with its OpenAPI document.
//!
//! Apply policies to each subrouter before merging routes with different needs.
//! [`crate::http::metrics`] shows how to expose metrics outside the instrumented
//! API router using only `http-metrics`. Documentation pages can use
//! [`HttpMiddlewareConfig::documentation`] for their browser security headers.
//! The application still decides who may access either endpoint. Clone a built
//! stack when subrouters should share its concurrency budget and injected stores.

mod config;
mod error;
mod policy;
mod route_settings;
mod runtime;
mod settings;

pub use crate::http::security::SecurityHeadersConfig;
pub use config::HttpMiddlewareSettings;
pub use error::HttpMiddlewareError;
pub use policy::{
    CorsConfig, CorsPolicy, DEFAULT_HSTS_MAX_AGE, DEFAULT_HTTP_REQUEST_BODY_LIMIT,
    DEFAULT_HTTP_TIMEOUT, EffectiveHttpRequestPolicy, HttpMiddlewareConfig, HttpRateLimitConfig,
    HttpRequestPolicy, HttpRouteRule, RequestBodyLimitPolicy, ResponseTimeout, RouteMatcher,
};
pub use route_settings::{
    HttpRequestPolicySettings, HttpRouteRuleSettings, RequestBodyLimitSettings,
    RouteMatcherSettings,
};
pub use runtime::{HttpMiddlewareStack, HttpMiddlewareStackBuilder};
pub use settings::{
    CorsMode, CorsSettings, ForwardedHeadersMode, ForwardedHeadersSettings,
    HttpIdempotencySettings, HttpRateLimitSettings, RateLimitKeySourceSettings,
    SecurityHeadersSettings, StrictTransportSecuritySettings,
};

#[cfg(test)]
use crate::http::trusted_proxy::ForwardedHeadersPolicy;

#[cfg(test)]
mod tests;