email_message/

address.rs

//! RFC 5322 mailbox, group, address, and address-list values.
//!
//! Parsing accepts either a single address item or a comma-separated list,
//! depending on the target type. Rendering produces UTF-8-direct display names;
//! use `email-message-wire` when RFC 2047 header encoding is required.

use std::fmt::Display;
use std::str::FromStr;
use std::sync::OnceLock;

use crate::email::{EmailAddress, EmailAddressParseError};

static ADDRESS_PARSER: OnceLock<mail_parser::MessageParser> = OnceLock::new();

/// A mailbox address with optional display name.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct Mailbox {
    name: Option<String>,
    email: EmailAddress,
}

impl Mailbox {
    /// Returns the optional display name.
    #[must_use]
    pub fn name(&self) -> Option<&str> {
        self.name.as_deref()
    }

    /// Returns the mailbox email address.
    #[must_use]
    pub const fn email(&self) -> &EmailAddress {
        &self.email
    }
}

impl From<EmailAddress> for Mailbox {
    fn from(email: EmailAddress) -> Self {
        Self { name: None, email }
    }
}

impl From<(String, EmailAddress)> for Mailbox {
    fn from((name, email): (String, EmailAddress)) -> Self {
        Self {
            name: Some(name),
            email,
        }
    }
}

impl From<(Option<String>, EmailAddress)> for Mailbox {
    fn from((name, email): (Option<String>, EmailAddress)) -> Self {
        Self { name, email }
    }
}

/// Errors returned when parsing a [`Mailbox`] or [`MailboxList`].
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum MailboxParseError {
    /// The input contained zero or multiple address items.
    #[error("expected a single mailbox, found {found} address item(s)")]
    ExpectedSingleMailbox {
        /// Number of address items found.
        found: usize,
    },
    /// The single address item was a group rather than a mailbox.
    #[error("expected mailbox but found group")]
    UnexpectedAddressKind,
    /// A mailbox list contained at least one group.
    #[error("mailbox list contains group entries")]
    ContainsGroupEntry,
    /// The address parsing backend failed.
    #[error("mailbox parse backend failed")]
    Backend {
        /// The underlying backend error.
        #[source]
        source: AddressBackendError,
    },
}

impl FromStr for Mailbox {
    type Err = MailboxParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if let Ok(email) = EmailAddress::from_str(s) {
            return Ok(Self::from(email));
        }

        let addresses =
            parse_address_items(s).map_err(|source| MailboxParseError::Backend { source })?;
        if addresses.len() != 1 {
            return Err(MailboxParseError::ExpectedSingleMailbox {
                found: addresses.len(),
            });
        }

        match addresses.into_iter().next() {
            Some(Address::Mailbox(mailbox)) => Ok(mailbox),
            _ => Err(MailboxParseError::UnexpectedAddressKind),
        }
    }
}

impl TryFrom<&str> for Mailbox {
    type Error = MailboxParseError;

    /// Parses a single mailbox from a string slice.
    ///
    /// ```rust
    /// use email_message::Mailbox;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let mailbox = Mailbox::try_from("Mary Smith <mary@x.test>")?;
    /// assert_eq!(mailbox.name(), Some("Mary Smith"));
    /// assert_eq!(mailbox.email().as_str(), "mary@x.test");
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`MailboxParseError`] unless the input contains exactly one
    /// mailbox and no group.
    fn try_from(value: &str) -> Result<Self, Self::Error> {
        Self::from_str(value)
    }
}

/// Renders the mailbox as `"display name" <email>` or just `email` if no
/// display name is set.
///
/// The output is **UTF-8-direct**: a non-ASCII display name is emitted
/// verbatim (e.g. `"José" <jose@example.com>`). This is the right shape
/// for HTTP-API consumers (Postmark, Resend, Mailgun, Loops) which
/// JSON-encode UTF-8 strings natively.
///
/// **Do not use the result directly as an RFC 5322 header value.** SMTP
/// headers are 7-bit and require RFC 2047 encoded-word wrapping for
/// non-ASCII display names; the wire renderer
/// (`email_message_wire::render_rfc822`) applies that encoding
/// separately. Routing `Mailbox::to_string()` straight into a `From:`
/// or `To:` header would emit a malformed RFC 5322 line.
impl Display for Mailbox {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self.name() {
            Some(name) => {
                write_quoted(name, f)?;
                f.write_str(" <")?;
                self.email.fmt(f)?;
                f.write_str(">")
            }
            None => self.email.fmt(f),
        }
    }
}

#[cfg(feature = "serde")]
#[derive(serde::Deserialize, PartialEq, Eq)]
#[serde(rename_all = "snake_case")]
enum AddressKind {
    Mailbox,
    Group,
}

#[cfg(feature = "schemars")]
fn mailbox_typed_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
    let email = generator.subschema_for::<EmailAddress>();
    schemars::json_schema!({
        "type": "object",
        "properties": {
            "type": {"const": "mailbox"},
            "name": {"type": ["string", "null"]},
            "email": email
        },
        "required": ["type", "email"]
    })
}

#[cfg(feature = "serde")]
impl serde::Serialize for Mailbox {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        use serde::ser::SerializeStruct as _;

        let len = 2 + usize::from(self.name.is_some());
        let mut value = serializer.serialize_struct("Mailbox", len)?;
        value.serialize_field("type", "mailbox")?;
        if let Some(name) = &self.name {
            value.serialize_field("name", name)?;
        }
        value.serialize_field("email", &self.email)?;
        value.end()
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for Mailbox {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        #[derive(serde::Deserialize)]
        struct RawMailbox {
            #[serde(rename = "type")]
            type_: AddressKind,
            #[serde(default)]
            name: Option<String>,
            email: EmailAddress,
        }

        fn from_raw<E>(raw: RawMailbox) -> Result<Mailbox, E>
        where
            E: serde::de::Error,
        {
            if raw.type_ != AddressKind::Mailbox {
                return Err(E::custom("expected mailbox address type"));
            }
            Ok(Mailbox {
                name: raw.name,
                email: raw.email,
            })
        }

        #[cfg(feature = "rfc5322-string-compat")]
        {
            // A bespoke `Visitor` (rather than `#[serde(untagged)]`) so
            // typed-shape errors keep their field-level provenance, e.g.
            // `missing field "type"` instead of the generic "did not match
            // any variant" produced by `untagged`.
            struct MailboxVisitor;

            impl<'de> serde::de::Visitor<'de> for MailboxVisitor {
                type Value = Mailbox;

                fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                    f.write_str("a typed mailbox object or an RFC 5322 mailbox string")
                }

                fn visit_str<E>(self, value: &str) -> Result<Mailbox, E>
                where
                    E: serde::de::Error,
                {
                    value.parse().map_err(E::custom)
                }

                fn visit_string<E>(self, value: String) -> Result<Mailbox, E>
                where
                    E: serde::de::Error,
                {
                    value.parse().map_err(E::custom)
                }

                fn visit_map<A>(self, map: A) -> Result<Mailbox, A::Error>
                where
                    A: serde::de::MapAccess<'de>,
                {
                    let raw = <RawMailbox as serde::Deserialize<'de>>::deserialize(
                        serde::de::value::MapAccessDeserializer::new(map),
                    )?;
                    from_raw(raw)
                }
            }

            deserializer.deserialize_any(MailboxVisitor)
        }

        #[cfg(not(feature = "rfc5322-string-compat"))]
        from_raw(RawMailbox::deserialize(deserializer)?)
    }
}

#[cfg(feature = "schemars")]
impl schemars::JsonSchema for Mailbox {
    fn schema_name() -> std::borrow::Cow<'static, str> {
        "Mailbox".into()
    }

    fn schema_id() -> std::borrow::Cow<'static, str> {
        concat!(module_path!(), "::Mailbox").into()
    }

    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
        let typed = mailbox_typed_schema(generator);

        #[cfg(feature = "rfc5322-string-compat")]
        {
            schemars::json_schema!({
                "oneOf": [
                    typed,
                    {
                        "type": "string",
                        "description": "RFC 5322 mailbox string"
                    }
                ]
            })
        }

        #[cfg(not(feature = "rfc5322-string-compat"))]
        typed
    }
}

#[cfg(feature = "arbitrary")]
impl<'a> arbitrary::Arbitrary<'a> for Mailbox {
    fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
        let email = EmailAddress::arbitrary(u)?;
        if bool::arbitrary(u)? {
            let name = format!("User {}", u8::arbitrary(u)?);
            Ok(Self {
                name: Some(name),
                email,
            })
        } else {
            Ok(Self { name: None, email })
        }
    }
}

/// A named address group containing mailbox members.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub struct Group {
    name: String,
    members: Vec<Mailbox>,
}

impl Group {
    /// Returns the group display name.
    #[must_use]
    pub fn name(&self) -> &str {
        self.name.as_str()
    }

    /// Returns group members.
    #[must_use]
    pub fn members(&self) -> &[Mailbox] {
        self.members.as_slice()
    }
}

/// Errors returned when parsing a [`Group`].
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum GroupParseError {
    /// The input contained zero or multiple address items.
    #[error("expected a single group, found {found} address item(s)")]
    ExpectedSingleGroup {
        /// Number of address items found.
        found: usize,
    },
    /// The single address item was a mailbox rather than a group.
    #[error("expected group but found mailbox")]
    UnexpectedAddressKind,
    /// The address parsing backend failed.
    #[error("group parse backend failed")]
    Backend {
        /// The underlying backend error.
        #[source]
        source: AddressBackendError,
    },
}

impl FromStr for Group {
    type Err = GroupParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        let addresses =
            parse_address_items(s).map_err(|source| GroupParseError::Backend { source })?;
        if addresses.len() != 1 {
            return Err(GroupParseError::ExpectedSingleGroup {
                found: addresses.len(),
            });
        }

        match addresses.into_iter().next() {
            Some(Address::Group(group)) => Ok(group),
            _ => Err(GroupParseError::UnexpectedAddressKind),
        }
    }
}

impl TryFrom<&str> for Group {
    type Error = GroupParseError;

    /// Parses a single group from a string slice.
    ///
    /// ```rust
    /// use email_message::Group;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let group = Group::try_from("Undisclosed recipients:;")?;
    /// assert_eq!(group.name(), "Undisclosed recipients");
    /// assert!(group.members().is_empty());
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`GroupParseError`] unless the input contains exactly one group.
    fn try_from(value: &str) -> Result<Self, Self::Error> {
        Self::from_str(value)
    }
}

/// Renders the group as `"display name": member1, member2, ...;`.
///
/// Same UTF-8-direct caveat as [`Display for Mailbox`]: suitable for
/// HTTP-API consumers, not directly safe as an RFC 5322 header value.
impl Display for Group {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write_quoted(self.name(), f)?;
        f.write_str(":")?;
        for (idx, member) in self.members().iter().enumerate() {
            if idx > 0 {
                f.write_str(", ")?;
            }
            member.fmt(f)?;
        }
        f.write_str(";")
    }
}

#[cfg(feature = "schemars")]
fn group_typed_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
    let members = <Vec<Mailbox> as schemars::JsonSchema>::json_schema(generator);
    schemars::json_schema!({
        "type": "object",
        "properties": {
            "type": {"const": "group"},
            "name": {"type": "string"},
            "members": members
        },
        "required": ["type", "name"]
    })
}

#[cfg(feature = "serde")]
impl serde::Serialize for Group {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        use serde::ser::SerializeStruct as _;

        let len = 2 + usize::from(!self.members.is_empty());
        let mut value = serializer.serialize_struct("Group", len)?;
        value.serialize_field("type", "group")?;
        value.serialize_field("name", &self.name)?;
        if !self.members.is_empty() {
            value.serialize_field("members", &self.members)?;
        }
        value.end()
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for Group {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        #[derive(serde::Deserialize)]
        struct RawGroup {
            #[serde(rename = "type")]
            type_: AddressKind,
            name: String,
            #[serde(default)]
            members: Vec<Mailbox>,
        }

        fn from_raw<E>(raw: RawGroup) -> Result<Group, E>
        where
            E: serde::de::Error,
        {
            if raw.type_ != AddressKind::Group {
                return Err(E::custom("expected group address type"));
            }
            Ok(Group {
                name: raw.name,
                members: raw.members,
            })
        }

        #[cfg(feature = "rfc5322-string-compat")]
        {
            struct GroupVisitor;

            impl<'de> serde::de::Visitor<'de> for GroupVisitor {
                type Value = Group;

                fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                    f.write_str("a typed group object or an RFC 5322 group string")
                }

                fn visit_str<E>(self, value: &str) -> Result<Group, E>
                where
                    E: serde::de::Error,
                {
                    value.parse().map_err(E::custom)
                }

                fn visit_string<E>(self, value: String) -> Result<Group, E>
                where
                    E: serde::de::Error,
                {
                    value.parse().map_err(E::custom)
                }

                fn visit_map<A>(self, map: A) -> Result<Group, A::Error>
                where
                    A: serde::de::MapAccess<'de>,
                {
                    let raw = <RawGroup as serde::Deserialize<'de>>::deserialize(
                        serde::de::value::MapAccessDeserializer::new(map),
                    )?;
                    from_raw(raw)
                }
            }

            deserializer.deserialize_any(GroupVisitor)
        }

        #[cfg(not(feature = "rfc5322-string-compat"))]
        from_raw(RawGroup::deserialize(deserializer)?)
    }
}

#[cfg(feature = "schemars")]
impl schemars::JsonSchema for Group {
    fn schema_name() -> std::borrow::Cow<'static, str> {
        "Group".into()
    }

    fn schema_id() -> std::borrow::Cow<'static, str> {
        concat!(module_path!(), "::Group").into()
    }

    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
        let typed = group_typed_schema(generator);

        #[cfg(feature = "rfc5322-string-compat")]
        {
            schemars::json_schema!({
                "oneOf": [
                    typed,
                    {
                        "type": "string",
                        "description": "RFC 5322 group string"
                    }
                ]
            })
        }

        #[cfg(not(feature = "rfc5322-string-compat"))]
        typed
    }
}

#[cfg(feature = "arbitrary")]
impl<'a> arbitrary::Arbitrary<'a> for Group {
    fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
        let member_count = usize::from(u.int_in_range::<u8>(0..=3)?);
        let mut members = Vec::with_capacity(member_count);
        for _ in 0..member_count {
            members.push(Mailbox::arbitrary(u)?);
        }
        Ok(Self {
            name: format!("Group {}", u8::arbitrary(u)?),
            members,
        })
    }
}

/// A single address item: either a mailbox or a group.
///
/// Deliberately *not* `#[non_exhaustive]`. RFC 5322 §3.4 closes the
/// address grammar to exactly `mailbox / group`; the kernel cannot
/// honestly add a third variant without an RFC update. The
/// derive-required exhaustive `match` lets downstream callers branch
/// on every variant without an `_ =>` arm, useful when an extension
/// crate wants type-safe coverage of the address space.
#[derive(Clone, Debug, PartialEq, Eq, Hash)]
pub enum Address {
    /// A single mailbox.
    Mailbox(Mailbox),
    /// A named group of mailboxes.
    Group(Group),
}

impl From<Mailbox> for Address {
    fn from(value: Mailbox) -> Self {
        Self::Mailbox(value)
    }
}

impl From<Group> for Address {
    fn from(value: Group) -> Self {
        Self::Group(value)
    }
}

impl Address {
    /// Returns the mailbox entries represented by this address item.
    pub fn mailboxes(&self) -> impl Iterator<Item = &Mailbox> {
        match self {
            Self::Mailbox(mailbox) => std::slice::from_ref(mailbox).iter(),
            Self::Group(group) => group.members().iter(),
        }
    }
}

/// Errors returned when parsing an [`Address`] or [`AddressList`].
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum AddressParseError {
    /// The input contained zero or multiple address items.
    #[error("expected a single address, found {found} address item(s)")]
    ExpectedSingleAddress {
        /// Number of address items found.
        found: usize,
    },
    /// The address parsing backend failed.
    #[error("address parse backend failed")]
    Backend {
        /// The underlying backend error.
        #[source]
        source: AddressBackendError,
    },
}

impl FromStr for Address {
    type Err = AddressParseError;

    fn from_str(s: &str) -> Result<Self, Self::Err> {
        if let Ok(email) = EmailAddress::from_str(s) {
            return Ok(Self::Mailbox(Mailbox::from(email)));
        }

        let addresses =
            parse_address_items(s).map_err(|source| AddressParseError::Backend { source })?;
        if addresses.len() != 1 {
            return Err(AddressParseError::ExpectedSingleAddress {
                found: addresses.len(),
            });
        }

        addresses
            .into_iter()
            .next()
            .ok_or(AddressParseError::ExpectedSingleAddress { found: 0 })
    }
}

impl TryFrom<&str> for Address {
    type Error = AddressParseError;

    /// Parses a single address (mailbox or group) from a string slice.
    ///
    /// ```rust
    /// use email_message::Address;
    ///
    /// # fn main() -> Result<(), Box<dyn std::error::Error>> {
    /// let address = Address::try_from("jdoe@one.test")?;
    /// assert_eq!(address.to_string(), "jdoe@one.test");
    /// # Ok(())
    /// # }
    /// ```
    ///
    /// # Errors
    ///
    /// Returns [`AddressParseError`] unless the input contains exactly one
    /// mailbox or group.
    fn try_from(value: &str) -> Result<Self, Self::Error> {
        Self::from_str(value)
    }
}

/// Forwards to the underlying [`Display for Mailbox`] or
/// [`Display for Group`]; same UTF-8-direct caveat applies.
impl Display for Address {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        match self {
            Self::Mailbox(mailbox) => mailbox.fmt(f),
            Self::Group(group) => group.fmt(f),
        }
    }
}

#[cfg(feature = "serde")]
impl serde::Serialize for Address {
    fn serialize<S>(&self, serializer: S) -> Result<S::Ok, S::Error>
    where
        S: serde::Serializer,
    {
        match self {
            Self::Mailbox(mailbox) => serde::Serialize::serialize(mailbox, serializer),
            Self::Group(group) => serde::Serialize::serialize(group, serializer),
        }
    }
}

#[cfg(feature = "serde")]
impl<'de> serde::Deserialize<'de> for Address {
    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
    where
        D: serde::Deserializer<'de>,
    {
        #[derive(serde::Deserialize)]
        #[serde(tag = "type", rename_all = "snake_case")]
        enum RawAddress {
            Mailbox {
                #[serde(default)]
                name: Option<String>,
                email: EmailAddress,
            },
            Group {
                name: String,
                #[serde(default)]
                members: Vec<Mailbox>,
            },
        }

        fn from_raw(raw: RawAddress) -> Address {
            match raw {
                RawAddress::Mailbox { name, email } => Address::Mailbox(Mailbox { name, email }),
                RawAddress::Group { name, members } => Address::Group(Group { name, members }),
            }
        }

        #[cfg(feature = "rfc5322-string-compat")]
        {
            struct AddressVisitor;

            impl<'de> serde::de::Visitor<'de> for AddressVisitor {
                type Value = Address;

                fn expecting(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                    f.write_str("a typed address object or an RFC 5322 address string")
                }

                fn visit_str<E>(self, value: &str) -> Result<Address, E>
                where
                    E: serde::de::Error,
                {
                    value.parse().map_err(E::custom)
                }

                fn visit_string<E>(self, value: String) -> Result<Address, E>
                where
                    E: serde::de::Error,
                {
                    value.parse().map_err(E::custom)
                }

                fn visit_map<A>(self, map: A) -> Result<Address, A::Error>
                where
                    A: serde::de::MapAccess<'de>,
                {
                    let raw = <RawAddress as serde::Deserialize<'de>>::deserialize(
                        serde::de::value::MapAccessDeserializer::new(map),
                    )?;
                    Ok(from_raw(raw))
                }
            }

            deserializer.deserialize_any(AddressVisitor)
        }

        #[cfg(not(feature = "rfc5322-string-compat"))]
        Ok(from_raw(RawAddress::deserialize(deserializer)?))
    }
}

#[cfg(feature = "schemars")]
impl schemars::JsonSchema for Address {
    fn schema_name() -> std::borrow::Cow<'static, str> {
        "Address".into()
    }

    fn schema_id() -> std::borrow::Cow<'static, str> {
        concat!(module_path!(), "::Address").into()
    }

    fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
        let mailbox = mailbox_typed_schema(generator);
        let group = group_typed_schema(generator);

        #[cfg(feature = "rfc5322-string-compat")]
        {
            schemars::json_schema!({
                "oneOf": [
                    mailbox,
                    group,
                    {
                        "type": "string",
                        "description": "RFC 5322 address string"
                    }
                ]
            })
        }

        #[cfg(not(feature = "rfc5322-string-compat"))]
        schemars::json_schema!({"oneOf": [mailbox, group]})
    }
}

#[cfg(feature = "arbitrary")]
impl<'a> arbitrary::Arbitrary<'a> for Address {
    fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
        if bool::arbitrary(u)? {
            Ok(Self::Mailbox(Mailbox::arbitrary(u)?))
        } else {
            Ok(Self::Group(Group::arbitrary(u)?))
        }
    }
}

macro_rules! impl_address_collection {
    ($(#[$meta:meta])* $name:ident, $item:ty, $error:ty, $parse_fn:expr) => {
        $(#[$meta])*
        #[derive(Clone, Debug, Default, PartialEq, Eq, Hash)]
        pub struct $name {
            items: Vec<$item>,
        }

        #[cfg(feature = "schemars")]
        impl schemars::JsonSchema for $name {
            fn inline_schema() -> bool {
                true
            }

            fn schema_name() -> std::borrow::Cow<'static, str> {
                stringify!($name).into()
            }

            fn schema_id() -> std::borrow::Cow<'static, str> {
                concat!(module_path!(), "::", stringify!($name)).into()
            }

            fn json_schema(generator: &mut schemars::SchemaGenerator) -> schemars::Schema {
                let typed = <Vec<$item> as schemars::JsonSchema>::json_schema(generator);

                #[cfg(feature = "rfc5322-string-compat")]
                {
                    schemars::json_schema!({
                        "oneOf": [
                            typed,
                            {
                                "type": "string",
                                "description": "RFC 5322 comma-separated address list string"
                            }
                        ]
                    })
                }

                #[cfg(not(feature = "rfc5322-string-compat"))]
                typed
            }
        }

        impl $name {
            /// Returns the number of items in the list.
            #[must_use]
            pub fn len(&self) -> usize {
                self.items.len()
            }

            /// Returns `true` if the list contains no items.
            #[must_use]
            pub fn is_empty(&self) -> bool {
                self.items.is_empty()
            }

            /// Returns an iterator over the items.
            pub fn iter(&self) -> std::slice::Iter<'_, $item> {
                self.items.iter()
            }

            /// Returns a mutable iterator over the items.
            pub fn iter_mut(&mut self) -> std::slice::IterMut<'_, $item> {
                self.items.iter_mut()
            }

            /// Returns the items as a slice.
            #[must_use]
            pub fn as_slice(&self) -> &[$item] {
                self.items.as_slice()
            }

            /// Consumes the list and returns its item vector.
            #[must_use]
            pub fn into_vec(self) -> Vec<$item> {
                self.items
            }
        }

        impl From<Vec<$item>> for $name {
            fn from(items: Vec<$item>) -> Self {
                Self { items }
            }
        }

        impl From<$name> for Vec<$item> {
            fn from(value: $name) -> Self {
                value.items
            }
        }

        impl FromStr for $name {
            type Err = $error;

            fn from_str(s: &str) -> Result<Self, Self::Err> {
                let items = ($parse_fn)(s)?;
                Ok(Self { items })
            }
        }

        impl TryFrom<&str> for $name {
            type Error = $error;

            /// Parses a list from a string slice.
            fn try_from(value: &str) -> Result<Self, Self::Error> {
                Self::from_str(value)
            }
        }

        impl IntoIterator for $name {
            type Item = $item;
            type IntoIter = std::vec::IntoIter<$item>;

            fn into_iter(self) -> Self::IntoIter {
                self.items.into_iter()
            }
        }

        impl<'a> IntoIterator for &'a $name {
            type Item = &'a $item;
            type IntoIter = std::slice::Iter<'a, $item>;

            fn into_iter(self) -> Self::IntoIter {
                self.items.iter()
            }
        }

        impl<'a> IntoIterator for &'a mut $name {
            type Item = &'a mut $item;
            type IntoIter = std::slice::IterMut<'a, $item>;

            fn into_iter(self) -> Self::IntoIter {
                self.items.iter_mut()
            }
        }

        impl AsRef<[$item]> for $name {
            fn as_ref(&self) -> &[$item] {
                self.items.as_slice()
            }
        }

        impl std::iter::FromIterator<$item> for $name {
            fn from_iter<T: IntoIterator<Item = $item>>(iter: T) -> Self {
                Self {
                    items: iter.into_iter().collect(),
                }
            }
        }

        impl Extend<$item> for $name {
            fn extend<T: IntoIterator<Item = $item>>(&mut self, iter: T) {
                self.items.extend(iter);
            }
        }

        impl Display for $name {
            fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
                for (idx, item) in self.items.iter().enumerate() {
                    if idx > 0 {
                        f.write_str(", ")?;
                    }
                    item.fmt(f)?;
                }
                Ok(())
            }
        }

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

        #[cfg(feature = "serde")]
        impl<'de> serde::Deserialize<'de> for $name {
            fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
            where
                D: serde::Deserializer<'de>,
            {
                #[cfg(feature = "rfc5322-string-compat")]
                {
                    struct CollectionVisitor;

                    impl<'de> serde::de::Visitor<'de> for CollectionVisitor {
                        type Value = $name;

                        fn expecting(
                            &self,
                            f: &mut std::fmt::Formatter<'_>,
                        ) -> std::fmt::Result {
                            f.write_str(concat!(
                                "a ",
                                stringify!($name),
                                " array or an RFC 5322 list string",
                            ))
                        }

                        fn visit_str<E>(self, value: &str) -> Result<$name, E>
                        where
                            E: serde::de::Error,
                        {
                            value.parse().map_err(E::custom)
                        }

                        fn visit_string<E>(self, value: String) -> Result<$name, E>
                        where
                            E: serde::de::Error,
                        {
                            value.parse().map_err(E::custom)
                        }

                        fn visit_seq<A>(self, mut seq: A) -> Result<$name, A::Error>
                        where
                            A: serde::de::SeqAccess<'de>,
                        {
                            let mut items = Vec::with_capacity(seq.size_hint().unwrap_or(0));
                            while let Some(item) = seq.next_element::<$item>()? {
                                items.push(item);
                            }
                            Ok($name { items })
                        }
                    }

                    deserializer.deserialize_any(CollectionVisitor)
                }

                #[cfg(not(feature = "rfc5322-string-compat"))]
                {
                    let items = <Vec<$item> as serde::Deserialize>::deserialize(deserializer)?;
                    Ok(Self { items })
                }
            }
        }

        #[cfg(feature = "arbitrary")]
        impl<'a> arbitrary::Arbitrary<'a> for $name {
            fn arbitrary(u: &mut arbitrary::Unstructured<'a>) -> arbitrary::Result<Self> {
                let len = usize::from(u.int_in_range::<u8>(0..=4)?);
                let mut items = Vec::with_capacity(len);
                for _ in 0..len {
                    items.push(<$item>::arbitrary(u)?);
                }
                Ok(Self { items })
            }
        }
    };
}

impl_address_collection!(
    /// A parsed list of address items.
    ///
    /// This is used instead of `Vec<Address>` for `FromStr`, because Rust's orphan
    /// rules do not allow implementing foreign traits for foreign types.
    AddressList,
    Address,
    AddressParseError,
    |s| parse_address_items(s).map_err(|source| AddressParseError::Backend { source })
);

impl<'a> TryFrom<Vec<&'a str>> for AddressList {
    type Error = AddressParseError;

    fn try_from(value: Vec<&'a str>) -> Result<Self, Self::Error> {
        value
            .into_iter()
            .map(Address::from_str)
            .collect::<Result<Vec<_>, _>>()
            .map(Self::from)
    }
}

impl<'a> TryFrom<&'a [&'a str]> for AddressList {
    type Error = AddressParseError;

    fn try_from(value: &'a [&'a str]) -> Result<Self, Self::Error> {
        value
            .iter()
            .copied()
            .map(Address::from_str)
            .collect::<Result<Vec<_>, _>>()
            .map(Self::from)
    }
}

impl<'a> TryFrom<Vec<&'a str>> for MailboxList {
    type Error = MailboxParseError;

    fn try_from(value: Vec<&'a str>) -> Result<Self, Self::Error> {
        value
            .into_iter()
            .map(Mailbox::from_str)
            .collect::<Result<Vec<_>, _>>()
            .map(Self::from)
    }
}

impl<'a> TryFrom<&'a [&'a str]> for MailboxList {
    type Error = MailboxParseError;

    fn try_from(value: &'a [&'a str]) -> Result<Self, Self::Error> {
        value
            .iter()
            .copied()
            .map(Mailbox::from_str)
            .collect::<Result<Vec<_>, _>>()
            .map(Self::from)
    }
}

impl_address_collection!(
    /// A parsed list of mailbox items.
    ///
    /// Group entries are rejected when parsing into `MailboxList`.
    MailboxList,
    Mailbox,
    MailboxParseError,
    |s| {
        let addresses = parse_address_items(s).map_err(|source| MailboxParseError::Backend { source })?;
        let mut items = Vec::with_capacity(addresses.len());

        for address in addresses {
            match address {
                Address::Mailbox(mailbox) => items.push(mailbox),
                Address::Group(_) => return Err(MailboxParseError::ContainsGroupEntry),
            }
        }

        Ok(items)
    }
);

/// Maximum byte length accepted by the address-list parser before
/// rejecting outright. 64 KiB is far above any realistic header value
///, RFC 5322 caps physical lines at 998 bytes; even a header folded
/// across hundreds of continuation lines stays well under this. The
/// cap exists to prevent the `format!("To: {input}\r\n\r\n")`
/// allocation amplification on adversarial multi-megabyte input.
pub const MAX_ADDRESS_INPUT_BYTES: usize = 64 * 1024;

/// Low-level failures reported by the address parsing backend.
#[derive(Debug, thiserror::Error)]
#[non_exhaustive]
pub enum AddressBackendError {
    /// The input contains a raw carriage return or line feed.
    #[error("address input contains raw newline characters")]
    InputContainsRawNewlines,
    /// The input exceeds [`MAX_ADDRESS_INPUT_BYTES`].
    #[error("address input is {len} bytes, exceeding maximum of {max}")]
    #[non_exhaustive]
    InputTooLong {
        /// Actual input length in bytes.
        len: usize,
        /// Maximum accepted input length in bytes.
        max: usize,
    },
    /// The backend could not parse the synthetic address header.
    #[error("failed to parse address header")]
    HeaderParse,
    /// The parsed header did not contain address data.
    #[error("parsed header did not contain address data")]
    MissingAddress,
    /// A mailbox did not contain an `addr-spec`.
    #[error("mailbox is missing addr-spec")]
    MissingAddrSpec,
    /// A mailbox contained an invalid `addr-spec`.
    #[error("invalid addr-spec `{input}`")]
    InvalidAddrSpec {
        /// Invalid `addr-spec` text.
        input: String,
        /// Underlying email-address validation error.
        #[source]
        source: EmailAddressParseError,
    },
    /// A group member did not contain an `addr-spec`.
    #[error("group member at index {index} is missing addr-spec")]
    GroupMemberMissingAddrSpec {
        /// Zero-based index of the invalid member.
        index: usize,
    },
    /// A group member contained an invalid `addr-spec`.
    #[error("invalid group member addr-spec `{input}` at index {index}")]
    InvalidGroupMemberAddrSpec {
        /// Zero-based index of the invalid member.
        index: usize,
        /// Invalid `addr-spec` text.
        input: String,
        /// Underlying email-address validation error.
        #[source]
        source: EmailAddressParseError,
    },
    /// A parsed group did not contain a name.
    #[error("group is missing a name")]
    GroupMissingName,
}

fn write_quoted(value: &str, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
    f.write_str("\"")?;
    for ch in value.chars() {
        if ch == '\\' || ch == '"' {
            f.write_str("\\")?;
        }
        f.write_str(ch.encode_utf8(&mut [0; 4]))?;
    }
    f.write_str("\"")
}

/// Parse-side address-list extractor.
///
/// # Byte discipline at the parser
///
/// This parser deliberately accepts more than the message-level gate
/// rejects. Specifically: it rejects raw CR / LF (which would let an
/// attacker inject a new header line at the parser layer) and
/// inputs over [`MAX_ADDRESS_INPUT_BYTES`]; it does **not** reject
/// NUL or other non-tab ASCII control characters in display-name
/// content.
///
/// The asymmetry is intentional. The kernel's stricter byte-
/// discipline lives at [`crate::Message::validate_basic`] and fires
/// when an outbound `OutboundMessage` is built; inbound parsing is
/// best-effort and used in forensic / archival / replay workflows
/// where rejecting BEL / VT / ESC in display names from real-world
/// malformed-but-recoverable mail loses information. A `Mailbox`
/// carrying questionable bytes is fine *as a parsed value*; it
/// cannot reach an outbound wire renderer because the message-level
/// gate catches it first.
///
/// Callers handing a `Mailbox.name()` directly to a logging sink or
/// non-validated downstream consumer are responsible for their own
/// byte-discipline check.
fn parse_address_items(input: &str) -> Result<Vec<Address>, AddressBackendError> {
    if input.len() > MAX_ADDRESS_INPUT_BYTES {
        return Err(AddressBackendError::InputTooLong {
            len: input.len(),
            max: MAX_ADDRESS_INPUT_BYTES,
        });
    }
    if input.contains('\r') || input.contains('\n') {
        return Err(AddressBackendError::InputContainsRawNewlines);
    }

    let raw = format!("To: {input}\r\n\r\n");
    let parser =
        ADDRESS_PARSER.get_or_init(|| mail_parser::MessageParser::new().with_address_headers());
    let message = parser
        .parse_headers(raw.as_bytes())
        .ok_or(AddressBackendError::HeaderParse)?;
    let parsed = message.to().ok_or(AddressBackendError::MissingAddress)?;

    match parsed {
        mail_parser::Address::List(list) => list
            .iter()
            .map(convert_mailbox)
            .map(|result| result.map(Address::Mailbox))
            .collect(),
        // mail_parser switches the whole header to the `Group` shape as soon
        // as any group syntax appears, and wraps flat mailboxes that appear
        // before/between/after named groups into a synthetic
        // `Group { name: None, ... }`. Flatten those back to `Mailbox`
        // entries so a mixed header like
        // `alice@example.com, Team: bob@team.com;, dave@example.com`
        // produces three items in order rather than a parse error.
        mail_parser::Address::Group(groups) => {
            let mut items = Vec::with_capacity(groups.len());
            for group in groups {
                if group.name.is_some() {
                    items.push(Address::Group(convert_group(group)?));
                } else {
                    for addr in &group.addresses {
                        items.push(Address::Mailbox(convert_mailbox(addr)?));
                    }
                }
            }
            Ok(items)
        }
    }
}

fn convert_mailbox(value: &mail_parser::Addr<'_>) -> Result<Mailbox, AddressBackendError> {
    let raw_email = value
        .address()
        .ok_or(AddressBackendError::MissingAddrSpec)?;
    let email = EmailAddress::from_str(raw_email).map_err(|source| {
        AddressBackendError::InvalidAddrSpec {
            input: raw_email.to_owned(),
            source,
        }
    })?;

    Ok(match value.name() {
        Some(name) => Mailbox::from((name.to_owned(), email)),
        None => Mailbox::from(email),
    })
}

fn convert_group(value: &mail_parser::Group<'_>) -> Result<Group, AddressBackendError> {
    let name = value
        .name
        .as_deref()
        .ok_or(AddressBackendError::GroupMissingName)?
        .to_owned();
    let mut members = Vec::with_capacity(value.addresses.len());
    for (index, member) in value.addresses.iter().enumerate() {
        let mailbox = convert_mailbox(member).map_err(|error| match error {
            AddressBackendError::MissingAddrSpec => {
                AddressBackendError::GroupMemberMissingAddrSpec { index }
            }
            AddressBackendError::InvalidAddrSpec { input, source } => {
                AddressBackendError::InvalidGroupMemberAddrSpec {
                    index,
                    input,
                    source,
                }
            }
            other => other,
        })?;
        members.push(mailbox);
    }

    Ok(Group { name, members })
}

#[cfg(test)]
mod tests {
    use super::*;

    #[test]
    fn mailbox_from_str_accepts_rfc_examples() {
        let parsed = "Mary Smith <mary@x.test>".parse::<Mailbox>();
        assert!(parsed.is_ok(), "expected valid mailbox");

        let parsed = "jdoe@one.test".parse::<Mailbox>();
        assert!(parsed.is_ok(), "expected valid mailbox");
    }

    #[test]
    fn mailbox_from_str_rejects_group() {
        let parsed = "Undisclosed recipients:;".parse::<Mailbox>();
        assert!(matches!(
            parsed,
            Err(MailboxParseError::UnexpectedAddressKind)
        ));
    }

    #[test]
    fn group_from_str_accepts_rfc_examples() {
        let parsed =
            "A Group:Ed Jones <c@a.test>,joe@where.test,John <jdoe@one.test>;".parse::<Group>();
        assert!(parsed.is_ok(), "expected valid group");

        let parsed = "Undisclosed recipients:;".parse::<Group>();
        assert!(parsed.is_ok(), "expected valid group");
    }

    #[test]
    fn address_list_roundtrip() {
        let list = "Mary Smith <mary@x.test>, jdoe@one.test"
            .parse::<AddressList>()
            .expect("address list should parse");
        let rendered = list.to_string();
        let reparsed = rendered
            .parse::<AddressList>()
            .expect("rendered address list should parse");
        assert_eq!(reparsed.as_slice(), list.as_slice());
    }

    #[test]
    fn mailbox_from_str_rejects_input_with_raw_newline() {
        let parsed = "Mary Smith <mary@x.test>\nBcc: victim@example.com".parse::<Mailbox>();
        assert!(matches!(
            parsed,
            Err(MailboxParseError::Backend {
                source: AddressBackendError::InputContainsRawNewlines,
            })
        ));
    }
}