footing 0.1.5

Feature-gated foundations for Rust backend services
Documentation
//! HTTP foundation assembly and Tower/Axum middleware application.

use std::{fmt, sync::Arc};

use axum::{
    Router,
    body::{Body, to_bytes},
    extract::MatchedPath,
    http::{Request, StatusCode},
    middleware::{self, Next},
    response::IntoResponse,
};
use tower_http::{
    compression::CompressionLayer,
    cors::{AllowOrigin, CorsLayer},
    timeout::TimeoutLayer,
    trace::TraceLayer,
};
use tracing::Level;

use crate::http::{
    ApiProblem, HttpMetricsLayer, IdempotencyLayer, IdempotencyRuntime, IdempotencyStore,
    ProblemCode, RateLimitLayer, RateLimitRuntime, RateLimitStore, RequestContext,
    request_context_middleware_with_forwarded_policy,
};

use super::{
    error::HttpLayerError,
    policy::{CorsPolicy, HttpLayerConfig, HttpRequestPolicy, RequestBodyLimitPolicy},
};

#[derive(Debug, Clone)]
#[non_exhaustive]
/// An assembled HTTP middleware stack with explicit runtime dependencies.
pub struct HttpFoundation {
    config: HttpLayerConfig,
    rate_limit: Option<RateLimitRuntime>,
    idempotency: Option<IdempotencyRuntime>,
    metrics: Option<HttpMetricsLayer>,
}

impl HttpFoundation {
    #[must_use]
    /// Starts runtime assembly for validated HTTP configuration.
    pub fn builder(config: HttpLayerConfig) -> HttpFoundationBuilder {
        HttpFoundationBuilder::new(config)
    }

    #[must_use]
    /// Returns the immutable HTTP configuration.
    pub const fn config(&self) -> &HttpLayerConfig {
        &self.config
    }

    /// Applies the assembled middleware stack to a router.
    pub fn apply<S>(self, router: Router<S>) -> Router<S>
    where
        S: Clone + Send + Sync + 'static,
    {
        apply_http_layers(router, self)
    }
}

#[derive(Clone)]
#[non_exhaustive]
/// Injects the runtime stores and telemetry required by HTTP policies.
pub struct HttpFoundationBuilder {
    config: HttpLayerConfig,
    rate_limit_store: Option<Arc<dyn RateLimitStore>>,
    idempotency_store: Option<Arc<dyn IdempotencyStore>>,
    metrics: Option<Arc<dyn crate::observability::MetricRecorder>>,
}

impl fmt::Debug for HttpFoundationBuilder {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("HttpFoundationBuilder")
            .field("config", &self.config)
            .field("rate_limit_store", &self.rate_limit_store.is_some())
            .field("idempotency_store", &self.idempotency_store.is_some())
            .field("metrics", &self.metrics.is_some())
            .finish()
    }
}

impl HttpFoundationBuilder {
    #[must_use]
    /// Creates an assembler for validated HTTP configuration.
    pub fn new(config: HttpLayerConfig) -> Self {
        Self {
            config,
            rate_limit_store: None,
            idempotency_store: None,
            metrics: None,
        }
    }

    #[must_use]
    /// Injects the rate-limit state store.
    pub fn with_rate_limit_store(mut self, store: Arc<dyn RateLimitStore>) -> Self {
        self.rate_limit_store = Some(store);
        self
    }

    #[must_use]
    /// Injects the idempotency state store.
    pub fn with_idempotency_store(mut self, store: Arc<dyn IdempotencyStore>) -> Self {
        self.idempotency_store = Some(store);
        self
    }

    #[must_use]
    /// Injects the shared metric recorder.
    pub fn with_metrics(mut self, metrics: Arc<dyn crate::observability::MetricRecorder>) -> Self {
        self.metrics = Some(metrics);
        self
    }

    /// Resolves policy configuration into a ready-to-apply middleware stack.
    pub fn build(self) -> Result<HttpFoundation, HttpLayerError> {
        let rate_limit = match (&self.config.rate_limit, self.rate_limit_store) {
            (Some(policy), Some(store)) => Some(
                RateLimitRuntime::new(policy.limiter, policy.key_source.clone(), store)
                    .with_metrics(self.metrics.clone()),
            ),
            (Some(_), None) => return Err(HttpLayerError::MissingRateLimitStore),
            (None, _) => None,
        };
        let idempotency = match (self.config.idempotency, self.idempotency_store) {
            (Some(policy), Some(store)) => {
                Some(IdempotencyRuntime::new(store, policy).with_metrics(self.metrics.clone()))
            }
            (Some(_), None) => return Err(HttpLayerError::MissingIdempotencyStore),
            (None, _) => None,
        };
        let metrics = self.metrics.map(HttpMetricsLayer::new);
        Ok(HttpFoundation {
            config: self.config,
            rate_limit,
            idempotency,
            metrics,
        })
    }
}

fn apply_http_layers<S>(router: Router<S>, foundation: HttpFoundation) -> Router<S>
where
    S: Clone + Send + Sync + 'static,
{
    let HttpFoundation {
        config,
        rate_limit,
        idempotency,
        metrics,
    } = foundation;
    let default_request_body_limit = config.request_body_limit_policy();
    let mut router = router;

    if let Some(metrics) = metrics {
        router = router.layer(metrics);
    }

    if let Some(rate_limit) = rate_limit {
        router = router.layer(
            RateLimitLayer::new(rate_limit).with_request_policy(config.request_policy.clone()),
        );
    }

    if let Some(idempotency) = idempotency {
        router = router.layer(
            IdempotencyLayer::new(idempotency).with_request_policy(config.request_policy.clone()),
        );
    }

    // Compression must wrap idempotency so the store keeps one canonical
    // representation and each replay negotiates content encoding independently.
    if config.compression {
        router = router.layer(CompressionLayer::new());
    }

    if !matches!(default_request_body_limit, RequestBodyLimitPolicy::Disabled)
        || config.request_policy.has_request_body_limit_overrides()
    {
        router = router.layer(RouteRequestBodyLimitLayer::new(
            config.request_policy.clone(),
            default_request_body_limit,
        ));
    }

    if let Some(timeout) = config.timeout {
        router = router.layer(TimeoutLayer::with_status_code(
            StatusCode::REQUEST_TIMEOUT,
            timeout,
        ));
    }

    if config.trace {
        router = router.layer(TraceLayer::new_for_http().make_span_with(
            |request: &axum::http::Request<_>| {
                let context = request
                    .extensions()
                    .get::<RequestContext>()
                    .cloned()
                    .unwrap_or_else(|| RequestContext::from_headers(request.headers()));
                let matched_path = request
                    .extensions()
                    .get::<MatchedPath>()
                    .map(MatchedPath::as_str)
                    .unwrap_or_default();

                tracing::span!(
                    Level::INFO,
                    "http_request",
                    method = %request.method(),
                    path = %request.uri().path(),
                    matched_path,
                    request_id = %context.request_id(),
                    trace_id = context.trace_id().unwrap_or_default()
                )
            },
        ));
    }

    if config.request_context {
        let forwarded_headers = config.forwarded_headers;
        router = router.layer(middleware::from_fn(move |request, next| {
            request_context_middleware_with_forwarded_policy(
                request,
                next,
                forwarded_headers.clone(),
            )
        }));
    }

    if let Some(cors_layer) = cors_layer(config.cors) {
        router = router.layer(cors_layer);
    }

    if let Some(security_headers) = config.security_headers {
        router = router.layer(middleware::from_fn(
            move |request: Request<Body>, next: Next| {
                let security_headers = security_headers.clone();
                async move {
                    let mut response = next.run(request).await;
                    security_headers.apply(response.headers_mut());
                    response
                }
            },
        ));
    }

    router
}

#[derive(Debug, Clone)]
struct RouteRequestBodyLimitLayer {
    request_policy: HttpRequestPolicy,
    default_request_body_limit: RequestBodyLimitPolicy,
}

impl RouteRequestBodyLimitLayer {
    fn new(
        request_policy: HttpRequestPolicy,
        default_request_body_limit: RequestBodyLimitPolicy,
    ) -> Self {
        Self {
            request_policy,
            default_request_body_limit,
        }
    }
}

impl<S> tower::Layer<S> for RouteRequestBodyLimitLayer {
    type Service = RouteRequestBodyLimitService<S>;

    fn layer(&self, inner: S) -> Self::Service {
        RouteRequestBodyLimitService {
            inner,
            request_policy: self.request_policy.clone(),
            default_request_body_limit: self.default_request_body_limit,
        }
    }
}

#[derive(Debug, Clone)]
struct RouteRequestBodyLimitService<S> {
    inner: S,
    request_policy: HttpRequestPolicy,
    default_request_body_limit: RequestBodyLimitPolicy,
}

impl<S> tower::Service<Request<Body>> for RouteRequestBodyLimitService<S>
where
    S: tower::Service<Request<Body>, Response = axum::response::Response> + Clone + Send + 'static,
    S::Future: Send + 'static,
    S::Error: Send + 'static,
{
    type Response = axum::response::Response;
    type Error = S::Error;
    type Future = std::pin::Pin<
        Box<dyn std::future::Future<Output = Result<Self::Response, Self::Error>> + Send>,
    >;

    fn poll_ready(
        &mut self,
        context: &mut std::task::Context<'_>,
    ) -> std::task::Poll<Result<(), Self::Error>> {
        self.inner.poll_ready(context)
    }

    fn call(&mut self, request: Request<Body>) -> Self::Future {
        let request_policy = self.request_policy.clone();
        let default_request_body_limit = self.default_request_body_limit;
        let clone = self.inner.clone();
        let mut inner = std::mem::replace(&mut self.inner, clone);

        Box::pin(async move {
            match enforce_route_request_body_limit(
                request_policy,
                default_request_body_limit,
                request,
            )
            .await
            {
                std::ops::ControlFlow::Continue(request) => inner.call(request).await,
                std::ops::ControlFlow::Break(response) => Ok(response),
            }
        })
    }
}

async fn enforce_route_request_body_limit(
    request_policy: HttpRequestPolicy,
    default_request_body_limit: RequestBodyLimitPolicy,
    request: Request<Body>,
) -> std::ops::ControlFlow<axum::response::Response, Request<Body>> {
    let RequestBodyLimitPolicy::Bytes(limit) =
        request_policy.request_body_limit_for(&request, default_request_body_limit)
    else {
        return std::ops::ControlFlow::Continue(request);
    };

    let (parts, body) = request.into_parts();
    let body = match to_bytes(body, limit.get()).await {
        Ok(body) => body,
        Err(_) => {
            return std::ops::ControlFlow::Break(
                ApiProblem::payload_too_large(
                    ProblemCode::REQUEST_BODY_TOO_LARGE,
                    "request body is too large",
                )
                .into_response(),
            );
        }
    };
    std::ops::ControlFlow::Continue(Request::from_parts(parts, Body::from(body)))
}

fn cors_layer(policy: CorsPolicy) -> Option<CorsLayer> {
    match policy {
        CorsPolicy::Disabled => None,
        CorsPolicy::Permissive => Some(CorsLayer::permissive()),
        CorsPolicy::Restricted(config) => {
            let mut layer = CorsLayer::new()
                .allow_origin(AllowOrigin::list(config.allowed_origins))
                .allow_credentials(config.allow_credentials);

            if !config.allowed_methods.is_empty() {
                layer = layer.allow_methods(config.allowed_methods);
            }

            if !config.allowed_headers.is_empty() {
                layer = layer.allow_headers(config.allowed_headers);
            }

            if !config.exposed_headers.is_empty() {
                layer = layer.expose_headers(config.exposed_headers);
            }

            if let Some(max_age) = config.max_age {
                layer = layer.max_age(max_age);
            }

            Some(layer)
        }
    }
}