pata 0.0.1

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

use crate::dns::Resolver;

#[cfg(feature = "runtime-portable")]
use crate::Result;

use crate::runtime::Timer;
#[cfg(feature = "smtp")]
use crate::runtime::{Connector, TlsConnector};

#[cfg(feature = "smtp")]
type SmtpRuntime<'a> = (
    &'a dyn Connector,
    &'a dyn Timer,
    Option<&'a dyn TlsConnector>,
);

mod cache;
#[cfg(feature = "runtime-portable")]
mod portable;

/// Runtime-neutral capabilities used by domain and mailbox validation.
///
/// Successful lookups are coalesced and cached by domain. Resolver TTLs are
/// capped at one hour. Without a TTL, successful routes remain for five minutes
/// and negative DNS results remain for one minute. Route and TXT caches
/// each retain at most 4,096 domains.
#[derive(Clone)]
pub struct Network {
    resolver: Arc<dyn Resolver>,
    timer: Arc<dyn Timer>,
    #[cfg(feature = "smtp")]
    connector: Option<Arc<dyn Connector>>,
    #[cfg(feature = "smtp")]
    tls: Option<Arc<dyn TlsConnector>>,
}

impl Network {
    /// Creates a network from caller-supplied DNS and deadline capabilities.
    #[must_use]
    pub fn new(resolver: impl Resolver + 'static, timer: impl Timer + 'static) -> Self {
        Self {
            resolver: Arc::new(cache::CachedResolver::new(resolver)),
            timer: Arc::new(timer),
            #[cfg(feature = "smtp")]
            connector: None,
            #[cfg(feature = "smtp")]
            tls: None,
        }
    }

    /// Creates a network with caller-supplied DNS, TCP, and timer capabilities.
    #[cfg(feature = "smtp")]
    #[must_use]
    pub fn with_runtime(
        resolver: impl Resolver + 'static,
        connector: impl Connector + 'static,
        timer: impl Timer + 'static,
    ) -> Self {
        Self {
            resolver: Arc::new(cache::CachedResolver::new(resolver)),
            timer: Arc::new(timer),
            connector: Some(Arc::new(connector)),
            tls: None,
        }
    }

    /// Adds an authenticated TLS upgrader to caller-supplied capabilities.
    #[cfg(feature = "smtp")]
    #[must_use]
    pub fn with_tls(mut self, tls: impl TlsConnector + 'static) -> Self {
        self.tls = Some(Arc::new(tls));
        self
    }

    /// Creates the portable network backed by operating-system DNS settings.
    ///
    /// The first call starts one shared DNS worker thread that remains for the
    /// process lifetime.
    #[cfg(feature = "runtime-portable")]
    pub fn system() -> Result<Self> {
        portable::network()
    }

    pub(crate) fn resolver(&self) -> &dyn Resolver {
        self.resolver.as_ref()
    }

    pub(crate) fn timer(&self) -> &dyn Timer {
        self.timer.as_ref()
    }

    #[cfg(feature = "smtp")]
    pub(crate) fn has_tls(&self) -> bool {
        self.tls.is_some()
    }

    #[cfg(feature = "smtp")]
    pub(crate) fn smtp(&self) -> Option<SmtpRuntime<'_>> {
        Some((
            self.connector.as_deref()?,
            self.timer.as_ref(),
            self.tls.as_deref(),
        ))
    }
}

impl fmt::Debug for Network {
    fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
        formatter.debug_struct("Network").finish_non_exhaustive()
    }
}

#[cfg(feature = "smtp")]
pub(crate) fn is_public(address: std::net::IpAddr) -> bool {
    match address {
        std::net::IpAddr::V4(address) => {
            let octets = address.octets();
            !(address.is_private()
                || address.is_loopback()
                || address.is_link_local()
                || address.is_broadcast()
                || address.is_documentation()
                || address.is_unspecified()
                || address.is_multicast()
                || octets[0] == 0
                || octets[0] == 100 && (64..=127).contains(&octets[1])
                || octets[0] == 192 && octets[1] == 0 && octets[2] == 0
                || octets[0] == 192 && octets[1] == 88 && octets[2] == 99
                || octets[0] == 198 && (18..=19).contains(&octets[1])
                || octets[0] >= 240)
        }
        std::net::IpAddr::V6(address) => {
            if let Some(mapped) = address.to_ipv4_mapped() {
                return is_public(mapped.into());
            }
            let segments = address.segments();
            !(address.is_loopback()
                || address.is_unspecified()
                || address.is_multicast()
                || address.is_unique_local()
                || address.is_unicast_link_local()
                || segments[0] & 0xe000 != 0x2000
                || segments[0] & 0xffc0 == 0xfec0
                || segments[..6] == [0, 0, 0, 0, 0, 0]
                || segments[0] == 0x2002
                || segments[0] == 0x2001
                    && (segments[1] == 0
                        || segments[1] == 2 && segments[2] == 0
                        || segments[1] & 0xfff0 == 0x0010
                        || segments[1] & 0xfff0 == 0x0020
                        || segments[1] == 0x0db8
                        || segments[1] & 0xfff0 == 0x3ff0))
        }
    }
}