pata 0.0.1

A fast, lightweight, and evidence-driven email validation library for Rust
Documentation
use std::{fmt, time::Duration};

use crate::{Address, Mode, ParseErrorKind, PolicyKind};

mod finding;
mod status;

pub use finding::{Finding, FindingCode};
pub use status::{Certainty, DomainStatus, MailboxStatus, Outcome, Verdict};

/// Offline classification attached to an address.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
pub struct Classification {
    disposable: bool,
    role: bool,
    free_mail: bool,
    suggested_domain: Option<&'static str>,
}

impl Classification {
    /// Returns whether the domain is in the reviewed disposable set.
    #[must_use]
    pub const fn is_disposable(self) -> bool {
        self.disposable
    }

    /// Returns whether the local part conventionally names a role.
    #[must_use]
    pub const fn is_role(self) -> bool {
        self.role
    }

    /// Returns whether the domain is in the reviewed free-mail set.
    #[must_use]
    pub const fn is_free_mail(self) -> bool {
        self.free_mail
    }

    /// Returns a conservative provider-domain correction when one is known.
    #[must_use]
    pub const fn suggested_domain(self) -> Option<&'static str> {
        self.suggested_domain
    }

    #[cfg(feature = "classification")]
    pub(crate) const fn new(
        disposable: bool,
        role: bool,
        free_mail: bool,
        suggested_domain: Option<&'static str>,
    ) -> Self {
        Self {
            disposable,
            role,
            free_mail,
            suggested_domain,
        }
    }
}

/// Provenance for one validation report.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct ReportMetadata {
    mode: Mode,
    policy: PolicyKind,
    schema: u16,
    pata_version: &'static str,
    data_revision: Option<&'static str>,
    elapsed: Duration,
}

impl ReportMetadata {
    /// Returns the requested validation mode.
    #[must_use]
    pub const fn mode(&self) -> Mode {
        self.mode
    }

    /// Returns the policy that produced the report verdict.
    #[must_use]
    pub const fn policy(&self) -> PolicyKind {
        self.policy
    }

    /// Returns the report schema version.
    #[must_use]
    pub const fn schema(&self) -> u16 {
        self.schema
    }

    /// Returns the Pata package version.
    #[must_use]
    pub const fn pata_version(&self) -> &'static str {
        self.pata_version
    }

    /// Returns the compiled classification-data revision when enabled.
    #[must_use]
    pub const fn data_revision(&self) -> Option<&'static str> {
        self.data_revision
    }

    /// Returns the elapsed validation duration.
    #[must_use]
    pub const fn elapsed(&self) -> Duration {
        self.elapsed
    }

    pub(crate) const fn new(mode: Mode, policy: PolicyKind, elapsed: Duration) -> Self {
        Self {
            mode,
            policy,
            schema: 1,
            pata_version: env!("CARGO_PKG_VERSION"),
            data_revision: crate::classifier::REVISION,
            elapsed,
        }
    }
}

/// A complete email address validation result.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
pub struct Report {
    input: String,
    address: Option<Address>,
    parse_error: Option<ParseErrorKind>,
    verdict: Verdict,
    findings: Vec<Finding>,
    classification: Classification,
    domain_status: DomainStatus,
    mailbox_status: MailboxStatus,
    #[cfg(feature = "posture")]
    posture: Option<crate::DomainPosture>,
    metadata: ReportMetadata,
}

impl Report {
    /// Returns the original caller input.
    #[must_use]
    pub fn input(&self) -> &str {
        &self.input
    }

    /// Returns the parsed address, or `None` for malformed input.
    #[must_use]
    pub const fn address(&self) -> Option<&Address> {
        self.address.as_ref()
    }

    /// Returns the parsing failure category for malformed input.
    #[must_use]
    pub const fn parse_error(&self) -> Option<ParseErrorKind> {
        self.parse_error
    }

    /// Returns the policy verdict.
    #[must_use]
    pub const fn verdict(&self) -> Verdict {
        self.verdict
    }

    /// Returns ordered semantic findings.
    #[must_use]
    pub fn findings(&self) -> &[Finding] {
        &self.findings
    }

    /// Returns offline classification.
    #[must_use]
    pub const fn classification(&self) -> Classification {
        self.classification
    }

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

    /// Returns the SMTP recipient observation.
    #[must_use]
    pub const fn mailbox_status(&self) -> MailboxStatus {
        self.mailbox_status
    }

    /// Returns optional receiving-domain security posture.
    #[cfg(feature = "posture")]
    #[must_use]
    pub const fn posture(&self) -> Option<crate::DomainPosture> {
        self.posture
    }

    /// Returns report provenance.
    #[must_use]
    pub const fn metadata(&self) -> &ReportMetadata {
        &self.metadata
    }

    pub(crate) fn invalid(
        input: String,
        parse_error: ParseErrorKind,
        mode: Mode,
        policy: PolicyKind,
        elapsed: Duration,
    ) -> Self {
        Self {
            input,
            address: None,
            parse_error: Some(parse_error),
            verdict: Verdict::Invalid,
            findings: vec![Finding::new(
                FindingCode::SyntaxInvalid,
                Outcome::Fail,
                Certainty::Conclusive,
                "the input is not a valid mailbox address",
            )],
            classification: Classification::default(),
            domain_status: DomainStatus::NotChecked,
            mailbox_status: MailboxStatus::NotChecked,
            #[cfg(feature = "posture")]
            posture: None,
            metadata: ReportMetadata::new(mode, policy, elapsed),
        }
    }

    pub(crate) fn parsed(
        input: String,
        address: Address,
        findings: Vec<Finding>,
        classification: Classification,
        mode: Mode,
        policy: PolicyKind,
        elapsed: Duration,
    ) -> Self {
        Self {
            input,
            address: Some(address),
            parse_error: None,
            verdict: Verdict::Plausible,
            findings,
            classification,
            domain_status: DomainStatus::NotChecked,
            mailbox_status: MailboxStatus::NotChecked,
            #[cfg(feature = "posture")]
            posture: None,
            metadata: ReportMetadata::new(mode, policy, elapsed),
        }
    }

    pub(crate) fn set_verdict(&mut self, verdict: Verdict) {
        self.verdict = verdict;
    }

    pub(crate) fn set_elapsed(&mut self, elapsed: Duration) {
        self.metadata.elapsed = elapsed;
    }

    #[cfg(feature = "dns")]
    pub(crate) fn append_domain(&mut self, status: DomainStatus, finding: Finding) {
        self.domain_status = status;
        self.findings.push(finding);
    }

    #[cfg(feature = "smtp")]
    pub(crate) fn append_mailbox(&mut self, status: MailboxStatus, finding: Finding) {
        self.mailbox_status = status;
        self.findings.push(finding);
    }

    #[cfg(feature = "posture")]
    pub(crate) fn set_posture(&mut self, posture: crate::DomainPosture) {
        self.posture = Some(posture);
        self.findings.extend(crate::posture::findings(posture));
    }
}

impl fmt::Debug for Report {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter
            .debug_struct("Report")
            .field("address", &self.address)
            .field("parse_error", &self.parse_error)
            .field("verdict", &self.verdict)
            .field("findings", &self.findings)
            .field("classification", &self.classification)
            .field("domain_status", &self.domain_status)
            .field("mailbox_status", &self.mailbox_status)
            .field("posture", &{
                #[cfg(feature = "posture")]
                {
                    self.posture
                }
                #[cfg(not(feature = "posture"))]
                {
                    "disabled"
                }
            })
            .field("metadata", &self.metadata)
            .finish()
    }
}

#[cfg(test)]
mod tests {
    #[cfg(feature = "serde")]
    use futures_executor::block_on;

    use super::*;

    #[test]
    fn finding_codes_are_stable_and_human_readable() {
        assert_eq!(FindingCode::DomainNullMx.as_str(), "domain.null_mx");
        assert_eq!(FindingCode::SmtpAccepted.to_string(), "smtp.accepted");
    }

    #[test]
    fn metadata_reports_only_compiled_classification_data() {
        let metadata = ReportMetadata::new(Mode::Local, PolicyKind::Registration, Duration::ZERO);

        assert_eq!(metadata.policy(), PolicyKind::Registration);
        #[cfg(feature = "classification")]
        assert_eq!(metadata.data_revision(), Some("2026-08-13.1"));
        #[cfg(not(feature = "classification"))]
        assert_eq!(metadata.data_revision(), None);
    }

    #[cfg(feature = "serde")]
    #[test]
    fn serialization_is_explicit_and_machine_stable() {
        let report = block_on(crate::Validator::local().validate("maya@example.com"));
        let value = serde_json::to_value(report).unwrap();

        assert_eq!(value["verdict"], "plausible");
        assert_eq!(value["input"], "maya@example.com");
        assert_eq!(value["findings"][0]["code"], "syntax.valid");
        assert_eq!(value["metadata"]["policy"], "registration");
    }
}