use std::{fmt, hash::Hash, net::IpAddr};
use thiserror::Error;
const MAILBOX_MAX_OCTETS: usize = 254;
const INPUT_MAX_BYTES: usize = 1_024;
const LOCAL_PART_MAX_OCTETS: usize = 64;
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[cfg_attr(feature = "serde", serde(rename_all = "snake_case"))]
#[derive(Clone, Copy, Debug, Eq, Hash, PartialEq)]
#[non_exhaustive]
pub enum ParseErrorKind {
Empty,
TooLong,
InvalidSyntax,
LocalPartTooLong,
InvalidDomain,
}
#[derive(Clone, Copy, Debug, Eq, Error, Hash, PartialEq)]
#[error("email address is invalid: {kind}")]
pub struct ParseError {
kind: ParseErrorKind,
}
impl ParseError {
#[must_use]
pub const fn kind(self) -> ParseErrorKind {
self.kind
}
const fn new(kind: ParseErrorKind) -> Self {
Self { kind }
}
}
impl fmt::Display for ParseErrorKind {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(match self {
Self::Empty => "empty input",
Self::TooLong => "input exceeds its length limit",
Self::InvalidSyntax => "invalid mailbox syntax",
Self::LocalPartTooLong => "local part exceeds its octet limit",
Self::InvalidDomain => "invalid domain",
})
}
}
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone)]
pub struct Domain {
display: String,
ascii: String,
literal: Option<IpAddr>,
}
impl Domain {
#[cfg(feature = "diagnostics")]
pub(crate) fn parse(input: &str) -> Result<Self, ParseError> {
if input.len() > INPUT_MAX_BYTES {
return Err(ParseError::new(ParseErrorKind::TooLong));
}
parse_domain(input)
}
#[must_use]
pub fn display(&self) -> &str {
&self.display
}
#[must_use]
pub fn ascii(&self) -> &str {
&self.ascii
}
#[must_use]
pub const fn literal(&self) -> Option<IpAddr> {
self.literal
}
#[must_use]
pub const fn is_literal(&self) -> bool {
self.literal.is_some()
}
}
impl fmt::Debug for Domain {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Domain")
.field("display", &self.display)
.field("ascii", &self.ascii)
.field("literal", &self.literal)
.finish()
}
}
impl fmt::Display for Domain {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter.write_str(&self.display)
}
}
impl PartialEq for Domain {
fn eq(&self, other: &Self) -> bool {
self.ascii == other.ascii && self.literal == other.literal
}
}
impl Eq for Domain {}
impl Hash for Domain {
fn hash<H: std::hash::Hasher>(&self, state: &mut H) {
self.ascii.hash(state);
self.literal.hash(state);
}
}
#[cfg_attr(feature = "serde", derive(serde::Serialize))]
#[derive(Clone, Eq, Hash, PartialEq)]
pub struct Address {
local: String,
domain: Domain,
requires_smtputf8: bool,
}
impl Address {
pub const MAX_OCTETS: usize = MAILBOX_MAX_OCTETS;
pub const MAX_INPUT_BYTES: usize = INPUT_MAX_BYTES;
pub fn parse(input: &str) -> Result<Self, ParseError> {
if input.is_empty() {
return Err(ParseError::new(ParseErrorKind::Empty));
}
if input.len() > INPUT_MAX_BYTES {
return Err(ParseError::new(ParseErrorKind::TooLong));
}
let (local, raw_domain) = input
.rsplit_once('@')
.ok_or_else(|| ParseError::new(ParseErrorKind::InvalidSyntax))?;
if local.len() > LOCAL_PART_MAX_OCTETS {
return Err(ParseError::new(ParseErrorKind::LocalPartTooLong));
}
if !valid_local_part(local) {
return Err(ParseError::new(ParseErrorKind::InvalidSyntax));
}
let domain = parse_domain(raw_domain)?;
let mailbox_octets = local.len() + 1 + domain.ascii.len();
if mailbox_octets > MAILBOX_MAX_OCTETS {
return Err(ParseError::new(ParseErrorKind::TooLong));
}
Ok(Self {
local: local.to_owned(),
domain,
requires_smtputf8: !local.is_ascii(),
})
}
#[must_use]
pub fn local(&self) -> &str {
&self.local
}
#[must_use]
pub const fn domain(&self) -> &Domain {
&self.domain
}
#[must_use]
pub const fn requires_smtputf8(&self) -> bool {
self.requires_smtputf8
}
}
fn valid_local_part(local: &str) -> bool {
if let Some(quoted) = local
.strip_prefix('"')
.and_then(|value| value.strip_suffix('"'))
{
return valid_quoted_local_part(quoted);
}
!local.is_empty()
&& local
.split('.')
.all(|atom| !atom.is_empty() && atom.chars().all(atext))
}
fn valid_quoted_local_part(local: &str) -> bool {
let mut characters = local.chars();
while let Some(character) = characters.next() {
if character == '\\' {
if !characters
.next()
.is_some_and(|escaped| (' '..='~').contains(&escaped))
{
return false;
}
} else if character.is_ascii() {
if !matches!(character, ' '..='!' | '#'..='[' | ']'..='~') {
return false;
}
} else if character.is_control() {
return false;
}
}
true
}
fn atext(character: char) -> bool {
character.is_ascii_alphanumeric()
|| matches!(
character,
'!' | '#'
| '$'
| '%'
| '&'
| '\''
| '*'
| '+'
| '-'
| '/'
| '='
| '?'
| '^'
| '_'
| '`'
| '{'
| '|'
| '}'
| '~'
)
|| !character.is_ascii() && !character.is_control()
}
impl fmt::Debug for Address {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
formatter
.debug_struct("Address")
.field("mailbox", &format_args!("***@{}", self.domain.display))
.field("requires_smtputf8", &self.requires_smtputf8)
.finish()
}
}
impl fmt::Display for Address {
fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
write!(formatter, "{}@{}", self.local, self.domain)
}
}
impl std::str::FromStr for Address {
type Err = ParseError;
fn from_str(input: &str) -> Result<Self, Self::Err> {
Self::parse(input)
}
}
fn parse_domain(input: &str) -> Result<Domain, ParseError> {
if let Some(literal) = input
.strip_prefix('[')
.and_then(|value| value.strip_suffix(']'))
{
let literal = if let Some((tag, address)) = literal.split_once(':') {
if !tag.eq_ignore_ascii_case("ipv6") {
return Err(ParseError::new(ParseErrorKind::InvalidDomain));
}
address
.parse::<std::net::Ipv6Addr>()
.map(IpAddr::V6)
.map_err(|_| ParseError::new(ParseErrorKind::InvalidDomain))?
} else {
literal
.parse::<std::net::Ipv4Addr>()
.map(IpAddr::V4)
.map_err(|_| ParseError::new(ParseErrorKind::InvalidDomain))?
};
return Ok(Domain {
display: input.to_owned(),
ascii: input.to_ascii_lowercase(),
literal: Some(literal),
});
}
let ascii = idna::domain_to_ascii_strict(input)
.map_err(|_| ParseError::new(ParseErrorKind::InvalidDomain))?
.to_ascii_lowercase();
if ascii.is_empty() || ascii.split('.').any(str::is_empty) {
return Err(ParseError::new(ParseErrorKind::InvalidDomain));
}
let (display, result) = idna::domain_to_unicode(&ascii);
result.map_err(|_| ParseError::new(ParseErrorKind::InvalidDomain))?;
Ok(Domain {
display,
ascii,
literal: None,
})
}
#[cfg(test)]
mod tests {
use proptest::prelude::*;
use super::*;
#[test]
fn parses_ascii_mailbox_without_rewriting_local_part() {
let address = Address::parse("Maya+tag@Example.COM").unwrap();
assert_eq!(address.local(), "Maya+tag");
assert_eq!(address.domain().ascii(), "example.com");
assert_eq!(address.to_string(), "Maya+tag@example.com");
assert!(!address.requires_smtputf8());
}
#[test]
fn accepts_an_empty_quoted_local_part() {
let address = Address::parse("\"\"@example.com").unwrap();
assert_eq!(address.local(), "\"\"");
}
#[test]
fn derives_idna_dns_form() {
let address = Address::parse("माया@उदाहरण.भारत").unwrap();
assert_eq!(address.domain().ascii(), "xn--p1b6ci4b4b3a.xn--h2brj9c");
assert!(address.requires_smtputf8());
}
#[test]
fn rejects_display_name() {
let error = Address::parse("Maya <maya@example.com>").unwrap_err();
assert_eq!(error.kind(), ParseErrorKind::InvalidSyntax);
assert!(!error.to_string().contains("maya@example.com"));
}
#[test]
fn parses_domain_literals_without_treating_them_as_dns_names() {
let address = Address::parse("maya@[127.0.0.1]").unwrap();
assert!(address.domain().is_literal());
}
#[test]
fn ipv6_domain_literals_require_the_registered_tag() {
assert!(Address::parse("maya@[IPv6:2001:db8::1]").is_ok());
assert!(Address::parse("maya@[2001:db8::1]").is_err());
assert!(Address::parse("maya@[IPv6:127.0.0.1]").is_err());
}
#[test]
fn mailbox_domains_do_not_accept_a_dns_root_label() {
assert!(Address::parse("maya@example.com.").is_err());
assert!(Address::parse("maya@.example.com").is_err());
}
#[test]
fn debug_redacts_local_part() {
let debug = format!("{:?}", Address::parse("secret@example.com").unwrap());
assert!(!debug.contains("secret"));
assert!(debug.contains("example.com"));
}
proptest! {
#[test]
fn arbitrary_utf8_is_always_a_result(input in ".{0,512}") {
let _ = Address::parse(&input);
}
#[test]
fn accepted_ascii_addresses_round_trip(
local in "[a-z][a-z0-9]{0,20}",
label in "[a-z][a-z0-9]{0,20}",
) {
let input = format!("{local}@{label}.example");
let address = Address::parse(&input).unwrap();
prop_assert_eq!(address.to_string(), input);
}
}
}