confers 0.4.0

//! Polled source abstraction for remote configuration.
//!
//! This module provides the `PolledSource` trait for sources that require
//! periodic polling (HTTP endpoints, databases, etc.) and implements
//! `HttpPolledSource` for HTTP-based configuration sources with ETag
//! and Last-Modified support.
//!
//! # SSRF Protection
//!
//! This module implements comprehensive Server-Side Request Forgery protection:
//! - Blocked IP ranges: private networks, loopback, link-local, documentation ranges
//! - DNS resolution validation: resolved IPs are checked against blocked ranges
//! - DNS rebinding protection: domain names are resolved at build time
//! - Configurable whitelist: specific domains can be allowed via builder
//! - All blocked attempts return errors with full context
//! - IPv6 support: handles IPv6 addresses and IPv4-mapped IPv6 addresses

use crate::error::{ConfigError, ConfigResult};
use crate::loader::{detect_format_from_content, parse_content, Format};
use crate::types::{AnnotatedValue, SourceId};
use arc_swap::ArcSwap;
use async_trait::async_trait;
use reqwest::Client;
use std::net::{IpAddr, SocketAddr, ToSocketAddrs};
use std::sync::atomic::AtomicU64;
use std::sync::Arc;
use std::sync::LazyLock;

use std::time::Duration;
use tokio::sync::RwLock;

/// Default poll interval when not specified (60 seconds).
pub const DEFAULT_POLL_INTERVAL: Duration = Duration::from_secs(60);

static BLOCKED_NETWORKS: LazyLock<Vec<ipnet::IpNet>> = LazyLock::new(|| {
    vec![
        "127.0.0.0/8".parse().unwrap(),
        "10.0.0.0/8".parse().unwrap(),
        "172.16.0.0/12".parse().unwrap(),
        "192.168.0.0/16".parse().unwrap(),
        "169.254.0.0/16".parse().unwrap(),
        "100.64.0.0/10".parse().unwrap(),
        "192.0.2.0/24".parse().unwrap(),
        "198.51.100.0/24".parse().unwrap(),
        "203.0.113.0/24".parse().unwrap(),
        "192.0.0.0/24".parse().unwrap(),
        "fc00::/7".parse().unwrap(),
        "fe80::/10".parse().unwrap(),
    ]
});

/// Check if an IP address is in a blocked range.
pub fn is_ip_blocked(ip: IpAddr) -> bool {
    if let IpAddr::V6(ipv6) = ip {
        let octets = ipv6.octets();
        if octets[..10] == [0, 0, 0, 0, 0, 0, 0, 0, 0, 0]
            && octets[10] == 0xff
            && octets[11] == 0xff
        {
            return true;
        }
    }

    if ip.is_loopback() {
        return true;
    }

    BLOCKED_NETWORKS.iter().any(|net| net.contains(&ip))
}

/// Resolve a hostname and check all resolved IPs against blocked ranges.
///
/// This provides DNS rebinding protection by validating that ALL resolved IPs
/// are safe to connect to. If any IP is blocked, the connection is rejected.
///
/// # Arguments
///
/// * `host` - The hostname to resolve
/// * `port` - The port to use for resolution
///
/// # Returns
///
/// Returns `Ok(Vec<IpAddr>)` with all resolved IPs if all are safe,
/// or an error if any IP is blocked.
fn resolve_host_with_validation(host: &str, port: u16) -> ConfigResult<Vec<IpAddr>> {
    let addr_string = if port == 0 {
        format!("{}:80", host)
    } else {
        format!("{}:{}", host, port)
    };

    let addrs: Vec<SocketAddr> = addr_string
        .to_socket_addrs()
        .map_err(|_| ConfigError::InvalidValue {
            key: "url".to_string(),
            expected_type: "resolvable hostname".to_string(),
            message: format!("Cannot resolve hostname: {}", host),
        })?
        .collect();

    if addrs.is_empty() {
        return Err(ConfigError::InvalidValue {
            key: "url".to_string(),
            expected_type: "resolvable hostname".to_string(),
            message: format!("No addresses resolved for hostname: {}", host),
        });
    }

    let mut resolved_ips = Vec::new();
    for addr in &addrs {
        let ip = addr.ip();
        resolved_ips.push(ip);

        if is_ip_blocked(ip) {
            // SSRF attempt detected - return error without logging
            return Err(ConfigError::InvalidValue {
                key: "url".to_string(),
                expected_type: "public IP".to_string(),
                message: "SSRF attempt detected: resolved IP address is in a blocked private range"
                    .to_string(),
            });
        }
    }

    Ok(resolved_ips)
}

/// Validate URL for security (SSRF protection).
///
/// Performs comprehensive SSRF protection checks:
/// 1. Only HTTPS URLs are allowed (unless HTTPS-only is disabled)
/// 2. Domain names are resolved and all resolved IPs are validated
/// 3. Direct IP addresses are validated against blocked ranges
/// 4. IPv4-mapped IPv6 addresses are blocked
/// 5. Domains can be whitelisted via the builder
fn validate_url(url: &str, allowed_domains: &[String]) -> ConfigResult<Vec<IpAddr>> {
    let parsed = url::Url::parse(url).map_err(|_| ConfigError::InvalidValue {
        key: "url".to_string(),
        expected_type: "valid URL".to_string(),
        message: "Invalid URL format".to_string(),
    })?;

    // Only allow HTTPS by default for security
    if parsed.scheme() != "https" {
        // Non-HTTPS URL rejected - return error without logging
        return Err(ConfigError::InvalidValue {
            key: "url".to_string(),
            expected_type: "https URL".to_string(),
            message: "Only HTTPS URLs are allowed for remote configuration".to_string(),
        });
    }

    let host = match parsed.host() {
        Some(h) => h,
        None => {
            return Err(ConfigError::InvalidValue {
                key: "url".to_string(),
                expected_type: "valid URL with host".to_string(),
                message: "URL must have a host".to_string(),
            });
        }
    };

    match host {
        url::Host::Domain(domain) => {
            // Check whitelist first
            let domain_str = domain.to_string();
            let is_whitelisted = allowed_domains.iter().any(|allowed| {
                // Exact match
                if allowed == &domain_str {
                    return true;
                }
                // Wildcard match: *.example.com matches sub.example.com
                if let Some(suffix) = allowed.strip_prefix("*.") {
                    // Domain must be a proper subdomain (e.g., sub.example.com, not example.com)
                    return domain_str.ends_with(&format!(".{suffix}"))
                        && !domain_str.ends_with(suffix);
                }
                // Subdomain match for non-wildcard entries (e.g., "example.com" matches "sub.example.com")
                domain_str.ends_with(&format!(".{allowed}"))
            });

            if is_whitelisted {
                // Whitelisted domains are allowed without IP validation
                return Ok(Vec::new());
            }

            // Resolve the domain and validate all IPs (DNS rebinding protection)
            let port = parsed.port().unwrap_or(443);
            let resolved = resolve_host_with_validation(&domain_str, port)?;

            Ok(resolved)
        }
        url::Host::Ipv4(ip) => {
            if is_ip_blocked(IpAddr::V4(ip)) {
                // Private IPv4 rejected - return error without logging
                return Err(ConfigError::InvalidValue {
                    key: "url".to_string(),
                    expected_type: "public IP".to_string(),
                    message: "Connection to private/internal IP addresses is not allowed"
                        .to_string(),
                });
            }
            Ok(vec![IpAddr::V4(ip)])
        }
        url::Host::Ipv6(ip) => {
            if is_ip_blocked(IpAddr::V6(ip)) {
                // Private IPv6 rejected - return error without logging
                return Err(ConfigError::InvalidValue {
                    key: "url".to_string(),
                    expected_type: "public IP".to_string(),
                    message: "Connection to private/internal IP addresses is not allowed"
                        .to_string(),
                });
            }
            Ok(vec![IpAddr::V6(ip)])
        }
    }
}

/// Trait for polled configuration sources.
///
/// Sources implementing this trait will be polled at regular intervals
/// to fetch the latest configuration values.
#[async_trait]
pub trait PolledSource: Send + Sync {
    /// Poll the source for the latest configuration.
    async fn poll(&self) -> ConfigResult<AnnotatedValue>;

    /// Get the poll interval for this source.
    fn poll_interval(&self) -> Option<Duration>;

    /// Get the source identifier.
    fn source_id(&self) -> SourceId;
}

/// HTTP-polled configuration source.
///
/// Fetches configuration from an HTTP endpoint with support for:
/// - ETag-based conditional requests (If-None-Match)
/// - Last-Modified-based conditional requests (If-Modified-Since)
/// - Configurable poll intervals
/// - Automatic format detection
/// - SSRF protection with configurable domain whitelist
///
/// # SSRF Protection
///
/// By default, connections to the following are blocked:
/// - Private IP ranges (10.x.x.x, 172.16-31.x.x, 192.168.x.x)
/// - Loopback addresses (127.x.x.x, ::1)
/// - Link-local addresses (169.254.x.x, fe80::/10)
/// - Documentation IP ranges (192.0.2.x/24, etc.)
/// - IPv4-mapped IPv6 addresses (::ffff:x.x.x.x)
///
/// DNS names are resolved at build time and all resolved IPs are validated.
///
/// # Examples
///
/// ```
/// use confers::remote::HttpPolledSourceBuilder;
/// use std::time::Duration;
///
/// let source = HttpPolledSourceBuilder::new()
///     .url("https://config.example.com/app.json")
///     .interval(Duration::from_secs(30))
///     .allowed_domain("config.example.com")
///     .allowed_domain("cdn.example.com")
///     .build()
///     .unwrap();
/// ```
///
/// # Lock Contention Optimization
///
/// This implementation uses atomics for ETag/Modified tracking to minimize
/// lock contention in high-concurrency scenarios. Only the cached value
/// is protected by a RwLock, which is held for the minimal time necessary.
#[derive(Debug)]
pub struct HttpPolledSource {
    url: Arc<str>,
    interval: Duration,
    client: Client,
    format: Option<Format>,
    #[allow(dead_code)] // reserved for cache invalidation tracking
    cache_generation: AtomicU64,
    cached: RwLock<Option<AnnotatedValue>>,
    last_etag: ArcSwap<Option<String>>,
    last_modified: ArcSwap<Option<String>>,
    source_id: SourceId,
}

/// Builder for `HttpPolledSource`.
pub struct HttpPolledSourceBuilder {
    url: Option<String>,
    interval: Option<Duration>,
    format: Option<Format>,
    timeout: Option<Duration>,
    allowed_domains: Vec<String>,
}

impl HttpPolledSourceBuilder {
    /// Create a new builder.
    pub fn new() -> Self {
        Self {
            url: None,
            interval: None,
            format: None,
            timeout: None,
            allowed_domains: Vec::new(),
        }
    }

    /// Set the URL of the remote configuration endpoint.
    ///
    /// The URL must use HTTPS. Domain names will be resolved at build time
    /// and all resolved IPs will be checked against blocked ranges.
    ///
    /// # SSRF Protection
    ///
    /// URLs pointing to private IPs, localhost, or documentation ranges
    /// will be rejected at build time.
    pub fn url(mut self, url: impl Into<String>) -> Self {
        self.url = Some(url.into());
        self
    }

    /// Set the poll interval.
    pub fn interval(mut self, interval: Duration) -> Self {
        self.interval = Some(interval);
        self
    }

    /// Set the configuration format (auto-detected if not specified).
    pub fn format(mut self, format: Format) -> Self {
        self.format = Some(format);
        self
    }

    /// Set the request timeout.
    pub fn timeout(mut self, timeout: Duration) -> Self {
        self.timeout = Some(timeout);
        self
    }

    /// Add a domain to the allowed whitelist.
    ///
    /// Whitelisted domains bypass IP-based SSRF checks. This is useful for
    /// internal services accessed via DNS names that resolve to private IPs.
    ///
    /// Supports:
    /// - Exact match: `internal.example.com`
    /// - Subdomain wildcard: `example.com` matches `api.example.com`
    /// - Explicit wildcard: `*.example.com` (via prefix check)
    ///
    /// # Security Note
    ///
    /// Use whitelisting sparingly. Prefer resolving private IP ranges properly.
    /// Whitelisting a domain means you trust ALL IPs that domain resolves to.
    pub fn allowed_domain(mut self, domain: impl Into<String>) -> Self {
        self.allowed_domains.push(domain.into());
        self
    }

    /// Add multiple domains to the allowed whitelist.
    pub fn allowed_domains(mut self, domains: impl IntoIterator<Item = impl Into<String>>) -> Self {
        for domain in domains {
            self.allowed_domains.push(domain.into());
        }
        self
    }

    /// Build the `HttpPolledSource`.
    ///
    /// # Errors
    ///
    /// Returns an error if:
    /// - URL is missing
    /// - URL uses non-HTTPS scheme
    /// - URL host is a blocked private IP
    /// - URL host is a domain that resolves to a blocked IP (DNS rebinding protection)
    pub fn build(self) -> ConfigResult<HttpPolledSource> {
        let url = self.url.ok_or_else(|| ConfigError::InvalidValue {
            key: "url".to_string(),
            expected_type: "string".to_string(),
            message: "URL is required".to_string(),
        })?;

        // Validate URL for security (SSRF protection with DNS resolution)
        validate_url(&url, &self.allowed_domains)?;

        let url_arc: Arc<str> = url.clone().into();
        let source_id = SourceId::new(format!("http:{}", url_arc));

        // Build HTTP client with TLS enabled by default
        let mut client_builder = Client::builder().use_rustls_tls();

        if let Some(timeout) = self.timeout {
            client_builder = client_builder.timeout(timeout);
        }

        let client = client_builder
            .build()
            .map_err(|_e| ConfigError::RemoteUnavailable {
                error_type: "ClientBuild".to_string(),
                retryable: false,
            })?;

        Ok(HttpPolledSource {
            url: url_arc,
            interval: self.interval.unwrap_or(DEFAULT_POLL_INTERVAL),
            client,
            format: self.format,
            cache_generation: AtomicU64::new(0),
            cached: RwLock::new(None),
            last_etag: ArcSwap::new(Arc::new(None)),
            last_modified: ArcSwap::new(Arc::new(None)),
            source_id,
        })
    }
}

impl Default for HttpPolledSourceBuilder {
    fn default() -> Self {
        Self::new()
    }
}

#[async_trait]
impl PolledSource for HttpPolledSource {
    /// Poll the HTTP endpoint for configuration.
    ///
    /// Uses ETag and Last-Modified headers for conditional requests.
    /// Returns cached value on 304 Not Modified responses.
    async fn poll(&self) -> ConfigResult<AnnotatedValue> {
        let mut request = self.client.get(self.url.as_ref());

        if let Some(etag) = self.last_etag.load().as_ref() {
            request = request.header("If-None-Match", etag.as_str());
        }

        if let Some(modified) = self.last_modified.load().as_ref() {
            request = request.header("If-Modified-Since", modified.as_str());
        }

        let response = request
            .send()
            .await
            .map_err(|e| ConfigError::RemoteUnavailable {
                error_type: std::any::type_name::<reqwest::Error>().to_string(),
                retryable: is_retryable_error(&e),
            })?;

        let status = response.status();

        if status == reqwest::StatusCode::NOT_MODIFIED {
            if let Some(cached) = self.cached.read().await.as_ref() {
                return Ok(cached.clone());
            }
            return Err(ConfigError::RemoteUnavailable {
                error_type: "NoCachedValue".to_string(),
                retryable: false,
            });
        }

        if !status.is_success() {
            return Err(ConfigError::RemoteUnavailable {
                error_type: format!("HTTP_{}", status.as_u16()),
                retryable: status.is_server_error() || status.as_u16() == 429,
            });
        }

        if let Some(etag) = response.headers().get("etag") {
            if let Ok(etag_str) = etag.to_str() {
                self.last_etag.store(Arc::new(Some(etag_str.to_string())));
            }
        }

        if let Some(modified) = response.headers().get("last-modified") {
            if let Ok(modified_str) = modified.to_str() {
                self.last_modified
                    .store(Arc::new(Some(modified_str.to_string())));
            }
        }

        let body = response
            .text()
            .await
            .map_err(|e| ConfigError::RemoteUnavailable {
                error_type: std::any::type_name::<reqwest::Error>().to_string(),
                retryable: is_retryable_error(&e),
            })?;

        let format = self
            .format
            .unwrap_or_else(|| detect_format_from_content(&body).unwrap_or(Format::Json));

        let source = self.source_id.clone();
        let value = parse_remote_content(&body, format, source)?;

        *self.cached.write().await = Some(value.clone());

        Ok(value)
    }

    fn poll_interval(&self) -> Option<Duration> {
        Some(self.interval)
    }

    fn source_id(&self) -> SourceId {
        self.source_id.clone()
    }
}

/// Parse content from a remote source using the unified parser.
fn parse_remote_content(
    content: &str,
    format: Format,
    source: SourceId,
) -> ConfigResult<AnnotatedValue> {
    // Use the unified parse_content from loader.rs, which handles all formats
    // consistently. The Format enum already exists in loader.rs.
    parse_content(content, format, source, None)
}

/// Check if a reqwest error is likely retryable.
fn is_retryable_error(error: &reqwest::Error) -> bool {
    error.is_timeout() || error.is_connect()
}

// =============================================================================
// Tests
// =============================================================================

#[cfg(test)]
mod tests {
    use super::*;

    // =============================================================================
    // SSRF Protection Tests (9.1.7)
    // =============================================================================

    #[test]
    fn test_is_ip_blocked_loopback_v4() {
        // 127.0.0.0/8 - all loopback
        assert!(is_ip_blocked(IpAddr::V4("127.0.0.1".parse().unwrap())));
        assert!(is_ip_blocked(IpAddr::V4(
            "127.255.255.255".parse().unwrap()
        )));
        assert!(is_ip_blocked(IpAddr::V4("127.0.0.0".parse().unwrap())));
    }

    #[test]
    fn test_is_ip_blocked_private_v4() {
        // 10.0.0.0/8
        assert!(is_ip_blocked(IpAddr::V4("10.0.0.1".parse().unwrap())));
        assert!(is_ip_blocked(IpAddr::V4("10.255.255.255".parse().unwrap())));
        // 172.16.0.0/12
        assert!(is_ip_blocked(IpAddr::V4("172.16.0.0".parse().unwrap())));
        assert!(is_ip_blocked(IpAddr::V4("172.31.255.255".parse().unwrap())));
        assert!(is_ip_blocked(IpAddr::V4("172.20.0.1".parse().unwrap())));
        // 172.15.x.x and 172.32.x.x are NOT blocked
        assert!(!is_ip_blocked(IpAddr::V4("172.15.0.1".parse().unwrap())));
        assert!(!is_ip_blocked(IpAddr::V4("172.32.0.1".parse().unwrap())));
        // 192.168.0.0/16
        assert!(is_ip_blocked(IpAddr::V4("192.168.0.1".parse().unwrap())));
        assert!(is_ip_blocked(IpAddr::V4(
            "192.168.255.255".parse().unwrap()
        )));
    }

    #[test]
    fn test_is_ip_blocked_link_local_v4() {
        // 169.254.0.0/16
        assert!(is_ip_blocked(IpAddr::V4("169.254.0.0".parse().unwrap())));
        assert!(is_ip_blocked(IpAddr::V4(
            "169.254.255.255".parse().unwrap()
        )));
    }

    #[test]
    fn test_is_ip_blocked_carrier_nat_v4() {
        // 100.64.0.0/10
        assert!(is_ip_blocked(IpAddr::V4("100.64.0.1".parse().unwrap())));
        assert!(is_ip_blocked(IpAddr::V4(
            "100.127.255.255".parse().unwrap()
        )));
        // 100.0-63 and 100.128+ are NOT blocked
        assert!(!is_ip_blocked(IpAddr::V4("100.0.0.1".parse().unwrap())));
        assert!(!is_ip_blocked(IpAddr::V4("100.128.0.1".parse().unwrap())));
    }

    #[test]
    fn test_is_ip_blocked_documentation_v4() {
        // 192.0.2.0/24 (DOC-1)
        assert!(is_ip_blocked(IpAddr::V4("192.0.2.1".parse().unwrap())));
        // 198.51.100.0/24 (DOC-2)
        assert!(is_ip_blocked(IpAddr::V4("198.51.100.1".parse().unwrap())));
        // 203.0.113.0/24 (DOC-3)
        assert!(is_ip_blocked(IpAddr::V4("203.0.113.1".parse().unwrap())));
        // 192.0.0.0/24 (IETF Protocol)
        assert!(is_ip_blocked(IpAddr::V4("192.0.0.1".parse().unwrap())));
    }

    #[test]
    fn test_is_ip_blocked_public_v4() {
        // Public IPs should not be blocked
        assert!(!is_ip_blocked(IpAddr::V4("8.8.8.8".parse().unwrap())));
        assert!(!is_ip_blocked(IpAddr::V4("1.1.1.1".parse().unwrap())));
        assert!(!is_ip_blocked(IpAddr::V4("93.184.216.34".parse().unwrap()))); // example.com
        assert!(!is_ip_blocked(IpAddr::V4("52.94.236.248".parse().unwrap()))); // AWS
    }

    #[test]
    fn test_is_ip_blocked_loopback_v6() {
        // ::1/128
        assert!(is_ip_blocked(IpAddr::V6("::1".parse().unwrap())));
        // ::0/128 is not blocked
        assert!(!is_ip_blocked(IpAddr::V6("::0".parse().unwrap())));
    }

    #[test]
    fn test_is_ip_blocked_unique_local_v6() {
        // fc00::/7
        assert!(is_ip_blocked(IpAddr::V6("fc00::1".parse().unwrap())));
        assert!(is_ip_blocked(IpAddr::V6("fd00::1".parse().unwrap())));
        // fdFF::/8 is the random local address range
        assert!(is_ip_blocked(IpAddr::V6("fdff::1".parse().unwrap())));
        // fe00::/7 is NOT unique local (fe00 is)
        assert!(!is_ip_blocked(IpAddr::V6("fe00::1".parse().unwrap())));
    }

    #[test]
    fn test_is_ip_blocked_link_local_v6() {
        // fe80::/10
        assert!(is_ip_blocked(IpAddr::V6("fe80::1".parse().unwrap())));
        assert!(is_ip_blocked(IpAddr::V6(
            "fe80:ffff:ffff:ffff::".parse().unwrap()
        )));
        // fe81:: is also blocked (still in fe80::/10)
        assert!(is_ip_blocked(IpAddr::V6("fe81::1".parse().unwrap())));
        // fe7f:: is NOT blocked (just outside fe80::/10)
        assert!(!is_ip_blocked(IpAddr::V6("fe7f::1".parse().unwrap())));
    }

    #[test]
    fn test_is_ip_blocked_ipv4_mapped_v6() {
        // IPv4-mapped IPv6 addresses (::ffff:0:0/96)
        assert!(is_ip_blocked(IpAddr::V6(
            "::ffff:127.0.0.1".parse().unwrap()
        )));
        assert!(is_ip_blocked(IpAddr::V6("::ffff:0:0".parse().unwrap())));
        // IPv4-mapped public IPs are still blocked
        assert!(is_ip_blocked(IpAddr::V6("::ffff:8.8.8.8".parse().unwrap())));
    }

    #[test]
    fn test_is_ip_blocked_public_v6() {
        // Public IPv6 addresses should not be blocked
        assert!(!is_ip_blocked(IpAddr::V6(
            "2001:4860:4860::8888".parse().unwrap()
        ))); // Google DNS
        assert!(!is_ip_blocked(IpAddr::V6(
            "2606:4700:4700::1111".parse().unwrap()
        ))); // Cloudflare DNS
    }

    // =============================================================================
    // URL Validation Tests (9.1.7)
    // =============================================================================

    #[test]
    fn test_validate_url_rejects_non_https() {
        let result = validate_url("http://example.com/config.json", &[]);
        assert!(result.is_err());
        let err = result.unwrap_err();
        assert!(matches!(err, ConfigError::InvalidValue { .. }));
    }

    #[test]
    fn test_validate_url_rejects_private_ipv4() {
        // 127.0.0.1
        let result = validate_url("https://127.0.0.1/config.json", &[]);
        assert!(result.is_err());
        // 10.x.x.x
        let result = validate_url("https://10.0.0.1/config.json", &[]);
        assert!(result.is_err());
        // 192.168.x.x
        let result = validate_url("https://192.168.1.1/config.json", &[]);
        assert!(err_if_blocked(&result));
        assert!(result.is_err());
        // 172.16.x.x
        let result = validate_url("https://172.16.0.1/config.json", &[]);
        assert!(result.is_err());
    }

    #[test]
    fn test_validate_url_rejects_private_ipv6() {
        // ::1
        let result = validate_url("https://[::1]/config.json", &[]);
        assert!(result.is_err());
        // fe80:: (link-local)
        let result = validate_url("https://[fe80::1]/config.json", &[]);
        assert!(result.is_err());
        // fc00:: (unique local)
        let result = validate_url("https://[fc00::1]/config.json", &[]);
        assert!(result.is_err());
    }

    #[test]
    fn test_validate_url_rejects_ipv4_mapped() {
        // ::ffff:127.0.0.1
        let result = validate_url("https://[::ffff:127.0.0.1]/config.json", &[]);
        assert!(result.is_err());
    }

    #[test]
    fn test_validate_url_rejects_documentation_ips() {
        let result = validate_url("https://192.0.2.1/config.json", &[]);
        assert!(result.is_err());
        let result = validate_url("https://198.51.100.1/config.json", &[]);
        assert!(result.is_err());
        let result = validate_url("https://203.0.113.1/config.json", &[]);
        assert!(result.is_err());
        let result = validate_url("https://192.0.0.1/config.json", &[]);
        assert!(result.is_err());
    }

    #[test]
    fn test_validate_url_accepts_public_ips() {
        // These should NOT block on IP check alone (though DNS resolution may fail)
        // We test with an IP that won't resolve
        let _result = validate_url("https://8.8.8.8/config.json", &[]);
        // Should not be blocked by SSRF check (8.8.8.8 is public)
        // The DNS resolution will fail for the IP-as-hostname case
        // but that's a different error
    }

    #[test]
    fn test_validate_url_whitelist_exact_match() {
        let result = validate_url(
            "https://internal.example.com/config.json",
            &["internal.example.com".to_string()],
        );
        // T-C-1 B1: the original test had a redundant duplicate
        // `assert!(result.is_ok())`. A single, well-messaged assertion is
        // sufficient — the key behavior is that the whitelist accepts the
        // exact domain. DNS resolution may return an empty IP list for
        // example domains, so we only assert Ok here.
        assert!(
            result.is_ok(),
            "whitelisted domain should be accepted: {:?}",
            result.err()
        );
    }

    #[test]
    fn test_validate_url_whitelist_subdomain_match() {
        // "example.com" in whitelist should match "api.example.com"
        let result = validate_url(
            "https://api.example.com/config.json",
            &["example.com".to_string()],
        );
        // T-C-1 B2: removed redundant duplicate assertion. The key
        // behavior is that the whitelist accepts subdomains.
        assert!(
            result.is_ok(),
            "subdomain of whitelisted domain should be accepted: {:?}",
            result.err()
        );
    }

    #[test]
    fn test_validate_url_whitelist_no_match() {
        // Non-whitelisted domain should be rejected by SSRF check.
        // T-C-1 D4b: old code discarded the result with `let _result = ...`.
        let result = validate_url(
            "https://untrusted.example.com/config.json",
            &["trusted.example.com".to_string()],
        );
        assert!(
            result.is_err(),
            "non-whitelisted domain should be rejected: {result:?}"
        );
    }

    #[test]
    fn test_validate_url_whitelist_mixed() {
        let domains = vec![
            "internal.corp.com".to_string(),
            "config-service.prod".to_string(),
        ];
        let result = validate_url("https://internal.corp.com/config.json", &domains);
        assert!(result.is_ok());
        let result = validate_url("https://config-service.prod/config.json", &domains);
        assert!(result.is_ok());
    }

    // Helper for test assertions
    fn err_if_blocked(result: &Result<Vec<IpAddr>, ConfigError>) -> bool {
        if let Err(e) = result {
            matches!(e, ConfigError::InvalidValue { .. })
        } else {
            false
        }
    }

    // =============================================================================
    // Builder Tests
    // =============================================================================

    #[test]
    fn test_http_polled_source_builder() {
        let source = HttpPolledSourceBuilder::new()
            .url("https://example.com/config.json")
            .interval(Duration::from_secs(30))
            .build()
            .expect("builder should succeed with valid public URL");

        assert_eq!(source.poll_interval(), Some(Duration::from_secs(30)));
        assert_eq!(
            source.source_id().as_str(),
            "http:https://example.com/config.json"
        );
    }

    #[test]
    fn test_http_polled_source_builder_requires_url() {
        let result = HttpPolledSourceBuilder::new().build();
        assert!(result.is_err());
    }

    #[test]
    fn test_default_poll_interval() {
        let source = HttpPolledSourceBuilder::new()
            .url("https://example.com/config.json")
            .build()
            .expect("builder should succeed with valid public URL");

        assert_eq!(source.poll_interval(), Some(DEFAULT_POLL_INTERVAL));
    }

    #[test]
    fn test_builder_pattern() {
        let source = HttpPolledSourceBuilder::new()
            .url("https://example.com/config.yaml")
            .interval(Duration::from_secs(30))
            .format(Format::Yaml)
            .timeout(Duration::from_secs(5))
            .allowed_domain("example.com")
            .allowed_domains(["cdn.example.com", "assets.example.com"])
            .build()
            .expect("builder should succeed with valid public URL and whitelist");

        assert_eq!(source.poll_interval(), Some(Duration::from_secs(30)));
    }

    #[test]
    fn test_builder_rejects_blocked_ip() {
        let result = HttpPolledSourceBuilder::new()
            .url("https://192.168.1.1/config.json")
            .build();

        assert!(result.is_err());
        let err = result.unwrap_err();
        let msg = err.user_message();
        assert!(
            msg.contains("private") || msg.contains("SSRF") || msg.contains("blocked"),
            "Expected SSRF-related error message, got: {}",
            msg
        );
    }

    #[test]
    fn test_builder_rejects_loopback() {
        let result = HttpPolledSourceBuilder::new()
            .url("https://127.0.0.1/config.json")
            .build();

        assert!(result.is_err());

        let result = HttpPolledSourceBuilder::new()
            .url("https://[::1]/config.json")
            .build();

        assert!(result.is_err());
    }

    #[test]
    fn test_builder_accepts_whitelisted_domain() {
        // Even if the domain resolves to a private IP, whitelisted domains are allowed
        // Note: In this test, we use a non-resolvable domain. The point is that
        // if it were resolvable (even to private IPs), the whitelist would bypass the check.
        // We can't easily test actual DNS resolution in unit tests, but the code path is tested.
        let result = HttpPolledSourceBuilder::new()
            .url("https://whitelisted-internal.local/config.json")
            .allowed_domain("whitelisted-internal.local")
            .build();

        // The build should either succeed (if it resolves to public IPs)
        // or fail with a DNS error (not an SSRF error)
        match result {
            Ok(_) => {}
            Err(ConfigError::InvalidValue { message, .. }) => {
                // Should be DNS resolution error, not SSRF error
                assert!(
                    message.contains("resolve") || message.contains("Cannot resolve"),
                    "Expected DNS resolution error, got: {}",
                    message
                );
            }
            Err(_) => {}
        }
    }

    #[test]
    fn test_resolve_host_with_validation_public() {
        // Test with a well-known public DNS
        // Note: This test requires network access. If it fails, the host doesn't resolve.
        let result = resolve_host_with_validation("example.com", 443);
        if let Ok(ips) = result {
            assert!(!ips.is_empty());
            for ip in &ips {
                assert!(
                    !is_ip_blocked(*ip),
                    "example.com resolved to a blocked IP: {}",
                    ip
                );
            }
        }
        // If network is unavailable, test is skipped
    }
}