footing 0.1.21

Feature-gated foundations for Rust backend services
Documentation
//! Top-level immutable HTTP configuration and settings materialization.

use std::time::Duration;

use serde::{Deserialize, Serialize};

use crate::{
    http::{IdempotencyConfig, trusted_proxy::ForwardedHeadersPolicy},
    settings::{SettingsIssues, SettingsValidationError},
};

use super::{
    policy::{
        CorsPolicy, DEFAULT_HTTP_TIMEOUT, HttpMiddlewareConfig, HttpRateLimitConfig,
        HttpRequestPolicy, RequestBodyLimitPolicy,
    },
    route_settings::HttpRequestPolicySettings,
    security::SecurityHeadersConfig,
    settings::{
        CorsSettings, ForwardedHeadersSettings, HttpIdempotencySettings, HttpRateLimitSettings,
        SecurityHeadersSettings,
    },
};

impl HttpMiddlewareConfig {
    #[must_use]
    /// Creates standard.
    pub fn standard() -> Self {
        Self {
            request_context: true,
            forwarded_headers: ForwardedHeadersPolicy::never(),
            trace: true,
            cors: CorsPolicy::Disabled,
            security_headers: Some(SecurityHeadersConfig::api_defaults()),
            timeout: Some(DEFAULT_HTTP_TIMEOUT),
            compression: true,
            rate_limit: None,
            idempotency: None,
            request_policy: HttpRequestPolicy::default(),
        }
    }

    #[must_use]
    /// Creates minimal.
    pub fn minimal() -> Self {
        Self {
            request_context: false,
            forwarded_headers: ForwardedHeadersPolicy::never(),
            trace: false,
            cors: CorsPolicy::Disabled,
            security_headers: None,
            timeout: None,
            compression: false,
            rate_limit: None,
            idempotency: None,
            request_policy: HttpRequestPolicy::disabled(),
        }
    }

    #[must_use]
    /// Returns the request context enabled.
    pub const fn request_context_enabled(&self) -> bool {
        self.request_context
    }

    #[must_use]
    /// Returns the forwarded headers enabled.
    pub fn forwarded_headers_enabled(&self) -> bool {
        !self.forwarded_headers.is_disabled()
    }

    #[must_use]
    /// Returns the forwarded headers policy.
    pub const fn forwarded_headers_policy(&self) -> &ForwardedHeadersPolicy {
        &self.forwarded_headers
    }

    #[must_use]
    /// Returns the trace enabled.
    pub const fn trace_enabled(&self) -> bool {
        self.trace
    }

    #[must_use]
    /// Returns the CORS.
    pub const fn cors(&self) -> &CorsPolicy {
        &self.cors
    }

    #[must_use]
    /// Returns the security headers.
    pub const fn security_headers(&self) -> Option<&SecurityHeadersConfig> {
        self.security_headers.as_ref()
    }

    #[must_use]
    /// Returns the timeout.
    pub const fn timeout(&self) -> Option<Duration> {
        self.timeout
    }

    #[must_use]
    /// Returns the default request body limit from the request policy.
    pub const fn request_body_limit(&self) -> Option<usize> {
        self.request_policy
            .default_request_body_limit()
            .as_optional()
    }

    #[must_use]
    /// Returns the request body limit policy.
    pub const fn request_body_limit_policy(&self) -> RequestBodyLimitPolicy {
        self.request_policy.default_request_body_limit()
    }

    #[must_use]
    /// Returns the compression enabled.
    pub const fn compression_enabled(&self) -> bool {
        self.compression
    }

    #[must_use]
    /// Returns the rate limit.
    pub const fn rate_limit(&self) -> Option<&HttpRateLimitConfig> {
        self.rate_limit.as_ref()
    }

    #[must_use]
    /// Returns the idempotency.
    pub const fn idempotency(&self) -> Option<&IdempotencyConfig> {
        self.idempotency.as_ref()
    }

    #[must_use]
    /// Returns the request policy.
    pub const fn request_policy(&self) -> &HttpRequestPolicy {
        &self.request_policy
    }
}

impl Default for HttpMiddlewareConfig {
    fn default() -> Self {
        Self::standard()
    }
}

#[cfg_attr(feature = "tier", derive(tier::TierConfig))]
#[derive(Debug, Clone, Serialize, Deserialize)]
#[serde(default, deny_unknown_fields)]
#[non_exhaustive]
/// Serializable settings for HTTP middleware.
pub struct HttpMiddlewareSettings {
    /// Whether request identifiers and context are attached to requests.
    pub request_context: bool,
    /// Whether HTTP tracing middleware is enabled.
    pub trace: bool,
    /// Forwarded-header trust configuration.
    pub forwarded_headers: ForwardedHeadersSettings,
    /// Cross-origin resource sharing configuration.
    pub cors: CorsSettings,
    /// Security response header configuration.
    pub security_headers: SecurityHeadersSettings,
    #[serde(with = "crate::settings::human_duration::option")]
    /// Optional timeout applied to each request.
    /// Required when idempotency is enabled, and must be shorter than its processing TTL.
    pub timeout: Option<Duration>,
    /// Whether supported responses may be compressed.
    pub compression: bool,
    /// Global rate-limit configuration.
    pub rate_limit: HttpRateLimitSettings,
    /// Global idempotency configuration.
    pub idempotency: HttpIdempotencySettings,
    /// Default and route-specific request policies.
    pub request_policy: HttpRequestPolicySettings,
}

impl Default for HttpMiddlewareSettings {
    fn default() -> Self {
        Self {
            request_context: true,
            trace: true,
            forwarded_headers: ForwardedHeadersSettings::default(),
            cors: CorsSettings::default(),
            security_headers: SecurityHeadersSettings::default(),
            timeout: Some(DEFAULT_HTTP_TIMEOUT),
            compression: true,
            rate_limit: HttpRateLimitSettings::default(),
            idempotency: HttpIdempotencySettings::default(),
            request_policy: HttpRequestPolicySettings::default(),
        }
    }
}

impl HttpMiddlewareSettings {
    #[must_use]
    /// Creates a new instance.
    pub fn new() -> Self {
        Self::default()
    }

    #[must_use]
    /// Configures request context and returns the updated value.
    pub const fn with_request_context(mut self, request_context: bool) -> Self {
        self.request_context = request_context;
        self
    }

    #[must_use]
    /// Configures trace and returns the updated value.
    pub const fn with_trace(mut self, trace: bool) -> Self {
        self.trace = trace;
        self
    }

    #[must_use]
    /// Configures forwarded headers and returns the updated value.
    pub fn with_forwarded_headers(mut self, forwarded_headers: ForwardedHeadersSettings) -> Self {
        self.forwarded_headers = forwarded_headers;
        self
    }

    #[must_use]
    /// Configures CORS and returns the updated value.
    pub fn with_cors(mut self, cors: CorsSettings) -> Self {
        self.cors = cors;
        self
    }

    #[must_use]
    /// Configures security headers and returns the updated value.
    pub fn with_security_headers(mut self, security_headers: SecurityHeadersSettings) -> Self {
        self.security_headers = security_headers;
        self
    }

    #[must_use]
    /// Configures timeout and returns the updated value.
    pub const fn with_timeout(mut self, timeout: Option<Duration>) -> Self {
        self.timeout = timeout;
        self
    }

    #[must_use]
    /// Sets the request policy's default body limit; `None` disables it.
    /// Calling `with_request_policy` afterwards replaces this value as well.
    pub const fn with_request_body_limit(mut self, request_body_limit: Option<usize>) -> Self {
        self.request_policy.default_request_body_limit = match request_body_limit {
            Some(bytes) => super::route_settings::RequestBodyLimitSettings::Bytes(bytes),
            None => super::route_settings::RequestBodyLimitSettings::Disabled,
        };
        self
    }

    #[must_use]
    /// Configures compression and returns the updated value.
    pub const fn with_compression(mut self, compression: bool) -> Self {
        self.compression = compression;
        self
    }

    #[must_use]
    /// Configures rate limit and returns the updated value.
    pub fn with_rate_limit(mut self, rate_limit: HttpRateLimitSettings) -> Self {
        self.rate_limit = rate_limit;
        self
    }

    #[must_use]
    /// Configures idempotency and returns the updated value.
    pub fn with_idempotency(mut self, idempotency: HttpIdempotencySettings) -> Self {
        self.idempotency = idempotency;
        self
    }

    #[must_use]
    /// Configures request policy and returns the updated value.
    pub fn with_request_policy(mut self, request_policy: HttpRequestPolicySettings) -> Self {
        self.request_policy = request_policy;
        self
    }

    /// Builds immutable HTTP configuration after validating every setting.
    pub fn build(self) -> Result<HttpMiddlewareConfig, SettingsValidationError> {
        self.build_at("http")
    }

    /// Validates all HTTP middleware settings.
    pub fn validate(&self) -> Result<(), SettingsValidationError> {
        self.validate_at("http")
    }

    pub(crate) fn validate_at(&self, path: &str) -> Result<(), SettingsValidationError> {
        self.build_at(path).map(|_| ())
    }

    fn build_at(&self, path: &str) -> Result<HttpMiddlewareConfig, SettingsValidationError> {
        let mut issues = SettingsIssues::new();
        issues.require(
            !self.idempotency.enabled || self.timeout.is_some(),
            format!("{path}.timeout"),
            "must be configured when idempotency is enabled",
        );
        if let Some(timeout) = self.timeout {
            issues.require(
                !timeout.is_zero(),
                format!("{path}.timeout"),
                "must be greater than zero",
            );
            if self.idempotency.enabled {
                issues.require(
                    self.idempotency.processing_ttl > timeout,
                    format!("{path}.idempotency.processing_ttl"),
                    "must be greater than the HTTP request timeout",
                );
            }
        }
        let cors = self.cors.build_at(&format!("{path}.cors"));
        let forwarded_headers = self
            .forwarded_headers
            .build_at(&format!("{path}.forwarded_headers"));
        let security_headers = self
            .security_headers
            .build_at(&format!("{path}.security_headers"));
        let rate_limit = self.rate_limit.build_at(&format!("{path}.rate_limit"));
        let idempotency = self.idempotency.build_at(&format!("{path}.idempotency"));
        let request_policy = self
            .request_policy
            .build_at(&format!("{path}.request_policy"));
        for result in [
            cors.as_ref().map(|_| ()),
            forwarded_headers.as_ref().map(|_| ()),
            security_headers.as_ref().map(|_| ()),
            rate_limit.as_ref().map(|_| ()),
            idempotency.as_ref().map(|_| ()),
            request_policy.as_ref().map(|_| ()),
        ] {
            if let Err(error) = result {
                issues.extend(error.clone());
            }
        }
        issues.into_result()?;
        Ok(HttpMiddlewareConfig {
            request_context: self.request_context,
            forwarded_headers: forwarded_headers?,
            trace: self.trace,
            cors: cors?,
            security_headers: security_headers?,
            timeout: self.timeout,
            compression: self.compression,
            rate_limit: rate_limit?,
            idempotency: idempotency?,
            request_policy: request_policy?,
        })
    }
}