footing 0.1.5

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

use std::{num::NonZeroUsize, time::Duration};

#[cfg(feature = "settings")]
use serde::{Deserialize, Serialize};

use crate::http::trusted_proxy::ForwardedHeadersPolicy;
#[cfg(feature = "settings")]
use crate::settings::{SettingsIssues, SettingsValidationError};

#[cfg(feature = "settings")]
use super::route_settings::HttpRequestPolicySettings;
#[cfg(feature = "settings")]
use super::{
    error::HttpLayerError,
    settings::{
        CorsSettings, ForwardedHeadersSettings, HttpIdempotencySettings, HttpRateLimitSettings,
        SecurityHeadersSettings, default_http_request_body_limit_setting,
        default_http_timeout_setting, default_true,
    },
};
use super::{
    policy::{
        CorsPolicy, DEFAULT_HTTP_REQUEST_BODY_LIMIT, DEFAULT_HTTP_TIMEOUT, HttpLayerConfig,
        HttpRateLimitConfig, HttpRequestPolicy, RequestBodyLimitPolicy,
    },
    security::SecurityHeadersConfig,
};
use crate::http::IdempotencyConfig;

impl HttpLayerConfig {
    #[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),
            request_body_limit: NonZeroUsize::new(DEFAULT_HTTP_REQUEST_BODY_LIMIT),
            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,
            request_body_limit: 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 request body limit.
    pub const fn request_body_limit(&self) -> Option<usize> {
        match self.request_body_limit {
            Some(value) => Some(value.get()),
            None => None,
        }
    }

    #[must_use]
    /// Returns the request body limit policy.
    pub const fn request_body_limit_policy(&self) -> RequestBodyLimitPolicy {
        match self.request_body_limit {
            Some(value) => RequestBodyLimitPolicy::Bytes(value),
            None => RequestBodyLimitPolicy::Disabled,
        }
    }

    #[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 HttpLayerConfig {
    fn default() -> Self {
        Self::standard()
    }
}

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

#[cfg(feature = "settings")]
impl Default for HttpFoundationSettings {
    fn default() -> Self {
        Self {
            request_context: true,
            trace: true,
            forwarded_headers: ForwardedHeadersSettings::default(),
            cors: CorsSettings::default(),
            security_headers: SecurityHeadersSettings::default(),
            timeout: default_http_timeout_setting(),
            request_body_limit: default_http_request_body_limit_setting(),
            compression: true,
            rate_limit: HttpRateLimitSettings::default(),
            idempotency: HttpIdempotencySettings::default(),
            request_policy: HttpRequestPolicySettings::default(),
        }
    }
}

#[cfg(feature = "settings")]
impl HttpFoundationSettings {
    #[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]
    /// Configures request body limit and returns the updated value.
    pub const fn with_request_body_limit(mut self, request_body_limit: Option<usize>) -> Self {
        self.request_body_limit = request_body_limit;
        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<HttpLayerConfig, SettingsValidationError> {
        self.validate()?;
        let materialize = |path: &'static str, error: HttpLayerError| {
            SettingsValidationError::single(path, error.to_string())
        };
        let request_body_limit = match self.request_body_limit {
            Some(value) => Some(NonZeroUsize::new(value).ok_or_else(|| {
                SettingsValidationError::single(
                    "http.request_body_limit",
                    "must be greater than zero",
                )
            })?),
            None => None,
        };
        Ok(HttpLayerConfig {
            request_context: self.request_context,
            forwarded_headers: ForwardedHeadersPolicy::try_from(&self.forwarded_headers)
                .map_err(|error| materialize("http.forwarded_headers", error))?,
            trace: self.trace,
            cors: CorsPolicy::try_from(&self.cors)
                .map_err(|error| materialize("http.cors", error))?,
            security_headers: SecurityHeadersSettings::try_config(&self.security_headers)
                .map_err(|error| materialize("http.security_headers", error))?,
            timeout: self.timeout,
            request_body_limit,
            compression: self.compression,
            rate_limit: self
                .rate_limit
                .config()
                .map_err(|error| materialize("http.rate_limit", error))?,
            idempotency: self
                .idempotency
                .config()
                .map_err(|error| materialize("http.idempotency", error))?,
            request_policy: HttpRequestPolicy::try_from(&self.request_policy)
                .map_err(|error| materialize("http.request_policy", error))?,
        })
    }

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

    pub(crate) fn validate_at(&self, path: &str) -> Result<(), SettingsValidationError> {
        let mut issues = SettingsIssues::new();
        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",
                );
            }
        }
        if let Some(limit) = self.request_body_limit {
            issues.require(
                limit > 0,
                format!("{path}.request_body_limit"),
                "must be greater than zero",
            );
        }
        issues.extend_result(self.cors.validate_at(&format!("{path}.cors")));
        issues.extend_result(
            self.forwarded_headers
                .validate_at(&format!("{path}.forwarded_headers")),
        );
        issues.extend_result(
            self.security_headers
                .validate_at(&format!("{path}.security_headers")),
        );
        issues.extend_result(self.rate_limit.validate_at(&format!("{path}.rate_limit")));
        issues.extend_result(self.idempotency.validate_at(&format!("{path}.idempotency")));
        issues.extend_result(
            self.request_policy
                .validate_at(&format!("{path}.request_policy")),
        );
        issues.into_result()
    }
}