daaki-imap 0.1.0

//! IMAP `ENVELOPE` type (RFC 3501 Section 7.4.2, RFC 9051 Section 7.5.2).
//!
//! All fields are owned strings. RFC 2047 encoded words are decoded at parse time
//! unless UTF8=ACCEPT (RFC 6855 Section 3) is active, in which case fields contain
//! raw UTF-8 per RFC 6532 Section 3. Non-UTF-8 charsets are lossy-converted to UTF-8.

/// A parsed IMAP ENVELOPE structure (RFC 3501 Section 7.4.2 / RFC 9051 Section 7.5.2).
///
/// Every field can be `None` because servers may return NIL for any of them.
#[derive(Debug, Clone, PartialEq, Eq, Default)]
pub struct Envelope {
    /// Date from the Date header (RFC 5322 Section 3.3, RFC 3501 Section 7.4.2).
    pub date: Option<String>,
    /// Decoded subject (RFC 2047 Section 2, RFC 3501 Section 7.4.2).
    /// When UTF8=ACCEPT (RFC 6855 Section 3) is active, contains raw UTF-8
    /// per RFC 6532 Section 3.
    pub subject: Option<String>,
    /// From addresses (RFC 5322 Section 3.6.2, RFC 3501 Section 7.4.2).
    pub from: Vec<EnvelopeAddress>,
    /// Sender addresses (RFC 5322 Section 3.6.2, RFC 3501 Section 7.4.2).
    pub sender: Vec<EnvelopeAddress>,
    /// Reply-To addresses (RFC 5322 Section 3.6.2, RFC 3501 Section 7.4.2).
    pub reply_to: Vec<EnvelopeAddress>,
    /// To addresses (RFC 5322 Section 3.6.3, RFC 3501 Section 7.4.2).
    pub to: Vec<EnvelopeAddress>,
    /// CC addresses (RFC 5322 Section 3.6.3, RFC 3501 Section 7.4.2).
    pub cc: Vec<EnvelopeAddress>,
    /// BCC addresses (RFC 5322 Section 3.6.3, RFC 3501 Section 7.4.2).
    pub bcc: Vec<EnvelopeAddress>,
    /// In-Reply-To header (RFC 5322 Section 3.6.4, RFC 3501 Section 7.4.2).
    pub in_reply_to: Option<String>,
    /// Message-ID header (RFC 5322 Section 3.6.4, RFC 3501 Section 7.4.2).
    pub message_id: Option<String>,
}

impl Envelope {
    /// Extract the first message-id from `in_reply_to`, stripped of angle brackets.
    ///
    /// Convenience method — the raw value is preserved in the field.
    pub fn first_in_reply_to(&self) -> Option<&str> {
        let raw = self.in_reply_to.as_deref()?;
        // Find the first <...> delimited message-id, or fall back to the whole string trimmed.
        if let Some(start) = raw.find('<') {
            let rest = &raw[start + 1..];
            // RFC 5322 Section 3.6.4: msg-id = "<" id-left "@" id-right ">".
            // Trim whitespace and filter out empty/whitespace-only content.
            rest.find('>')
                .map(|end| &rest[..end])
                .map(str::trim)
                .filter(|s| !s.is_empty())
        } else {
            let trimmed = raw.trim();
            if trimmed.is_empty() {
                None
            } else {
                Some(trimmed)
            }
        }
    }

    /// Return the message-id stripped of angle brackets.
    ///
    /// Convenience method — the raw value is preserved in the field.
    pub fn bare_message_id(&self) -> Option<&str> {
        let raw = self.message_id.as_deref()?;
        let trimmed = raw.trim();
        trimmed
            .strip_prefix('<')
            .and_then(|s| s.strip_suffix('>'))
            // RFC 5322 Section 3.6.4: trim CFWS around msg-id components.
            .map(str::trim)
            .or(Some(trimmed))
            .filter(|s| !s.is_empty())
    }
}

/// A single address entry from an ENVELOPE (RFC 3501 Section 7.4.2 / RFC 9051 Section 7.5.2).
///
/// Named `EnvelopeAddress` to distinguish from `daaki_message::Address` (RFC 5322 Section 3.4),
/// which is a simpler name+email pair. This type carries the full IMAP 4-tuple.
///
/// Group syntax is represented as:
/// - **Group start**: `host` is `None`, `mailbox` holds the group name.
/// - **Group end**: both `host` and `mailbox` are `None`.
///
/// Use [`EnvelopeAddress::is_group_start`] and [`EnvelopeAddress::is_group_end`] to detect these markers.
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct EnvelopeAddress {
    /// Display name, RFC 2047 decoded (RFC 3501 Section 7.4.2 / RFC 9051 Section 7.5.2).
    /// When UTF8=ACCEPT (RFC 6855 Section 3) is active, contains raw UTF-8
    /// per RFC 6532 Section 3.
    pub name: Option<String>,
    /// SMTP at-domain-list (source route) — almost always `None` in practice
    /// (RFC 3501 Section 7.4.2 / RFC 9051 Section 7.5.2).
    pub adl: Option<String>,
    /// Mailbox (local-part), or group name for group-start markers
    /// (RFC 3501 Section 7.4.2 / RFC 9051 Section 7.5.2).
    pub mailbox: Option<String>,
    /// Host (domain part), or `None` for group markers
    /// (RFC 3501 Section 7.4.2 / RFC 9051 Section 7.5.2).
    pub host: Option<String>,
}

impl EnvelopeAddress {
    /// Returns the full email address as `mailbox@host`, or `None` if either part is missing
    /// or empty (including for group markers).
    ///
    /// RFC 5322 Section 3.4.1: `addr-spec = local-part "@" domain` — both local-part
    /// and domain are required to be non-empty.
    pub fn email(&self) -> Option<String> {
        match (&self.mailbox, &self.host) {
            (Some(m), Some(h)) if !m.is_empty() && !h.is_empty() => Some(format!("{m}@{h}")),
            _ => None,
        }
    }

    /// Returns `true` if this is an RFC 5322 group start marker.
    ///
    /// Per RFC 3501 Section 7.4.2: host is NIL, mailbox holds the group name.
    pub fn is_group_start(&self) -> bool {
        self.host.is_none() && self.mailbox.is_some()
    }

    /// Returns `true` if this is an RFC 5322 group end marker.
    ///
    /// Per RFC 3501 Section 7.4.2: both host and mailbox are NIL.
    pub fn is_group_end(&self) -> bool {
        self.host.is_none() && self.mailbox.is_none()
    }

    /// Returns `true` if this is a real address (not a group marker).
    pub fn is_address(&self) -> bool {
        self.host.is_some()
    }

    /// Converts this IMAP address to a `daaki_message::Address`.
    ///
    /// Returns `None` for group markers (where both mailbox and host
    /// are not present). For real addresses, combines `mailbox@host`
    /// into the `email` field.
    ///
    /// This eliminates the boilerplate conversion that consumers otherwise
    /// need at every IMAP→message boundary.
    ///
    /// # References
    /// - RFC 3501 Section 7.4.2 (ENVELOPE address structure)
    /// - RFC 5322 Section 3.4 (address specification)
    pub fn to_message_address(&self) -> Option<daaki_message::Address> {
        let email = self.email()?;
        Some(daaki_message::Address {
            name: self.name.clone(),
            email,
        })
    }
}

/// Converts an IMAP ENVELOPE address to a `daaki_message::Address`.
///
/// Group markers (where `email()` returns `None`) produce an `Address`
/// with an empty `email` field. Use [`EnvelopeAddress::to_message_address`] if
/// you need to filter those out.
///
/// # References
/// - RFC 3501 Section 7.4.2 (ENVELOPE address structure)
impl From<&EnvelopeAddress> for daaki_message::Address {
    fn from(addr: &EnvelopeAddress) -> Self {
        Self {
            name: addr.name.clone(),
            email: addr.email().unwrap_or_default(),
        }
    }
}

/// Owned conversion from IMAP envelope address to message address.
impl From<EnvelopeAddress> for daaki_message::Address {
    fn from(addr: EnvelopeAddress) -> Self {
        Self {
            email: addr.email().unwrap_or_default(),
            name: addr.name,
        }
    }
}

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

    #[test]
    fn address_email_both_parts() {
        let addr = EnvelopeAddress {
            name: Some("Alice".into()),
            adl: None,
            mailbox: Some("alice".into()),
            host: Some("example.com".into()),
        };
        assert_eq!(addr.email(), Some("alice@example.com".into()));
        assert!(addr.is_address());
        assert!(!addr.is_group_start());
        assert!(!addr.is_group_end());
    }

    #[test]
    fn address_email_missing_host() {
        let addr = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: Some("alice".into()),
            host: None,
        };
        assert_eq!(addr.email(), None);
    }

    #[test]
    fn address_email_missing_mailbox() {
        let addr = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: None,
            host: Some("example.com".into()),
        };
        assert_eq!(addr.email(), None);
    }

    #[test]
    fn default_envelope_is_empty() {
        let env = Envelope::default();
        assert!(env.date.is_none());
        assert!(env.subject.is_none());
        assert!(env.from.is_empty());
        assert!(env.message_id.is_none());
    }

    // --- Group marker tests (RFC 3501 Section 7.4.2) ---

    #[test]
    fn group_start_marker() {
        let addr = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: Some("Friends".into()),
            host: None,
        };
        assert!(addr.is_group_start());
        assert!(!addr.is_group_end());
        assert!(!addr.is_address());
        assert_eq!(addr.email(), None);
    }

    #[test]
    fn group_end_marker() {
        let addr = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: None,
            host: None,
        };
        assert!(addr.is_group_end());
        assert!(!addr.is_group_start());
        assert!(!addr.is_address());
    }

    // --- Envelope convenience methods ---

    #[test]
    fn bare_message_id_strips_brackets() {
        let env = Envelope {
            message_id: Some("<abc@example.com>".into()),
            ..Default::default()
        };
        assert_eq!(env.bare_message_id(), Some("abc@example.com"));
    }

    #[test]
    fn bare_message_id_no_brackets() {
        let env = Envelope {
            message_id: Some("abc@example.com".into()),
            ..Default::default()
        };
        assert_eq!(env.bare_message_id(), Some("abc@example.com"));
    }

    #[test]
    fn bare_message_id_nil() {
        let env = Envelope::default();
        assert_eq!(env.bare_message_id(), None);
    }

    #[test]
    fn first_in_reply_to_single() {
        let env = Envelope {
            in_reply_to: Some("<parent@example.com>".into()),
            ..Default::default()
        };
        assert_eq!(env.first_in_reply_to(), Some("parent@example.com"));
    }

    #[test]
    fn first_in_reply_to_multiple() {
        let env = Envelope {
            in_reply_to: Some("<first@a.com> <second@b.com>".into()),
            ..Default::default()
        };
        assert_eq!(env.first_in_reply_to(), Some("first@a.com"));
    }

    #[test]
    fn first_in_reply_to_no_brackets() {
        let env = Envelope {
            in_reply_to: Some("bare-id@example.com".into()),
            ..Default::default()
        };
        assert_eq!(env.first_in_reply_to(), Some("bare-id@example.com"));
    }

    #[test]
    fn first_in_reply_to_nil() {
        let env = Envelope::default();
        assert_eq!(env.first_in_reply_to(), None);
    }

    /// `first_in_reply_to()` must return `None` for empty angle brackets `<>`
    /// (RFC 5322 Section 3.6.4: msg-id requires non-empty id-left "@" id-right).
    #[test]
    fn first_in_reply_to_empty_angle_brackets() {
        let env = Envelope {
            in_reply_to: Some("<>".into()),
            ..Default::default()
        };
        assert_eq!(
            env.first_in_reply_to(),
            None,
            "first_in_reply_to() must return None for empty angle brackets <> \
             (RFC 5322 Section 3.6.4)"
        );
    }

    /// `first_in_reply_to()` must return `None` for whitespace-only content
    /// inside angle brackets `<  >` (RFC 5322 Section 3.6.4: msg-id requires
    /// id-left "@" id-right, so whitespace alone is never a valid message-id).
    #[test]
    fn first_in_reply_to_whitespace_only_in_brackets() {
        let env = Envelope {
            in_reply_to: Some("<  >".into()),
            ..Default::default()
        };
        assert_eq!(
            env.first_in_reply_to(),
            None,
            "first_in_reply_to() must return None for whitespace-only angle brackets <  > \
             (RFC 5322 Section 3.6.4)"
        );
    }

    /// `first_in_reply_to()` must return `None` for a single space inside
    /// angle brackets `< >` (RFC 5322 Section 3.6.4).
    #[test]
    fn first_in_reply_to_single_space_in_brackets() {
        let env = Envelope {
            in_reply_to: Some("< >".into()),
            ..Default::default()
        };
        assert_eq!(
            env.first_in_reply_to(),
            None,
            "first_in_reply_to() must return None for single-space angle brackets < > \
             (RFC 5322 Section 3.6.4)"
        );
    }

    /// `first_in_reply_to()` must trim surrounding whitespace from the
    /// extracted message-id (RFC 5322 Section 3.6.4: CFWS around msg-id).
    #[test]
    fn first_in_reply_to_trims_whitespace() {
        let env = Envelope {
            in_reply_to: Some("< real@example.com >".into()),
            ..Default::default()
        };
        assert_eq!(
            env.first_in_reply_to(),
            Some("real@example.com"),
            "first_in_reply_to() must trim whitespace inside angle brackets \
             (RFC 5322 Section 3.6.4)"
        );
    }

    /// `first_in_reply_to()` returns the valid id for a normal bracketed input.
    #[test]
    fn first_in_reply_to_normal_bracketed() {
        let env = Envelope {
            in_reply_to: Some("<real@example.com>".into()),
            ..Default::default()
        };
        assert_eq!(env.first_in_reply_to(), Some("real@example.com"));
    }

    /// `bare_message_id()` must return `None` for empty angle brackets `<>`.
    #[test]
    fn bare_message_id_empty_angle_brackets() {
        let env = Envelope {
            message_id: Some("<>".into()),
            ..Default::default()
        };
        assert_eq!(
            env.bare_message_id(),
            None,
            "bare_message_id() must return None for empty angle brackets <>"
        );
    }

    /// `bare_message_id()` must return `None` for whitespace-only content
    /// inside angle brackets `< >` (RFC 5322 Section 3.6.4: msg-id requires
    /// id-left "@" id-right, so whitespace alone is never a valid message-id).
    #[test]
    fn bare_message_id_whitespace_only_in_brackets() {
        let env = Envelope {
            message_id: Some("< >".into()),
            ..Default::default()
        };
        assert_eq!(
            env.bare_message_id(),
            None,
            "bare_message_id() must return None for whitespace-only angle brackets < > \
             (RFC 5322 Section 3.6.4)"
        );
    }

    /// `bare_message_id()` must return `None` for multi-space content
    /// inside angle brackets `<   >` (RFC 5322 Section 3.6.4).
    #[test]
    fn bare_message_id_multi_space_in_brackets() {
        let env = Envelope {
            message_id: Some("<   >".into()),
            ..Default::default()
        };
        assert_eq!(
            env.bare_message_id(),
            None,
            "bare_message_id() must return None for multi-space angle brackets <   > \
             (RFC 5322 Section 3.6.4)"
        );
    }

    /// `email()` must return `None` when mailbox or host is an empty string,
    /// because `@host` / `mailbox@` / `@` are not valid addr-spec values
    /// (RFC 5322 Section 3.4.1).
    #[test]
    fn address_email_rejects_empty_strings() {
        let both_empty = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: Some(String::new()),
            host: Some(String::new()),
        };
        assert_eq!(
            both_empty.email(),
            None,
            "email() must return None when both mailbox and host are empty strings \
             (RFC 5322 Section 3.4.1: addr-spec = local-part '@' domain)"
        );

        let empty_mailbox = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: Some(String::new()),
            host: Some("example.com".into()),
        };
        assert_eq!(
            empty_mailbox.email(),
            None,
            "email() must return None when mailbox is empty \
             (RFC 5322 Section 3.4.1)"
        );

        let empty_host = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: Some("alice".into()),
            host: Some(String::new()),
        };
        assert_eq!(
            empty_host.email(),
            None,
            "email() must return None when host is empty \
             (RFC 5322 Section 3.4.1)"
        );
    }

    /// `bare_message_id()` must trim surrounding whitespace from the
    /// extracted message-id (RFC 5322 Section 3.6.4: CFWS around msg-id).
    #[test]
    fn bare_message_id_trims_whitespace() {
        let env = Envelope {
            message_id: Some("< real@example.com >".into()),
            ..Default::default()
        };
        assert_eq!(
            env.bare_message_id(),
            Some("real@example.com"),
            "bare_message_id() must trim whitespace inside angle brackets \
             (RFC 5322 Section 3.6.4)"
        );
    }

    // --- EnvelopeAddress is distinct from daaki_message::Address ---

    /// Verify that `EnvelopeAddress` exists as a distinct type from `daaki_message::Address`
    /// and has the correct IMAP envelope fields (name, adl, mailbox, host) per
    /// RFC 3501 Section 7.4.2.
    #[test]
    fn envelope_address_is_distinct_from_message_address() {
        // EnvelopeAddress is the IMAP 4-tuple (RFC 3501 Section 7.4.2).
        let env_addr = EnvelopeAddress {
            name: Some("Alice".into()),
            adl: None,
            mailbox: Some("alice".into()),
            host: Some("example.com".into()),
        };
        assert_eq!(env_addr.name.as_deref(), Some("Alice"));
        assert!(env_addr.adl.is_none());
        assert_eq!(env_addr.mailbox.as_deref(), Some("alice"));
        assert_eq!(env_addr.host.as_deref(), Some("example.com"));

        // daaki_message::Address is a simpler name+email pair (RFC 5322 Section 3.4).
        let msg_addr = daaki_message::Address {
            name: Some("Alice".into()),
            email: "alice@example.com".into(),
        };
        assert_eq!(msg_addr.name.as_deref(), Some("Alice"));
        assert_eq!(msg_addr.email, "alice@example.com");

        // The two types are fundamentally different — EnvelopeAddress has adl/mailbox/host,
        // while daaki_message::Address has a single email field.
    }

    // --- Address → daaki_message::Address conversion  ---

    #[test]
    fn to_message_address_normal() {
        let addr = EnvelopeAddress {
            name: Some("Alice".into()),
            adl: None,
            mailbox: Some("alice".into()),
            host: Some("example.com".into()),
        };
        let msg_addr = addr.to_message_address().unwrap();
        assert_eq!(msg_addr.name.as_deref(), Some("Alice"));
        assert_eq!(msg_addr.email, "alice@example.com");
    }

    #[test]
    fn to_message_address_group_marker_returns_none() {
        let group_start = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: Some("undisclosed".into()),
            host: None,
        };
        assert!(
            group_start.to_message_address().is_none(),
            "group start marker must return None"
        );
    }

    #[test]
    fn from_ref_conversion() {
        let addr = EnvelopeAddress {
            name: Some("Bob".into()),
            adl: None,
            mailbox: Some("bob".into()),
            host: Some("test.com".into()),
        };
        let msg_addr: daaki_message::Address = (&addr).into();
        assert_eq!(msg_addr.name.as_deref(), Some("Bob"));
        assert_eq!(msg_addr.email, "bob@test.com");
    }

    #[test]
    fn from_owned_conversion() {
        let addr = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: Some("user".into()),
            host: Some("domain.org".into()),
        };
        let msg_addr: daaki_message::Address = addr.into();
        assert!(msg_addr.name.is_none());
        assert_eq!(msg_addr.email, "user@domain.org");
    }

    #[test]
    fn from_conversion_group_marker_empty_email() {
        let addr = EnvelopeAddress {
            name: None,
            adl: None,
            mailbox: None,
            host: None,
        };
        let msg_addr: daaki_message::Address = (&addr).into();
        assert!(msg_addr.email.is_empty());
    }

    /// Both `From<&EnvelopeAddress>` and `From<EnvelopeAddress>` must produce identical results
    /// for addresses with empty mailbox/host parts.
    #[test]
    fn from_ref_and_owned_match_for_empty_parts() {
        let cases = [
            EnvelopeAddress {
                name: Some("X".into()),
                adl: None,
                mailbox: Some(String::new()),
                host: Some("h.com".into()),
            },
            EnvelopeAddress {
                name: None,
                adl: None,
                mailbox: Some("u".into()),
                host: Some(String::new()),
            },
            EnvelopeAddress {
                name: None,
                adl: None,
                mailbox: Some(String::new()),
                host: Some(String::new()),
            },
            EnvelopeAddress {
                name: None,
                adl: None,
                mailbox: None,
                host: Some("h.com".into()),
            },
        ];
        for addr in &cases {
            let from_ref: daaki_message::Address = addr.into();
            let from_owned: daaki_message::Address = addr.clone().into();
            assert_eq!(
                from_ref.email, from_owned.email,
                "From<&EnvelopeAddress> and From<EnvelopeAddress> must produce the same email for {addr:?}"
            );
            assert_eq!(
                from_ref.name, from_owned.name,
                "From<&EnvelopeAddress> and From<EnvelopeAddress> must produce the same name for {addr:?}"
            );
        }
    }
}