Skip to main content

dispocheck/
lib.rs

1//! # disposable-email-domains
2//!
3//! Fast, dependency-light checking of disposable / temporary email domains,
4//! built from the community-maintained
5//! [`disposable-email-domains/disposable-email-domains`](https://github.com/disposable-email-domains/disposable-email-domains)
6//! dataset (CC0-licensed, ~8,000 domains and growing).
7//!
8//! The domain list is embedded at **compile time** as a perfect hash set
9//! ([`phf`](https://docs.rs/phf)), so lookups are `O(1)`, allocation-light,
10//! and require no filesystem or network access at runtime.
11//!
12//! ```
13//! use dispocheck::is_disposable_email;
14//!
15//! assert!(is_disposable_email("someone@mailinator.com"));
16//! assert!(!is_disposable_email("someone@gmail.com"));
17//! ```
18//!
19//! ## Subdomain matching
20//!
21//! The upstream list stores second-level (or, for public-suffix domains,
22//! third-level) domains. A blocked entry also blocks any subdomain of it,
23//! e.g. if `mailinator.com` is listed, `foo.mailinator.com` is also treated
24//! as disposable:
25//!
26//! ```
27//! use dispocheck::is_disposable_domain;
28//!
29//! assert!(is_disposable_domain("sub.mailinator.com"));
30//! ```
31//!
32//! ## Custom / runtime lists
33//!
34//! If you need to merge the embedded list with your own domains, or refresh
35//! the list at runtime without recompiling, use `Blocklist` (requires the
36//! default `std` feature).
37//!
38//! ## Freshness
39//!
40//! The upstream dataset changes daily. This crate's embedded list is
41//! refreshed and republished automatically by CI — see the crate's
42//! repository for the update cadence and the exact upstream commit each
43//! release was built from (recorded in `data/SOURCE_COMMIT`).
44#![cfg_attr(not(feature = "std"), no_std)]
45#![deny(missing_docs)]
46#![warn(clippy::all)]
47
48extern crate alloc;
49
50use alloc::string::String;
51use alloc::vec::Vec;
52
53#[cfg(feature = "std")]
54extern crate std;
55
56include!(concat!(env!("OUT_DIR"), "/blocklist_data.rs"));
57
58/// Returns `true` if `email`'s domain (or one of its parent domains) is a
59/// known disposable/temporary email domain.
60///
61/// Matching is case-insensitive. Malformed input (no `@`, empty domain)
62/// returns `false` rather than erroring, since callers typically validate
63/// email *syntax* separately (e.g. with a dedicated email-parsing crate)
64/// before checking disposability.
65///
66/// # Examples
67///
68/// ```
69/// use dispocheck::is_disposable_email;
70///
71/// assert!(is_disposable_email("test@mailinator.com"));
72/// assert!(is_disposable_email("Test@Mailinator.COM")); // case-insensitive
73/// assert!(!is_disposable_email("test@company.com"));
74/// assert!(!is_disposable_email("not-an-email"));
75/// ```
76pub fn is_disposable_email(email: &str) -> bool {
77    match email.rsplit_once('@') {
78        Some((_, domain)) if !domain.is_empty() => is_disposable_domain(domain),
79        _ => false,
80    }
81}
82
83/// Returns `true` if `domain`, or any of its parent domains, is a known
84/// disposable/temporary email domain.
85///
86/// For example, if `mailinator.com` is in the blocklist, both
87/// `mailinator.com` and `anything.mailinator.com` return `true`.
88///
89/// Matching is case-insensitive and tolerant of a single trailing dot
90/// (as in a fully-qualified domain name).
91///
92/// # Examples
93///
94/// ```
95/// use dispocheck::is_disposable_domain;
96///
97/// assert!(is_disposable_domain("mailinator.com"));
98/// assert!(is_disposable_domain("deeply.nested.mailinator.com"));
99/// assert!(!is_disposable_domain("example.com"));
100/// ```
101pub fn is_disposable_domain(domain: &str) -> bool {
102    let normalized = normalize(domain);
103    if normalized.is_empty() {
104        return false;
105    }
106    domain_suffixes(&normalized).any(|suffix| BLOCKLIST.contains(suffix))
107}
108
109/// Returns the total number of domains in the embedded blocklist.
110///
111/// # Examples
112///
113/// ```
114/// assert!(dispocheck::len() > 1000);
115/// ```
116pub fn len() -> usize {
117    DOMAIN_COUNT
118}
119
120/// Returns `true` if the embedded blocklist is empty. Always `false` in
121/// practice; the build script refuses to compile an implausibly small list.
122pub fn is_empty() -> bool {
123    DOMAIN_COUNT == 0
124}
125
126/// Returns an iterator over every domain in the embedded blocklist.
127///
128/// Iteration order is unspecified.
129pub fn iter() -> impl Iterator<Item = &'static &'static str> {
130    BLOCKLIST.into_iter()
131}
132
133/// Lowercases and trims a domain, stripping a single trailing dot (FQDN
134/// notation).
135fn normalize(domain: &str) -> String {
136    let trimmed = domain.trim().trim_end_matches('.');
137    trimmed.to_lowercase()
138}
139
140/// Iterator over `domain` and each of its parent domains, most-specific
141/// first, stopping before the bare top-level domain — matching the
142/// suffix-walk algorithm documented by the upstream dataset.
143fn domain_suffixes(domain: &str) -> impl Iterator<Item = &str> {
144    let parts: Vec<&str> = domain.split('.').collect();
145    let len = parts.len();
146    (0..len.saturating_sub(1)).map(move |i| {
147        let start: usize = parts[..i].iter().map(|p| p.len() + 1).sum();
148        &domain[start..]
149    })
150}
151
152#[cfg(feature = "std")]
153mod runtime;
154#[cfg(feature = "std")]
155pub use runtime::Blocklist;