pata 0.0.1

A fast, lightweight, and evidence-driven email validation library for Rust
Documentation
//! Redaction-safe network readiness diagnostics.

use crate::{DomainStatus, Network, dns::ResolutionKind};

/// A no-recipient diagnostic of DNS routes and configured SMTP capabilities.
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct NetworkDiagnostics {
    domain: DomainStatus,
    public_destinations: usize,
    blocked_destinations: usize,
    smtp_configured: bool,
    tls_configured: bool,
}

impl NetworkDiagnostics {
    /// Returns the mail-routing conclusion.
    #[must_use]
    pub const fn domain_status(&self) -> DomainStatus {
        self.domain
    }

    /// Returns the number of public resolved SMTP destinations.
    #[must_use]
    pub const fn public_destinations(&self) -> usize {
        self.public_destinations
    }

    /// Returns the number of destinations rejected by the network safety policy.
    #[must_use]
    pub const fn blocked_destinations(&self) -> usize {
        self.blocked_destinations
    }

    /// Returns whether TCP and timer capabilities are configured.
    #[must_use]
    pub const fn smtp_configured(&self) -> bool {
        self.smtp_configured
    }

    /// Returns whether authenticated STARTTLS is configured.
    #[must_use]
    pub const fn tls_configured(&self) -> bool {
        self.tls_configured
    }
}

impl Network {
    /// Resolves one domain and audits route safety without disclosing a mailbox.
    pub async fn diagnose(&self, domain: impl AsRef<str>) -> NetworkDiagnostics {
        self.diagnose_with_timeout(domain, std::time::Duration::from_secs(5))
            .await
    }

    /// Resolves one domain with an explicit total deadline.
    pub async fn diagnose_with_timeout(
        &self,
        domain: impl AsRef<str>,
        timeout: std::time::Duration,
    ) -> NetworkDiagnostics {
        let smtp = self.smtp();
        let (smtp_configured, tls_configured) = match smtp {
            Some((_, _, tls)) => (true, tls.is_some()),
            None => (false, false),
        };
        let unavailable = || NetworkDiagnostics {
            domain: DomainStatus::Unknown,
            public_destinations: 0,
            blocked_destinations: 0,
            smtp_configured,
            tls_configured,
        };
        let domain = domain.as_ref();
        if timeout.is_zero() || std::time::Instant::now().checked_add(timeout).is_none() {
            return unavailable();
        }
        let normalized = crate::Domain::parse(domain)
            .ok()
            .filter(|domain| !domain.is_literal())
            .map(|domain| domain.ascii().to_owned());
        let Some(normalized) = normalized else {
            return unavailable();
        };
        let Ok(Ok(resolution)) =
            crate::runtime::timeout(self.timer(), timeout, self.resolver().resolve(&normalized))
                .await
        else {
            return unavailable();
        };
        let domain = match resolution.kind() {
            ResolutionKind::Mx => DomainStatus::MailExchanger,
            ResolutionKind::ImplicitMx => DomainStatus::ImplicitMailExchanger,
            ResolutionKind::NullMx => DomainStatus::NullMx,
            ResolutionKind::NxDomain => DomainStatus::NxDomain,
            ResolutionKind::NoMailRoute => DomainStatus::NoMailRoute,
        };
        let (public_destinations, blocked_destinations) = resolution
            .exchanges()
            .iter()
            .flat_map(|exchange| exchange.addresses())
            .fold((0, 0), |(public, blocked), address| {
                if crate::network::is_public(*address) {
                    (public + 1, blocked)
                } else {
                    (public, blocked + 1)
                }
            });
        NetworkDiagnostics {
            domain,
            public_destinations,
            blocked_destinations,
            smtp_configured,
            tls_configured,
        }
    }
}