footing 0.4.2

Feature-gated foundations for Rust backend services
Documentation
use serde::{Deserialize, Serialize};

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

#[cfg_attr(feature = "tier", derive(tier::TierConfig))]
#[derive(Debug, Clone, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(default, deny_unknown_fields)]
#[non_exhaustive]
/// Serializable settings for forwarded headers.
pub struct ForwardedHeadersSettings {
    /// Forwarded-header trust mode.
    pub mode: ForwardedHeadersMode,
    /// Proxy networks trusted to supply forwarded headers.
    pub trusted_proxy_cidrs: Vec<String>,
}

#[cfg_attr(feature = "tier", derive(tier::TierConfig))]
#[derive(Debug, Clone, Copy, Serialize, Deserialize, PartialEq, Eq, Default)]
#[serde(rename_all = "snake_case")]
#[non_exhaustive]
/// Enumerates the supported forwarded headers mode values.
pub enum ForwardedHeadersMode {
    #[default]
    /// The capability is disabled.
    Disabled,
    /// Indicates trusted proxies.
    TrustedProxies,
    /// Indicates always.
    Always,
}

impl ForwardedHeadersSettings {
    #[must_use]
    /// Creates disabled.
    pub fn disabled() -> Self {
        Self::default()
    }

    #[must_use]
    /// Creates trusted proxies.
    pub fn trusted_proxies(cidrs: impl IntoIterator<Item = impl Into<String>>) -> Self {
        Self {
            mode: ForwardedHeadersMode::TrustedProxies,
            trusted_proxy_cidrs: cidrs.into_iter().map(Into::into).collect(),
        }
    }

    #[must_use]
    /// Creates always.
    pub fn always() -> Self {
        Self {
            mode: ForwardedHeadersMode::Always,
            trusted_proxy_cidrs: Vec::new(),
        }
    }

    pub(in crate::http::layers) fn build_at(
        &self,
        path: &str,
    ) -> Result<ForwardedHeadersPolicy, SettingsValidationError> {
        let mut issues = SettingsIssues::new();
        match self.mode {
            ForwardedHeadersMode::TrustedProxies => {
                issues.require(
                    !self.trusted_proxy_cidrs.is_empty(),
                    format!("{path}.trusted_proxy_cidrs"),
                    "must not be empty when mode is trusted_proxies",
                );
            }
            ForwardedHeadersMode::Disabled | ForwardedHeadersMode::Always => {
                issues.require(
                    self.trusted_proxy_cidrs.is_empty(),
                    format!("{path}.trusted_proxy_cidrs"),
                    "must be empty unless mode is trusted_proxies",
                );
            }
        }
        let networks = IpNetworkSet::from_cidrs(&self.trusted_proxy_cidrs).map_err(|error| {
            SettingsValidationError::single(
                format!("{path}.trusted_proxy_cidrs"),
                format!("contains invalid CIDR: {error}"),
            )
        });
        if let Err(error) = &networks {
            issues.extend(error.clone());
        }
        issues.into_result()?;
        Ok(match self.mode {
            ForwardedHeadersMode::Disabled => ForwardedHeadersPolicy::Never,
            ForwardedHeadersMode::Always => ForwardedHeadersPolicy::Always,
            ForwardedHeadersMode::TrustedProxies => {
                ForwardedHeadersPolicy::trusted_proxies(networks?)
            }
        })
    }
}

impl TryFrom<&ForwardedHeadersSettings> for ForwardedHeadersPolicy {
    type Error = SettingsValidationError;

    fn try_from(value: &ForwardedHeadersSettings) -> Result<Self, Self::Error> {
        value.build_at("http.forwarded_headers")
    }
}