seer-core 0.52.0

use std::collections::HashSet;
use std::time::Duration;

use regex::Regex;
use std::sync::LazyLock;
use tokio::io::{AsyncReadExt, AsyncWriteExt};
use tokio::net::TcpStream;
use tokio::time::timeout;
use tracing::{debug, instrument, warn};

use super::parser::{field_patterns, WhoisResponse};
use super::servers::{get_tld, get_whois_server_for_domain, has_no_whois_server};
use crate::cache::TtlCache;
use crate::error::{Result, SeerError};
use crate::retry::{RetryExecutor, RetryPolicy};
use crate::validation::normalize_domain;

/// Pre-compiled regexes for extracting WHOIS referral servers. The value
/// MUST be on the key's own line, so an EMPTY `Registrar WHOIS Server:` line
/// yields no match rather than capturing the following line (see
/// [`field_patterns`]).
static REFERRAL_PATTERNS: LazyLock<Vec<Regex>> = LazyLock::new(|| {
    let mut patterns = field_patterns(&["Registrar WHOIS Server", "Whois Server"]);
    patterns.push(
        Regex::new(r"(?i)ReferralServer:[ \t]*whois://(.+)")
            .expect("Invalid regex pattern for ReferralServer"),
    );
    patterns
});

const WHOIS_PORT: u16 = 43;
const DEFAULT_TIMEOUT: Duration = Duration::from_secs(15); // Increased for slow ccTLD registries
const MAX_RESPONSE_SIZE: usize = 1024 * 1024; // 1MB
const MAX_REFERRAL_DEPTH: u8 = 3;
const IANA_WHOIS_SERVER: &str = "whois.iana.org";

/// TTL for discovered WHOIS servers (24 hours)
const SERVER_CACHE_TTL: Duration = Duration::from_secs(24 * 60 * 60);

/// TTL for a definitive "IANA lists no WHOIS server" answer. Shorter than
/// [`SERVER_CACHE_TTL`] so a registry that starts publishing a server is
/// picked up the same day, while repeat lookups skip the IANA round trip.
const NO_SERVER_CACHE_TTL: Duration = Duration::from_secs(60 * 60);

/// Outcome of an IANA WHOIS-server discovery, cached per TLD.
#[derive(Debug, Clone)]
enum Discovery {
    /// IANA named this (vetted) server.
    Server(String),
    /// IANA answered for the TLD but lists no server; the error message.
    NoServer(String),
}

/// Cache of IANA discovery outcomes per TLD. Transient failures (timeouts,
/// connection errors, a reply that is not an IANA record) are never cached.
static DISCOVERED_SERVERS: LazyLock<TtlCache<String, Discovery>> =
    LazyLock::new(|| TtlCache::new(SERVER_CACHE_TTL));

#[derive(Debug, Clone)]
pub struct WhoisClient {
    timeout: Duration,
    retry_policy: RetryPolicy,
    /// Target port for WHOIS queries. Always [`WHOIS_PORT`] in production;
    /// overridable only through the `#[cfg(test)]` seam so mock-server tests
    /// can bind an ephemeral local port.
    port: u16,
    /// When true, skips the SSRF/public-host validation so tests can point
    /// the client at a 127.0.0.1 fixture. Not settable outside `#[cfg(test)]`
    /// builds — production paths always validate.
    allow_private_hosts: bool,
    /// Server asked to discover unmapped TLDs. Always [`IANA_WHOIS_SERVER`]
    /// in production; the `#[cfg(test)]` seam points it at a mock.
    iana_server: &'static str,
}

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

impl WhoisClient {
    /// Creates a new WHOIS client with default settings.
    pub fn new() -> Self {
        Self {
            timeout: DEFAULT_TIMEOUT,
            retry_policy: RetryPolicy::default(),
            port: WHOIS_PORT,
            allow_private_hosts: false,
            iana_server: IANA_WHOIS_SERVER,
        }
    }

    /// Builds a client honoring `~/.seer/config.toml` settings.
    ///
    /// Reads `timeouts.whois_secs` (already clamped to 1–300s by
    /// [`crate::config::SeerConfig::load`]). Sugar over
    /// [`WhoisClient::with_timeout`] — equivalent to
    /// `WhoisClient::new().with_timeout(config.whois_timeout())`.
    pub fn from_config(config: &crate::config::SeerConfig) -> Self {
        Self::new().with_timeout(config.whois_timeout())
    }

    /// Test-only: allow connections to loopback/private hosts (mock servers).
    #[cfg(test)]
    pub(crate) fn allowing_private_hosts(mut self) -> Self {
        self.allow_private_hosts = true;
        self
    }

    /// Test-only: query a non-standard port (mock servers bind ephemeral ports).
    #[cfg(test)]
    pub(crate) fn with_port(mut self, port: u16) -> Self {
        self.port = port;
        self
    }

    /// Test-only: discover unmapped TLDs from `server` instead of IANA.
    #[cfg(test)]
    fn with_iana_server(mut self, server: &'static str) -> Self {
        self.iana_server = server;
        self
    }

    /// Sets the timeout for WHOIS queries.
    ///
    /// The default is 15 seconds to accommodate slow ccTLD registries.
    pub fn with_timeout(mut self, timeout: Duration) -> Self {
        self.timeout = timeout;
        self
    }

    /// Sets the retry policy for transient network failures.
    ///
    /// The default policy makes up to 3 attempts in all (the first plus 2
    /// retries) with exponential backoff.
    pub fn with_retry_policy(mut self, policy: RetryPolicy) -> Self {
        self.retry_policy = policy;
        self
    }

    /// Disables retries (single attempt only).
    pub fn without_retries(mut self) -> Self {
        self.retry_policy = RetryPolicy::no_retry();
        self
    }

    /// Performs a WHOIS lookup for a domain.
    ///
    /// Automatically discovers the appropriate WHOIS server and follows referrals
    /// to get the most detailed registration information.
    #[instrument(skip(self), fields(domain = %domain))]
    pub async fn lookup(&self, domain: &str) -> Result<WhoisResponse> {
        let start = std::time::Instant::now();
        let domain = normalize_domain(domain)?;

        // Try the static mapping first — most-specific match wins (a
        // second-level registry zone like co.za before the plain TLD).
        let whois_server = match get_whois_server_for_domain(&domain) {
            Some(server) => server.to_string(),
            None => self.discover_whois_server(get_tld(&domain)).await?,
        };

        let mut visited = HashSet::new();
        let result = self
            .lookup_with_referrals(&domain, &whois_server, 0, &mut visited)
            .await;
        let elapsed_ms = start.elapsed().as_millis();
        debug!(
            domain = %domain,
            elapsed_ms = elapsed_ms,
            "WHOIS lookup complete"
        );
        result
    }

    fn lookup_with_referrals<'a>(
        &'a self,
        domain: &'a str,
        whois_server: &'a str,
        depth: u8,
        visited: &'a mut HashSet<String>,
    ) -> std::pin::Pin<Box<dyn std::future::Future<Output = Result<WhoisResponse>> + Send + 'a>>
    {
        Box::pin(async move {
            // Enforce max referral depth BEFORE querying so we consult at most
            // MAX_REFERRAL_DEPTH servers (depths 0..MAX_REFERRAL_DEPTH-1).
            if depth >= MAX_REFERRAL_DEPTH {
                warn!(depth = depth, server = %whois_server, "Max referral depth reached before query, aborting referral chain");
                return Err(SeerError::WhoisError(
                    "max WHOIS referral depth exceeded".to_string(),
                ));
            }

            // Check for circular referrals
            let server_lower = whois_server.to_lowercase();
            if visited.contains(&server_lower) {
                warn!(server = %whois_server, "Circular WHOIS referral detected");
                return Err(SeerError::WhoisError(
                    "circular WHOIS referral detected".to_string(),
                ));
            }
            visited.insert(server_lower);

            debug!(whois_server = %whois_server, depth = depth, "Querying WHOIS server");

            // The registry (depth 0) gets the full retry policy. A registrar
            // referral hop only runs with the registry record already in
            // hand — which is kept whenever the hop fails — so it is a
            // single attempt rather than seconds of retries on a
            // best-effort enrichment.
            let policy = if depth == 0 {
                self.retry_policy.clone()
            } else {
                RetryPolicy::no_retry()
            };
            let query = format_query_for_server(whois_server, domain);
            let raw_response = self
                .query_server_with_retry(whois_server, &query, &policy)
                .await?;
            let current_response = WhoisResponse::parse(domain, whois_server, &raw_response);

            // Prefer registry response when it has core data (registrar, dates,
            // nameservers).  Registrar (referral) servers are often slow, rate-
            // limited, or outright block non-commercial queries (e.g. CSC's
            // whois.corporatedomains.com).  Most contact fields are GDPR-redacted
            // anyway, so the registry response is sufficient for the vast majority
            // of use cases.
            if current_response.has_core_data() {
                debug!(
                    server = %whois_server,
                    "Registry response has core data, skipping registrar referral"
                );
                return Ok(current_response);
            }

            // Registry response is thin — follow the referral for more detail
            if let Some(referral) = extract_referral_with(&raw_response, self.allow_private_hosts) {
                if referral != whois_server && !visited.contains(&referral.to_lowercase()) {
                    debug!(
                        referral_depth = depth,
                        "Registry response lacks core data, following referral to {}", referral
                    );
                    match self
                        .lookup_with_referrals(domain, &referral, depth + 1, visited)
                        .await
                    {
                        Ok(referral_response) => {
                            if referral_response.is_available()
                                || referral_response.indicates_not_found()
                            {
                                debug!(
                                    referral = %referral,
                                    "Referral server indicates domain not found, using registry response"
                                );
                                return Ok(current_response);
                            }
                            // Only let the referral replace the registry
                            // record when it actually carries registration
                            // data. A registry record that merely lacks
                            // nameservers (an undelegated domain) still has
                            // its registrar/dates/status, and a registrar's
                            // throttle or refusal body ("connection limit
                            // exceeded") must not swap that for all-None.
                            if !referral_response.has_registration_fields()
                                && current_response.has_any_registry_field()
                            {
                                debug!(
                                    referral = %referral,
                                    "Referral response carries no registration data, using registry response"
                                );
                                return Ok(current_response);
                            }
                            return Ok(referral_response);
                        }
                        Err(e) => {
                            debug!(referral = %referral, error = %e, "Referral lookup failed, using registry response");
                            return Ok(current_response);
                        }
                    }
                }
            }

            Ok(current_response)
        })
    }

    /// Performs a WHOIS lookup using a specific WHOIS server.
    ///
    /// Use this when you know the exact server to query, bypassing automatic
    /// server discovery and referral following.
    #[instrument(skip(self), fields(domain = %domain, server = %server))]
    pub async fn lookup_with_server(&self, domain: &str, server: &str) -> Result<WhoisResponse> {
        // Validate server before any network connection
        if server.contains('\r') || server.contains('\n') {
            return Err(SeerError::WhoisError(format!(
                "invalid WHOIS server: contains illegal characters: {}",
                server.replace('\r', "\\r").replace('\n', "\\n")
            )));
        }
        if !self.allow_private_hosts && !is_safe_whois_server(server) {
            return Err(SeerError::WhoisError(format!(
                "invalid WHOIS server: {}",
                server
            )));
        }

        let domain = normalize_domain(domain)?;
        let query = format_query_for_server(server, &domain);
        let raw_response = self
            .query_server_with_retry(server, &query, &self.retry_policy)
            .await?;
        Ok(WhoisResponse::parse(&domain, server, &raw_response))
    }

    /// Queries a WHOIS server, retrying transient failures under `policy`.
    async fn query_server_with_retry(
        &self,
        server: &str,
        query: &str,
        policy: &RetryPolicy,
    ) -> Result<String> {
        let executor = RetryExecutor::new(policy.clone());
        let server = server.to_string();
        let query = query.to_string();
        let timeout_duration = self.timeout;
        let port = self.port;
        let allow_private_hosts = self.allow_private_hosts;

        executor
            .execute(|| {
                let server = server.clone();
                let query = query.clone();
                async move {
                    query_server_internal_with(
                        &server,
                        &query,
                        timeout_duration,
                        port,
                        allow_private_hosts,
                    )
                    .await
                }
            })
            .await
    }

    /// Finds the WHOIS server for a TLD missing from the static map: none for
    /// a TLD the catalog knows has no port-43 service (RDAP-only, retired or
    /// server-less per IANA), else the cached or freshly queried IANA answer.
    async fn discover_whois_server(&self, tld: &str) -> Result<String> {
        if has_no_whois_server(tld) {
            return Err(SeerError::WhoisServerNotFound(format!(
                "No WHOIS server for '.{tld}' (the registry offers no port-43 WHOIS; use RDAP)"
            )));
        }
        let discovery = match DISCOVERED_SERVERS.get(&tld.to_string()) {
            Some(cached) => {
                debug!(tld = %tld, "Using cached IANA discovery");
                cached
            }
            None => {
                debug!(tld = %tld, "Querying IANA for WHOIS server");
                let discovery = self.query_iana(tld).await?;
                let ttl = match discovery {
                    Discovery::Server(_) => SERVER_CACHE_TTL,
                    Discovery::NoServer(_) => NO_SERVER_CACHE_TTL,
                };
                DISCOVERED_SERVERS.insert_with_ttl(tld.to_string(), discovery.clone(), ttl);
                discovery
            }
        };
        match discovery {
            Discovery::Server(server) => Ok(server),
            Discovery::NoServer(msg) => Err(SeerError::WhoisServerNotFound(msg)),
        }
    }

    /// Asks IANA (with retry) for a TLD's WHOIS server. `Ok` is a definitive
    /// answer worth caching; every failure — including a reply that is not an
    /// IANA TLD record — is `Err` and left uncached.
    async fn query_iana(&self, tld: &str) -> Result<Discovery> {
        let response = self
            .query_server_with_retry(self.iana_server, tld, &self.retry_policy)
            .await?;

        // IANA response format includes a line like: "whois:        whois.nic.xyz"
        if let Some(server) = extract_iana_whois_server(&response) {
            // Validate IANA-discovered hostname before trusting/caching it.
            // A poisoned IANA response could otherwise inject a malicious
            // WHOIS server that gets cached for 24h.
            if !self.allow_private_hosts && !is_safe_whois_server(&server) {
                warn!(server = %server, "IANA returned unsafe WHOIS server, rejecting");
                return Err(SeerError::WhoisError(format!(
                    "IANA returned unsafe WHOIS server: {}",
                    server
                )));
            }
            // SSRF guard: resolve the discovered hostname and refuse it if any
            // resolved address is in a reserved range. This prevents a malicious
            // or poisoned IANA response from caching a hostname that (via DNS
            // rebinding or otherwise) points at internal services (H1 amplifier
            // via 24h cache).
            if !self.allow_private_hosts {
                crate::net::validate_public_host(&server, WHOIS_PORT).await?;
            }
            return Ok(Discovery::Server(server));
        }

        let msg = match extract_iana_registration_url(&response) {
            Some(url) => format!("No WHOIS server for '.{tld}' - check whois directly via: {url}"),
            None => format!("No WHOIS server found for TLD '{tld}'"),
        };
        if is_iana_record(&response) {
            Ok(Discovery::NoServer(msg))
        } else {
            // Not an IANA answer (truncated, throttled, empty): do not cache.
            Err(SeerError::WhoisServerNotFound(msg))
        }
    }
}

/// Whether an IANA port-43 reply is an authoritative answer for the query:
/// a TLD record (it opens with a `domain:` line) or IANA's explicit "0
/// objects" miss. Anything else is not a definitive "no server".
fn is_iana_record(response: &str) -> bool {
    response.lines().any(|line| {
        let line = line.trim_start().to_ascii_lowercase();
        line.starts_with("domain:") || line.contains("returned 0 objects")
    })
}

/// Formats the wire query for registries whose port-43 servers need more
/// than the bare domain: DENIC returns only `Status: connect` unless queried
/// with `-T dn,ace`, and JPRS answers in Japanese without a `/e` suffix.
/// Everything else gets the domain unchanged.
fn format_query_for_server(server: &str, domain: &str) -> String {
    match server.to_ascii_lowercase().as_str() {
        "whois.denic.de" => format!("-T dn,ace {}", domain),
        "whois.jprs.jp" => format!("{}/e", domain),
        _ => domain.to_string(),
    }
}

/// Test-facing wrapper with the historical 3-arg signature: standard port,
/// full SSRF validation. Production goes through [`query_server_internal_with`]
/// via `WhoisClient`, whose `port`/`allow_private_hosts` fields are only
/// non-default in `#[cfg(test)]` builds.
#[cfg(test)]
async fn query_server_internal(
    server: &str,
    query: &str,
    timeout_duration: Duration,
) -> Result<String> {
    query_server_internal_with(server, query, timeout_duration, WHOIS_PORT, false).await
}

/// Sends one WHOIS query over TCP to `server:port` and returns the response.
/// `port` and `allow_private_hosts` (which skips the SSRF host validation)
/// exist so `#[cfg(test)]` mock-server tests can target 127.0.0.1 on an
/// ephemeral port. The only production caller is `WhoisClient`, which
/// passes [`WHOIS_PORT`] and `allow_private_hosts: false` outside test builds.
async fn query_server_internal_with(
    server: &str,
    query: &str,
    timeout_duration: Duration,
    port: u16,
    allow_private_hosts: bool,
) -> Result<String> {
    // Defense in depth: reject CR/LF/NUL in the query before any TCP write.
    // normalize_domain already filters these, but we enforce here too so
    // alternate call paths cannot bypass the check.
    if query.bytes().any(|b| b == 0 || b == b'\r' || b == b'\n') {
        return Err(SeerError::WhoisError(
            "query string must not contain CR/LF/NUL".into(),
        ));
    }

    // SSRF guard: resolve the server hostname, refuse any address in a
    // reserved/private/loopback/link-local range, and connect to the VALIDATED
    // SocketAddrs. Connecting to the resolved addresses (rather than letting
    // TcpStream::connect("host:port") re-resolve) closes the DNS-rebinding
    // TOCTOU where a hostile authoritative DNS for a referral/IANA-discovered
    // server could answer the validation lookup with a public IP and the
    // connect lookup with 127.0.0.1 / 169.254.169.254 / RFC1918.
    let addrs: Vec<std::net::SocketAddr> = if allow_private_hosts {
        tokio::net::lookup_host((server, port))
            .await
            .map_err(|e| SeerError::WhoisError(format!("failed to resolve {}: {}", server, e)))?
            .collect()
    } else {
        crate::net::resolve_public_host(server, port).await?
    };

    debug!("WHOIS query to {}", server);
    let mut stream = connect_ipv4_first(server, addrs, timeout_duration).await?;

    // Send query with CRLF
    let query_bytes = format!("{}\r\n", query);
    timeout(timeout_duration, stream.write_all(query_bytes.as_bytes()))
        .await
        .map_err(|_| SeerError::Timeout("write timed out".to_string()))?
        .map_err(|e| SeerError::WhoisError(format!("failed to send query: {}", e)))?;

    // Read response with a wall-clock deadline so slow-trickle servers
    // cannot hold the connection open indefinitely.
    let mut response = Vec::new();
    let mut buf = [0u8; 4096];
    let deadline = tokio::time::Instant::now() + timeout_duration;

    loop {
        let remaining = deadline.saturating_duration_since(tokio::time::Instant::now());
        if remaining.is_zero() {
            if !response.is_empty() {
                tracing::warn!(
                    "WHOIS read deadline reached with partial response ({} bytes)",
                    response.len()
                );
                break;
            }
            return Err(SeerError::Timeout("read timed out".to_string()));
        }

        let read_result = timeout(remaining, stream.read(&mut buf)).await;

        match read_result {
            Ok(Ok(0)) => break, // EOF
            Ok(Ok(n)) => {
                response.extend_from_slice(&buf[..n]);
                if response.len() > MAX_RESPONSE_SIZE {
                    return Err(SeerError::WhoisError("response too large".to_string()));
                }
            }
            Ok(Err(e)) => {
                return Err(SeerError::WhoisError(format!("read error: {}", e)));
            }
            Err(_) => {
                // Timeout on read - if we have data, return it
                if !response.is_empty() {
                    tracing::warn!(
                        "WHOIS per-read timeout with partial response ({} bytes)",
                        response.len()
                    );
                    break;
                }
                return Err(SeerError::Timeout("read timed out".to_string()));
            }
        }
    }

    // Explicitly shutdown the TCP stream to ensure proper FIN handshake
    let _ = stream.shutdown().await;

    Ok(decode_whois_body(response))
}

/// Connects to the first reachable of `addrs` within `budget`, IPv4 first
/// with a per-address share of the budget ([`crate::net::connect_any`]).
async fn connect_ipv4_first(
    server: &str,
    addrs: Vec<std::net::SocketAddr>,
    budget: Duration,
) -> Result<TcpStream> {
    crate::net::connect_any(&addrs, budget, TcpStream::connect)
        .await
        .map_err(|e| match e {
            // The unconditionally-retryable variant: the substring-gated
            // WhoisError classification misses transient connect failures
            // whose OS message lacks "connection"/"refused"/"reset"/"timeout"
            // (e.g. "Network is unreachable", "No route to host").
            crate::net::ConnectError::Io(e) => {
                SeerError::WhoisConnectionFailed(format!("failed to connect to {server}: {e}"))
            }
            crate::net::ConnectError::TimedOut => {
                SeerError::Timeout(format!("connection to {server} timed out"))
            }
        })
}

/// Decodes a raw port-43 body: UTF-8 where the bytes are valid UTF-8, and
/// every byte that is NOT part of a valid UTF-8 sequence as windows-1252
/// (Latin-1 plus printable 0x80–0x9F).
///
/// Decoding per invalid byte rather than reinterpreting the WHOLE body keeps
/// valid UTF-8 intact (CJK ccTLD registries — JPRS, KISA, CONAC, TWNIC,
/// NIC.br — emit UTF-8, and one stray byte must not mojibake every character
/// after it), while legacy ISO-8859-1 / windows-1252 bodies (`M\xfcller`)
/// keep their accents instead of collapsing to U+FFFD as a lossy UTF-8
/// decode would. The 0x80–0x9F range maps to windows-1252's printable
/// characters — never to C1 control characters, which a terminal could act
/// on — and its five undefined bytes to U+FFFD.
fn decode_whois_body(bytes: Vec<u8>) -> String {
    /// windows-1252 characters for bytes 0x80–0x9F (U+FFFD where undefined).
    const CP1252_80_9F: [char; 32] = [
        '\u{20AC}', '\u{FFFD}', '\u{201A}', '\u{0192}', '\u{201E}', '\u{2026}', '\u{2020}',
        '\u{2021}', '\u{02C6}', '\u{2030}', '\u{0160}', '\u{2039}', '\u{0152}', '\u{FFFD}',
        '\u{017D}', '\u{FFFD}', '\u{FFFD}', '\u{2018}', '\u{2019}', '\u{201C}', '\u{201D}',
        '\u{2022}', '\u{2013}', '\u{2014}', '\u{02DC}', '\u{2122}', '\u{0161}', '\u{203A}',
        '\u{0153}', '\u{FFFD}', '\u{017E}', '\u{0178}',
    ];
    match String::from_utf8(bytes) {
        Ok(text) => text,
        Err(e) => {
            let bytes = e.into_bytes();
            let mut text = String::with_capacity(bytes.len() + bytes.len() / 2);
            for chunk in bytes.utf8_chunks() {
                text.push_str(chunk.valid());
                text.extend(chunk.invalid().iter().map(|&b| match b {
                    0x80..=0x9F => CP1252_80_9F[usize::from(b - 0x80)],
                    _ => char::from(b),
                }));
            }
            text
        }
    }
}

/// Extracts the WHOIS server from an IANA response.
fn extract_iana_whois_server(response: &str) -> Option<String> {
    for line in response.lines() {
        let line = line.trim();
        if line.to_lowercase().starts_with("whois:") {
            let server = line[6..].trim();
            if !server.is_empty() {
                return Some(server.to_lowercase());
            }
        }
    }
    None
}

/// Extracts the registration URL from an IANA response remarks field.
fn extract_iana_registration_url(response: &str) -> Option<String> {
    for line in response.lines() {
        let line = line.trim();
        if line.to_lowercase().starts_with("remarks:") {
            let remarks = line[8..].trim();
            // Look for URL patterns in remarks
            if let Some(url_start) = remarks.find("http") {
                let url = &remarks[url_start..];
                // Extract URL (ends at whitespace or end of line)
                let url_end = url.find(char::is_whitespace).unwrap_or(url.len());
                return Some(url[..url_end].to_string());
            }
        }
    }
    None
}

/// Checks whether a WHOIS referral server hostname is safe to connect to.
/// Rejects IP literals in private/reserved ranges, embedded ports, and
/// hostnames with characters that are not valid in DNS labels.
fn is_safe_whois_server(server: &str) -> bool {
    // Must be a plausible hostname: alphanumeric, dots, hyphens only
    if server.is_empty() || !server.contains('.') {
        return false;
    }
    if !server
        .chars()
        .all(|c| c.is_ascii_alphanumeric() || c == '.' || c == '-')
    {
        return false;
    }
    // Reject IP address literals that resolve to private/reserved ranges
    if let Ok(ip) = server.parse::<std::net::IpAddr>() {
        return !crate::net::is_reserved_ip(ip);
    }
    true
}

/// Test-facing wrapper preserving the historical 1-arg signature (production
/// semantics: safe-hostname filter applied).
#[cfg(test)]
fn extract_referral(response: &str) -> Option<String> {
    extract_referral_with(response, false)
}

/// Returns the first referral server named in `response`, kept only if it
/// passes [`is_safe_whois_server`]. `allow_private_hosts` skips that filter
/// so `#[cfg(test)]` mock servers (loopback, no dots) can act as referral
/// targets. Production callers pass the client's `allow_private_hosts`,
/// which is always false outside test builds.
fn extract_referral_with(response: &str, allow_private_hosts: bool) -> Option<String> {
    for re in REFERRAL_PATTERNS.iter() {
        if let Some(caps) = re.captures(response) {
            if let Some(m) = caps.get(1) {
                let server = m.as_str().trim().to_lowercase();
                if allow_private_hosts || is_safe_whois_server(&server) {
                    return Some(server);
                }
            }
        }
    }

    None
}

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

    #[test]
    fn from_config_applies_whois_timeout() {
        let mut config = crate::config::SeerConfig::default();
        config.timeouts.whois_secs = 42;
        let client = WhoisClient::from_config(&config);
        assert_eq!(client.timeout, Duration::from_secs(42));
    }

    #[test]
    fn test_normalize_domain() {
        assert_eq!(normalize_domain("example.com").unwrap(), "example.com");
        assert_eq!(normalize_domain("EXAMPLE.COM").unwrap(), "example.com");
        assert_eq!(
            normalize_domain("https://www.example.com/path").unwrap(),
            "example.com"
        );
        assert!(normalize_domain("invalid").is_err());
    }

    #[test]
    fn test_default_client_has_retry_policy() {
        let client = WhoisClient::new();
        assert_eq!(client.retry_policy.max_attempts, 3);
    }

    #[test]
    fn extract_referral_same_line_value() {
        let response = "Registrar WHOIS Server: whois.registrar.example\n";
        assert_eq!(
            extract_referral(response),
            Some("whois.registrar.example".to_string())
        );
    }

    #[test]
    fn extract_referral_empty_key_line_does_not_capture_next_line() {
        // An empty `Registrar WHOIS Server:` line must NOT capture the
        // following line's content as the referral server.
        let response = "Registrar WHOIS Server:\nwhois.victim.example\n";
        assert_eq!(
            extract_referral(response),
            None,
            "empty referral key line must not swallow the next line"
        );
    }

    #[test]
    fn decode_whois_body_keeps_utf8_and_decodes_legacy_bytes_as_cp1252() {
        // Valid UTF-8 is untouched.
        assert_eq!(
            decode_whois_body("Registrant: 東京ドメイン\n".as_bytes().to_vec()),
            "Registrant: 東京ドメイン\n"
        );
        // An ISO-8859-1 body keeps its accents (a lossy UTF-8 decode turned
        // each into U+FFFD).
        assert_eq!(
            decode_whois_body(b"Registrant: M\xfcller Stra\xdfe, K\xf8benhavn\n".to_vec()),
            "Registrant: Müller Straße, København\n"
        );
        // A stray byte inside a UTF-8 body only affects that byte.
        let mut mixed = "Name Server: ns1.例え.jp ".as_bytes().to_vec();
        mixed.push(0xE9);
        mixed.extend_from_slice(" 東京\n".as_bytes());
        assert_eq!(
            decode_whois_body(mixed),
            "Name Server: ns1.例え.jp é 東京\n"
        );
        // 0x80–0x9F decode as windows-1252 printables, never C1 controls;
        // its undefined bytes become U+FFFD.
        let decoded = decode_whois_body(b"\x93quoted\x94 \x80 \x81".to_vec());
        assert_eq!(decoded, "\u{201C}quoted\u{201D} \u{20AC} \u{FFFD}");
        assert!(!decoded.chars().any(|c| ('\u{80}'..='\u{9F}').contains(&c)));
    }

    #[test]
    fn test_client_without_retries() {
        let client = WhoisClient::new().without_retries();
        assert_eq!(client.retry_policy.max_attempts, 1);
    }

    #[test]
    fn test_client_custom_retry_policy() {
        let policy = RetryPolicy::new().with_max_attempts(5);
        let client = WhoisClient::new().with_retry_policy(policy);
        assert_eq!(client.retry_policy.max_attempts, 5);
    }

    #[tokio::test]
    async fn query_server_internal_rejects_crlf_in_query() {
        // CR in query should be rejected before any TCP connect.
        let err = query_server_internal(
            "whois.example.com",
            "example.com\r\nWHOIS evil.example",
            Duration::from_secs(1),
        )
        .await
        .expect_err("CRLF in query must be rejected");
        match err {
            SeerError::WhoisError(msg) => {
                assert!(msg.contains("CR/LF/NUL"), "unexpected message: {msg}");
            }
            other => panic!("expected WhoisError, got {other:?}"),
        }

        // LF-only and NUL should also be rejected.
        assert!(
            query_server_internal("whois.example.com", "a\nb", Duration::from_secs(1))
                .await
                .is_err()
        );
        assert!(
            query_server_internal("whois.example.com", "a\0b", Duration::from_secs(1))
                .await
                .is_err()
        );
    }

    #[test]
    fn iana_discovery_rejects_unsafe_server() {
        // extract_iana_whois_server returns the value verbatim (lowercased).
        // `query_iana` is expected to reject anything that
        // fails is_safe_whois_server before caching it.
        let synthetic = "refer: whois.iana.org\nwhois: 127.0.0.1\n";
        let extracted = extract_iana_whois_server(synthetic);
        assert_eq!(extracted.as_deref(), Some("127.0.0.1"));

        // is_safe_whois_server must reject loopback IP literals, which is
        // what the discovery wrapper now enforces before caching.
        assert!(
            !is_safe_whois_server(&extracted.unwrap()),
            "is_safe_whois_server must reject 127.0.0.1"
        );

        // Sanity: hostnames with CR/LF or illegal chars are also rejected.
        assert!(!is_safe_whois_server("whois.evil.com\r\nevil"));
        assert!(!is_safe_whois_server("whois.evil.com:4444"));

        // A legitimate hostname is accepted.
        assert!(is_safe_whois_server("whois.nic.xyz"));
    }

    // H13 regression: with MAX_REFERRAL_DEPTH = 3, exactly 3 servers should be
    // queried across a longer referral chain. Verifying this end-to-end
    // requires mocking TCP WHOIS servers. The depth check in
    // `lookup_with_referrals` now fires BEFORE `query_server_with_retry`, so
    // the sequence 0 -> 1 -> 2 (each queries) then 3 (rejected pre-query)
    // consults exactly MAX_REFERRAL_DEPTH servers. See the diff for
    // Batch 5 / H13 for the fix location.

    #[tokio::test]
    async fn whois_refuses_loopback_server() {
        // Feeding 127.0.0.1 as the server must be rejected by
        // validate_public_host BEFORE any TCP connect is attempted.
        let err = query_server_internal("127.0.0.1", "example.com", Duration::from_secs(1))
            .await
            .expect_err("loopback server must be rejected");
        match err {
            SeerError::InvalidInput(msg) => {
                assert!(
                    msg.contains("reserved") || msg.contains("127.0.0.1"),
                    "unexpected message: {msg}"
                );
            }
            other => panic!("expected InvalidInput, got {other:?}"),
        }
    }

    #[tokio::test]
    async fn whois_refuses_rfc1918_server() {
        // Feeding an RFC1918 address must be rejected by validate_public_host
        // BEFORE any TCP connect is attempted.
        let err = query_server_internal("10.0.0.1", "example.com", Duration::from_secs(1))
            .await
            .expect_err("RFC1918 server must be rejected");
        match err {
            SeerError::InvalidInput(msg) => {
                assert!(
                    msg.contains("reserved") || msg.contains("10.0.0.1"),
                    "unexpected message: {msg}"
                );
            }
            other => panic!("expected InvalidInput, got {other:?}"),
        }
    }

    #[tokio::test]
    async fn whois_refuses_link_local_metadata_server() {
        // The cloud metadata address 169.254.169.254 must also be rejected.
        let err = query_server_internal("169.254.169.254", "example.com", Duration::from_secs(1))
            .await
            .expect_err("link-local metadata server must be rejected");
        assert!(matches!(err, SeerError::InvalidInput(_)));
    }

    // ---- deterministic mock-server tests -----------------------------------
    //
    // These run a real TCP listener on 127.0.0.1 and exercise the full client
    // path (connect → query → read-to-EOF → parse → referral logic) without
    // touching the network. The SSRF guards deliberately refuse loopback, so
    // the client under test uses the `#[cfg(test)]`-only `allowing_private_hosts`
    // / `with_port` seams, which do not exist in release builds.

    /// Serves one canned WHOIS response per accepted connection, in order,
    /// then stops accepting. Returns the bound port.
    async fn spawn_mock_whois(responses: Vec<&'static str>) -> u16 {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let port = listener.local_addr().unwrap().port();
        tokio::spawn(async move {
            for response in responses {
                let Ok((mut sock, _)) = listener.accept().await else {
                    return;
                };
                let mut buf = [0u8; 512];
                let _ = sock.read(&mut buf).await; // consume "domain\r\n"
                let _ = sock.write_all(response.as_bytes()).await;
                // drop(sock) → FIN → client reads to EOF
            }
        });
        port
    }

    fn mock_client(port: u16) -> WhoisClient {
        WhoisClient::new()
            .without_retries()
            .allowing_private_hosts()
            .with_port(port)
    }

    /// Like [`spawn_mock_whois`] but also captures the raw query line the
    /// client sent, so tests can assert what actually went over the wire.
    async fn spawn_mock_whois_capturing(
        response: &'static str,
    ) -> (u16, tokio::sync::oneshot::Receiver<String>) {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let port = listener.local_addr().unwrap().port();
        let (tx, rx) = tokio::sync::oneshot::channel();
        tokio::spawn(async move {
            let Ok((mut sock, _)) = listener.accept().await else {
                return;
            };
            let mut buf = [0u8; 512];
            let n = sock.read(&mut buf).await.unwrap_or(0);
            let _ = tx.send(String::from_utf8_lossy(&buf[..n]).into_owned());
            let _ = sock.write_all(response.as_bytes()).await;
        });
        (port, rx)
    }

    /// An IDN (U-label) domain must reach the wire as its punycode A-labels:
    /// port-43 registries are only required to accept ACE per RFC 3912/5891,
    /// and sending raw UTF-8 gets "no match" from most of them.
    #[tokio::test]
    async fn mock_idn_domain_is_queried_as_punycode() {
        let (port, rx) = spawn_mock_whois_capturing(
            "Domain Name: XN--E1AFMKFD.XN--P1AI\nRegistrar: Mock IDN Registrar\n",
        )
        .await;
        let resp = mock_client(port)
            .lookup_with_server("пример.рф", "127.0.0.1")
            .await
            .unwrap();
        assert_eq!(
            rx.await.unwrap(),
            "xn--e1afmkfd.xn--p1ai\r\n",
            "wire query must be the A-label form, never raw Unicode"
        );
        assert_eq!(resp.domain, "xn--e1afmkfd.xn--p1ai");
        assert_eq!(resp.registrar.as_deref(), Some("Mock IDN Registrar"));
    }

    #[tokio::test]
    async fn mock_basic_lookup_parses_canned_response() {
        let port = spawn_mock_whois(vec![
            "Domain Name: EXAMPLE.COM\nRegistrar: Mock Registrar Inc.\nCreation Date: 2020-01-01T00:00:00Z\n",
        ])
        .await;
        let resp = mock_client(port)
            .lookup_with_server("example.com", "127.0.0.1")
            .await
            .unwrap();
        assert_eq!(resp.registrar.as_deref(), Some("Mock Registrar Inc."));
    }

    #[tokio::test]
    async fn mock_referral_is_followed_when_registry_response_is_thin() {
        // Registry response (127.0.0.1) lacks core data and refers to
        // "localhost"; both names resolve to the same fixture, which serves
        // the responses in connection order.
        let port = spawn_mock_whois(vec![
            "Registry data follows.\nRegistrar WHOIS Server: localhost\n",
            "Domain Name: EXAMPLE.COM\nRegistrar: Mock Registrar Two\nCreation Date: 2021-02-02T00:00:00Z\n",
        ])
        .await;
        let client = mock_client(port);
        let mut visited = HashSet::new();
        let resp = client
            .lookup_with_referrals("example.com", "127.0.0.1", 0, &mut visited)
            .await
            .unwrap();
        assert_eq!(resp.registrar.as_deref(), Some("Mock Registrar Two"));
        assert_eq!(resp.whois_server, "localhost");
    }

    /// An undelegated domain's registry record (registrar, dates, status,
    /// but no nameservers) fails `has_core_data`, so the referral is
    /// followed. When the registrar answers with a throttle / refusal body
    /// instead of a record, the registry's data must be kept rather than
    /// replaced by an all-empty response.
    #[tokio::test]
    async fn mock_refusing_referral_does_not_replace_registry_data() {
        let port = spawn_mock_whois(vec![
            "Domain Name: EXAMPLE.COM\n\
             Registrar WHOIS Server: localhost\n\
             Registrar: Registry-Listed Registrar, Inc.\n\
             Creation Date: 2020-01-01T00:00:00Z\n\
             Registry Expiry Date: 2030-01-01T00:00:00Z\n\
             Domain Status: serverHold https://icann.org/epp#serverHold\n",
            "Your connection limit exceeded. Please slow down and try again later.\n",
        ])
        .await;
        let client = mock_client(port);
        let mut visited = HashSet::new();
        let resp = client
            .lookup_with_referrals("example.com", "127.0.0.1", 0, &mut visited)
            .await
            .unwrap();
        assert_eq!(
            resp.registrar.as_deref(),
            Some("Registry-Listed Registrar, Inc.")
        );
        assert!(resp.creation_date.is_some() && resp.expiration_date.is_some());
        assert_eq!(resp.status, vec!["serverHold"]);
        assert_eq!(resp.whois_server, "127.0.0.1", "registry response kept");
        assert!(
            visited.contains("localhost"),
            "the referral was still consulted"
        );
    }

    #[tokio::test]
    async fn mock_circular_referral_terminates_with_last_response() {
        // A (127.0.0.1) refers to B (localhost); B refers back to A, which is
        // already in the visited set. The chain must terminate gracefully —
        // returning B's response — instead of looping or erroring.
        let port = spawn_mock_whois(vec![
            "Registry data follows.\nRegistrar WHOIS Server: localhost\n",
            "Registrar data follows.\nRegistrar WHOIS Server: 127.0.0.1\n",
        ])
        .await;
        let client = mock_client(port);
        let mut visited = HashSet::new();
        let resp = client
            .lookup_with_referrals("example.com", "127.0.0.1", 0, &mut visited)
            .await
            .unwrap();
        assert_eq!(resp.whois_server, "localhost");
    }

    #[tokio::test]
    async fn mock_silent_server_times_out() {
        // Listener accepts but never writes: the read deadline must surface
        // as SeerError::Timeout rather than hanging.
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let port = listener.local_addr().unwrap().port();
        tokio::spawn(async move {
            let Ok((_sock, _)) = listener.accept().await else {
                return;
            };
            tokio::time::sleep(Duration::from_secs(10)).await;
        });
        let client = mock_client(port).with_timeout(Duration::from_millis(200));
        let err = client
            .lookup_with_server("example.com", "127.0.0.1")
            .await
            .unwrap_err();
        assert!(matches!(err, SeerError::Timeout(_)), "got: {err:?}");
    }

    /// Serves `responses` in connection order — `None` accepts and holds the
    /// connection silently — counting every accepted connection.
    async fn spawn_counting_whois(
        responses: Vec<Option<&'static str>>,
    ) -> (u16, std::sync::Arc<std::sync::atomic::AtomicUsize>) {
        use std::sync::atomic::{AtomicUsize, Ordering};
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let port = listener.local_addr().unwrap().port();
        let accepted = std::sync::Arc::new(AtomicUsize::new(0));
        let counter = accepted.clone();
        tokio::spawn(async move {
            let mut responses = responses.into_iter();
            while let Ok((mut sock, _)) = listener.accept().await {
                counter.fetch_add(1, Ordering::SeqCst);
                let response = responses.next().flatten();
                tokio::spawn(async move {
                    let mut buf = [0u8; 512];
                    let _ = sock.read(&mut buf).await;
                    match response {
                        Some(r) => {
                            let _ = sock.write_all(r.as_bytes()).await;
                        }
                        None => tokio::time::sleep(Duration::from_secs(10)).await,
                    }
                });
            }
        });
        (port, accepted)
    }

    /// Catalogued TLDs without port-43 service fail fast with
    /// `WhoisServerNotFound` — no IANA round trip (nothing listens on the
    /// mock "IANA" port, so a query would fail as a connection error).
    #[tokio::test]
    async fn catalogued_no_whois_tlds_short_circuit_before_discovery() {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let port = listener.local_addr().unwrap().port();
        drop(listener);
        let client = mock_client(port).with_iana_server("127.0.0.1");
        // RDAP-only, no-WHOIS (per IANA) and retired, in turn.
        for domain in ["example.app", "example.netflix", "example.mt"] {
            let err = client.lookup(domain).await.unwrap_err();
            assert!(
                matches!(err, SeerError::WhoisServerNotFound(_)),
                "{domain}: {err:?}"
            );
        }
        // A mapped second-level zone still wins over its server-less TLD.
        assert_eq!(
            get_whois_server_for_domain("example.co.za"),
            Some("whois.registry.net.za")
        );
    }

    /// IANA's definitive "no server" answer is negative-cached: the second
    /// lookup for the TLD does not query IANA again.
    #[tokio::test]
    async fn definitive_iana_no_server_answer_is_negative_cached() {
        use std::sync::atomic::Ordering;
        let (port, accepted) = spawn_counting_whois(vec![Some(
            "% IANA WHOIS server\n\ndomain:       SEERNEGCACHE\n\nstatus:       ACTIVE\n",
        )])
        .await;
        let client = mock_client(port).with_iana_server("127.0.0.1");
        for _ in 0..2 {
            let err = client.lookup("example.seernegcache").await.unwrap_err();
            assert!(matches!(err, SeerError::WhoisServerNotFound(_)), "{err:?}");
        }
        assert_eq!(
            accepted.load(Ordering::SeqCst),
            1,
            "second lookup hit the cache"
        );
    }

    /// A reply that is not an IANA record (throttle banner) is not a
    /// definitive answer, so it is not cached and the next lookup asks again.
    #[tokio::test]
    async fn non_definitive_iana_reply_is_not_cached() {
        use std::sync::atomic::Ordering;
        let (port, accepted) = spawn_counting_whois(vec![
            Some("% Query rate limit exceeded, try again later\n"),
            Some("% IANA WHOIS server\n\ndomain:       SEERTRANSIENT\n"),
        ])
        .await;
        let client = mock_client(port).with_iana_server("127.0.0.1");
        for _ in 0..3 {
            let err = client.lookup("example.seertransient").await.unwrap_err();
            assert!(matches!(err, SeerError::WhoisServerNotFound(_)), "{err:?}");
        }
        assert_eq!(
            accepted.load(Ordering::SeqCst),
            2,
            "the throttle reply was retried, the IANA record then cached"
        );
    }

    #[test]
    fn iana_record_detection() {
        assert!(is_iana_record(
            "domain:       COM\nwhois: whois.verisign-grs.com\n"
        ));
        assert!(is_iana_record("% This query returned 0 objects.\n"));
        assert!(!is_iana_record(""));
        assert!(!is_iana_record("% rate limit exceeded\n"));
    }

    /// A referral hop runs once, not under the registry's retry policy: the
    /// registry record is already in hand and is kept when the hop fails.
    #[tokio::test]
    async fn referral_hop_is_a_single_attempt() {
        use std::sync::atomic::Ordering;
        // Registry (127.0.0.1) answers thin with a referral to "localhost";
        // the referral target then accepts and never answers (a timeout,
        // which is retryable).
        let (port, accepted) = spawn_counting_whois(vec![
            Some("Domain Name: EXAMPLE.COM\nRegistrar WHOIS Server: localhost\n"),
            None,
            None,
            None,
        ])
        .await;
        let client = WhoisClient::new()
            .with_retry_policy(
                RetryPolicy::new()
                    .with_max_attempts(3)
                    .with_initial_delay(Duration::from_millis(1))
                    .with_jitter(false),
            )
            .allowing_private_hosts()
            .with_port(port)
            .with_timeout(Duration::from_millis(200));
        let mut visited = HashSet::new();
        let resp = client
            .lookup_with_referrals("example.com", "127.0.0.1", 0, &mut visited)
            .await
            .unwrap();
        assert_eq!(resp.whois_server, "127.0.0.1", "registry response kept");
        assert_eq!(
            accepted.load(Ordering::SeqCst),
            2,
            "one registry query plus a single referral attempt"
        );
    }

    /// An address that never answers (TEST-NET-1 is blackholed or unrouted)
    /// costs only its share of the budget; the next address still connects.
    #[tokio::test]
    async fn connect_moves_past_an_unresponsive_address_within_budget() {
        let listener = tokio::net::TcpListener::bind("127.0.0.1:0").await.unwrap();
        let live = listener.local_addr().unwrap();
        let addrs = vec![
            std::net::SocketAddr::new("192.0.2.1".parse().unwrap(), live.port()),
            live,
        ];
        let start = std::time::Instant::now();
        let stream = connect_ipv4_first("mock", addrs, Duration::from_secs(2))
            .await
            .expect("the live address connects");
        assert_eq!(stream.peer_addr().unwrap(), live);
        assert!(start.elapsed() < Duration::from_secs(2));
    }

    /// Registries whose port-43 servers need a non-bare query: DENIC returns
    /// only `Status: connect` without `-T dn,ace`, and JPRS responds in
    /// Japanese without the `/e` suffix.
    #[test]
    fn format_query_for_server_registry_specific() {
        assert_eq!(
            format_query_for_server("whois.denic.de", "example.de"),
            "-T dn,ace example.de"
        );
        assert_eq!(
            format_query_for_server("WHOIS.DENIC.DE", "example.de"),
            "-T dn,ace example.de",
            "server hostname match must be case-insensitive"
        );
        assert_eq!(
            format_query_for_server("whois.jprs.jp", "example.jp"),
            "example.jp/e"
        );
        assert_eq!(
            format_query_for_server("whois.verisign-grs.com", "example.com"),
            "example.com",
            "all other servers get the bare domain"
        );
    }
}