pata 0.0.1

A fast, lightweight, and evidence-driven email validation library for Rust
Documentation
use super::Validator;
use crate::Report;

#[cfg(feature = "dns")]
use crate::{Certainty, DomainStatus, Finding, FindingCode, Mode, Outcome, dns::ResolutionKind};

impl Validator {
    pub(super) async fn check_network(&self, report: &mut Report) {
        #[cfg(feature = "dns")]
        if let Some(network) = self.network.as_ref() {
            if crate::runtime::timeout(
                network.timer(),
                self.timeouts.total(),
                self.run_network_checks(report),
            )
            .await
            .is_err()
            {
                self.record_timeout(report);
            }
            return;
        }
        self.run_network_checks(report).await;
    }

    #[cfg(feature = "dns")]
    fn record_timeout(&self, report: &mut Report) {
        if report.domain_status() == DomainStatus::NotChecked {
            report.append_domain(
                DomainStatus::Unknown,
                Finding::new(
                    FindingCode::DomainLookupUnavailable,
                    Outcome::Unknown,
                    Certainty::Strong,
                    "the total validation deadline expired during DNS analysis",
                ),
            );
        }
        #[cfg(feature = "smtp")]
        if self.mode == Mode::Mailbox && report.mailbox_status() == crate::MailboxStatus::NotChecked
        {
            report.append_mailbox(
                crate::MailboxStatus::Unknown,
                Finding::new(
                    FindingCode::SmtpTemporaryFailure,
                    Outcome::Unknown,
                    Certainty::Strong,
                    "the total validation deadline expired during SMTP observation",
                ),
            );
        }
        #[cfg(feature = "posture")]
        if self.posture && report.posture().is_none() {
            report.set_posture(crate::DomainPosture::unavailable());
        }
    }

    async fn run_network_checks(&self, report: &mut Report) {
        #[cfg(not(feature = "dns"))]
        let _ = report;
        #[cfg(feature = "dns")]
        if self.mode != Mode::Local
            && let Some(address) = report.address().cloned()
        {
            if address.domain().is_literal() {
                report.append_domain(
                    DomainStatus::Unknown,
                    Finding::new(
                        FindingCode::DomainLookupUnavailable,
                        Outcome::Unknown,
                        Certainty::Conclusive,
                        "address literals are not sent to public DNS",
                    ),
                );
                return;
            }
            let domain = address.domain().ascii().to_owned();
            #[cfg(feature = "smtp")]
            let resolution = self.check_domain(report, &domain).await;
            #[cfg(not(feature = "smtp"))]
            self.check_domain(report, &domain).await;
            #[cfg(feature = "smtp")]
            self.observe_mailbox(report, &address, resolution.as_ref())
                .await;
            #[cfg(feature = "posture")]
            if self.posture
                && let Some(network) = self.network.as_ref()
            {
                report.set_posture(
                    crate::posture::inspect(network, &domain, self.timeouts.dns()).await,
                );
            }
        }
    }

    #[cfg(feature = "smtp")]
    async fn observe_mailbox(
        &self,
        report: &mut Report,
        address: &crate::Address,
        resolution: Option<&crate::dns::Resolution>,
    ) {
        if self.mode != Mode::Mailbox {
            return;
        }
        let Some(resolution) = resolution else { return };
        let Some(identity) = self.probe_identity.as_deref() else {
            return;
        };
        let Some(network) = self.network.as_ref() else {
            return;
        };
        let Some((connector, timer, tls)) = network.smtp() else {
            return;
        };
        if !matches!(
            resolution.kind(),
            ResolutionKind::Mx | ResolutionKind::ImplicitMx
        ) {
            return;
        }
        let observation = crate::smtp::probe(
            crate::smtp::Capabilities {
                connector,
                timer,
                tls,
            },
            crate::smtp::Probe {
                routes: resolution,
                address,
                identity,
                policy: self.smtp_policy,
                timeouts: self.timeouts,
            },
        )
        .await;
        for finding in observation.findings {
            report.append_mailbox(observation.status, finding);
        }
    }

    #[cfg(feature = "dns")]
    async fn check_domain(
        &self,
        report: &mut Report,
        domain: &str,
    ) -> Option<crate::dns::Resolution> {
        let network = self.network.as_ref()?;
        let resolved = crate::runtime::timeout(
            network.timer(),
            self.timeouts.dns(),
            network.resolver().resolve(domain),
        )
        .await
        .unwrap_or_else(|_| {
            Err(crate::dns::ResolveError::new(
                crate::dns::ResolveErrorKind::Timeout,
                "DNS lookup exceeded its deadline",
            ))
        });
        match resolved {
            Ok(resolution) => {
                append_resolution(report, resolution.kind());
                Some(resolution)
            }
            Err(_) => {
                report.append_domain(
                    DomainStatus::Unknown,
                    Finding::new(
                        FindingCode::DomainLookupUnavailable,
                        Outcome::Unknown,
                        Certainty::Strong,
                        "the DNS lookup did not return a conclusive result",
                    ),
                );
                None
            }
        }
    }
}

#[cfg(feature = "dns")]
fn append_resolution(report: &mut Report, kind: ResolutionKind) {
    let (status, code, outcome, summary) = match kind {
        ResolutionKind::Mx => (
            DomainStatus::MailExchanger,
            FindingCode::DomainMx,
            Outcome::Pass,
            "the domain advertises a mail exchanger",
        ),
        ResolutionKind::ImplicitMx => (
            DomainStatus::ImplicitMailExchanger,
            FindingCode::DomainImplicitMx,
            Outcome::Pass,
            "the domain has an implicit RFC 5321 mail route",
        ),
        ResolutionKind::NullMx => (
            DomainStatus::NullMx,
            FindingCode::DomainNullMx,
            Outcome::Fail,
            "the domain explicitly declines email with Null MX",
        ),
        ResolutionKind::NxDomain => (
            DomainStatus::NxDomain,
            FindingCode::DomainNxDomain,
            Outcome::Fail,
            "the domain does not exist",
        ),
        ResolutionKind::NoMailRoute => (
            DomainStatus::NoMailRoute,
            FindingCode::DomainNoMailRoute,
            Outcome::Fail,
            "the domain has no usable mail route",
        ),
    };
    report.append_domain(
        status,
        Finding::new(code, outcome, Certainty::Conclusive, summary),
    );
}