pata 0.0.1

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

/// How far one validation proceeds.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum Mode {
    /// Parse and classify the address without network I/O.
    #[default]
    Local,
    /// Inspect DNS existence and mail routing after local validation.
    Domain,
    /// Observe a receiving SMTP server after domain validation.
    Mailbox,
}

/// Whether Pata performs a generated-recipient catch-all check.
#[cfg(feature = "smtp")]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum CatchAll {
    /// Probe only the requested recipient.
    #[default]
    Disabled,
    /// Probe one generated address after the requested recipient is accepted.
    OneProbe,
}

/// STARTTLS behavior for mailbox observation.
#[cfg(feature = "smtp")]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[derive(Clone, Copy, Debug, Default, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum TlsPolicy {
    /// Upgrade when STARTTLS and an authenticated TLS capability are available.
    /// Continue without TLS only when no upgrade is available. Stop if an
    /// advertised upgrade fails so the probe cannot silently downgrade.
    #[default]
    Opportunistic,
    /// Stop before disclosing the address unless authenticated TLS succeeds.
    Required,
}

/// Safety and behavior controls for SMTP recipient observation.
#[cfg(feature = "smtp")]
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct SmtpPolicy {
    tls: TlsPolicy,
    catch_all: CatchAll,
}

#[cfg(feature = "smtp")]
impl SmtpPolicy {
    /// Returns the STARTTLS behavior.
    #[must_use]
    pub const fn tls(self) -> TlsPolicy {
        self.tls
    }

    /// Returns the catch-all behavior.
    #[must_use]
    pub const fn catch_all(self) -> CatchAll {
        self.catch_all
    }

    /// Replaces the STARTTLS behavior.
    #[must_use]
    pub const fn with_tls(mut self, tls: TlsPolicy) -> Self {
        self.tls = tls;
        self
    }

    /// Replaces the catch-all behavior.
    #[must_use]
    pub const fn with_catch_all(mut self, catch_all: CatchAll) -> Self {
        self.catch_all = catch_all;
        self
    }
}

#[cfg(feature = "smtp")]
impl Default for SmtpPolicy {
    fn default() -> Self {
        Self {
            tls: TlsPolicy::Opportunistic,
            catch_all: CatchAll::Disabled,
        }
    }
}

/// Resource bounds applied by a validator.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Limits {
    input_bytes: usize,
    concurrent_validations: usize,
}

impl Limits {
    /// The largest supported batch concurrency limit.
    pub const MAX_CONCURRENT_VALIDATIONS: usize = 1_024;

    /// Replaces the maximum accepted input length with a stricter bound.
    #[must_use]
    pub const fn with_input_bytes(mut self, input_bytes: usize) -> Self {
        self.input_bytes = input_bytes;
        self
    }

    /// Replaces the maximum number of concurrent batch validations.
    #[must_use]
    pub const fn with_concurrent_validations(mut self, concurrent_validations: usize) -> Self {
        self.concurrent_validations = concurrent_validations;
        self
    }

    /// The maximum accepted input length.
    #[must_use]
    pub const fn input_bytes(self) -> usize {
        self.input_bytes
    }

    /// Returns the maximum number of concurrent batch validations.
    #[must_use]
    pub const fn concurrent_validations(self) -> usize {
        self.concurrent_validations
    }
}

impl Default for Limits {
    fn default() -> Self {
        Self {
            input_bytes: crate::Address::MAX_INPUT_BYTES,
            concurrent_validations: 16,
        }
    }
}

/// Time bounds applied to network validation stages.
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Copy, Debug, Eq, PartialEq)]
pub struct Timeouts {
    dns: Duration,
    connect: Duration,
    command: Duration,
    total: Duration,
}

impl Timeouts {
    /// Replaces the DNS lookup timeout.
    #[must_use]
    pub const fn with_dns(mut self, dns: Duration) -> Self {
        self.dns = dns;
        self
    }

    /// Replaces the TCP connection timeout.
    #[must_use]
    pub const fn with_connect(mut self, connect: Duration) -> Self {
        self.connect = connect;
        self
    }

    /// Replaces the timeout for one SMTP command.
    #[must_use]
    pub const fn with_command(mut self, command: Duration) -> Self {
        self.command = command;
        self
    }

    /// Replaces the total validation timeout.
    #[must_use]
    pub const fn with_total(mut self, total: Duration) -> Self {
        self.total = total;
        self
    }

    /// Returns the DNS lookup timeout.
    #[must_use]
    pub const fn dns(self) -> Duration {
        self.dns
    }

    /// Returns the TCP connection timeout.
    #[must_use]
    pub const fn connect(self) -> Duration {
        self.connect
    }

    /// Returns the timeout for one SMTP command.
    #[must_use]
    pub const fn command(self) -> Duration {
        self.command
    }

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

impl Default for Timeouts {
    fn default() -> Self {
        Self {
            dns: Duration::from_secs(3),
            connect: Duration::from_secs(5),
            command: Duration::from_secs(5),
            total: Duration::from_secs(15),
        }
    }
}