pata 0.0.1

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

use super::{Certainty, Outcome};

/// A stable machine-readable finding identifier.
#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
#[non_exhaustive]
pub enum FindingCode {
    /// The address matches Pata's supported mailbox grammar.
    SyntaxValid,
    /// The address does not match Pata's supported mailbox grammar.
    SyntaxInvalid,
    /// The local part requires SMTPUTF8.
    SyntaxNonAsciiLocalPart,
    /// The address uses a domain literal.
    SyntaxDomainLiteral,
    /// The Unicode domain mixes scripts.
    UnicodeMixedScript,
    /// The Unicode local part is not in NFC.
    UnicodeLocalPartNotNormalized,
    /// The domain belongs to a disposable-mail service.
    ClassificationDisposable,
    /// The local part conventionally identifies a role.
    ClassificationRole,
    /// The domain belongs to a free-mail provider.
    ClassificationFreeMail,
    /// The domain resembles a common provider-domain typo.
    ClassificationTypo,
    /// A caller-owned allow rule matched the domain.
    PolicyAllowed,
    /// A caller-owned deny rule matched the domain.
    PolicyDenied,
    /// The domain does not exist.
    DomainNxDomain,
    /// The domain explicitly advertises Null MX.
    DomainNullMx,
    /// The domain advertises at least one MX route.
    DomainMx,
    /// The domain uses RFC 5321 implicit MX fallback.
    DomainImplicitMx,
    /// No usable mail route exists.
    DomainNoMailRoute,
    /// The DNS lookup did not return a conclusive result.
    DomainLookupUnavailable,
    /// The SMTP server accepted the recipient at observation time.
    SmtpAccepted,
    /// The SMTP server rejected the recipient permanently.
    SmtpRecipientRejected,
    /// The SMTP server reported a disabled mailbox.
    SmtpMailboxDisabled,
    /// The SMTP server reported a full mailbox.
    SmtpMailboxFull,
    /// The SMTP server applied greylisting.
    SmtpGreylisted,
    /// The SMTP server rate-limited the probe.
    SmtpRateLimited,
    /// The SMTP observation failed transiently.
    SmtpTemporaryFailure,
    /// The SMTP server rejected the transaction, but not the recipient.
    SmtpProbeRejected,
    /// The SMTP server blocked recipient probing by policy.
    SmtpPolicyBlocked,
    /// The server does not support required SMTPUTF8 delivery.
    SmtpRequiresSmtpUtf8,
    /// The domain accepted a generated recipient probe.
    SmtpCatchAll,
    /// The domain rejected a generated recipient probe.
    SmtpCatchAllRejected,
    /// Catch-all behavior could not be established.
    SmtpCatchAllUnknown,
    /// SPF publication was inspected.
    PostureSpf,
    /// DMARC publication was inspected.
    PostureDmarc,
    /// MTA-STS publication was inspected.
    PostureMtaSts,
    /// SMTP TLS reporting publication was inspected.
    PostureTlsRpt,
}

impl FindingCode {
    /// Returns the stable dotted representation.
    #[must_use]
    pub const fn as_str(self) -> &'static str {
        match self {
            Self::SyntaxValid => "syntax.valid",
            Self::SyntaxInvalid => "syntax.invalid",
            Self::SyntaxNonAsciiLocalPart => "syntax.non_ascii_local_part",
            Self::SyntaxDomainLiteral => "syntax.domain_literal",
            Self::UnicodeMixedScript => "unicode.mixed_script",
            Self::UnicodeLocalPartNotNormalized => "unicode.local_part_not_normalized",
            Self::ClassificationDisposable => "classification.disposable",
            Self::ClassificationRole => "classification.role",
            Self::ClassificationFreeMail => "classification.free_mail",
            Self::ClassificationTypo => "classification.typo",
            Self::PolicyAllowed => "policy.allowed",
            Self::PolicyDenied => "policy.denied",
            Self::DomainNxDomain => "domain.nxdomain",
            Self::DomainNullMx => "domain.null_mx",
            Self::DomainMx => "domain.mx",
            Self::DomainImplicitMx => "domain.implicit_mx",
            Self::DomainNoMailRoute => "domain.no_mail_route",
            Self::DomainLookupUnavailable => "domain.lookup_unavailable",
            Self::SmtpAccepted => "smtp.accepted",
            Self::SmtpRecipientRejected => "smtp.recipient_rejected",
            Self::SmtpMailboxDisabled => "smtp.mailbox_disabled",
            Self::SmtpMailboxFull => "smtp.mailbox_full",
            Self::SmtpGreylisted => "smtp.greylisted",
            Self::SmtpRateLimited => "smtp.rate_limited",
            Self::SmtpTemporaryFailure => "smtp.temporary_failure",
            Self::SmtpProbeRejected => "smtp.probe_rejected",
            Self::SmtpPolicyBlocked => "smtp.policy_blocked",
            Self::SmtpRequiresSmtpUtf8 => "smtp.requires_smtputf8",
            Self::SmtpCatchAll => "smtp.catch_all",
            Self::SmtpCatchAllRejected => "smtp.catch_all_rejected",
            Self::SmtpCatchAllUnknown => "smtp.catch_all_unknown",
            Self::PostureSpf => "posture.spf",
            Self::PostureDmarc => "posture.dmarc",
            Self::PostureMtaSts => "posture.mta_sts",
            Self::PostureTlsRpt => "posture.tls_rpt",
        }
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for FindingCode {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        serializer.serialize_str(self.as_str())
    }
}

impl fmt::Display for FindingCode {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.write_str(self.as_str())
    }
}

/// One semantic observation retained in a report.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Debug, Eq, PartialEq)]
pub struct Finding {
    code: FindingCode,
    outcome: Outcome,
    certainty: Certainty,
    summary: &'static str,
}

impl Finding {
    pub(crate) const fn new(
        code: FindingCode,
        outcome: Outcome,
        certainty: Certainty,
        summary: &'static str,
    ) -> Self {
        Self {
            code,
            outcome,
            certainty,
            summary,
        }
    }

    /// Returns the stable finding code.
    #[must_use]
    pub const fn code(&self) -> FindingCode {
        self.code
    }

    /// Returns the finding outcome.
    #[must_use]
    pub const fn outcome(&self) -> Outcome {
        self.outcome
    }

    /// Returns the finding certainty.
    #[must_use]
    pub const fn certainty(&self) -> Certainty {
        self.certainty
    }

    /// Returns a short human-facing explanation.
    #[must_use]
    pub const fn summary(&self) -> &'static str {
        self.summary
    }
}