relay_core/identity/
address.rs

1use serde::{Deserialize, Serialize};
2
3use super::{AgentId, IdentityError as Err, InboxId, UserId};
4
5#[derive(Debug, Clone, PartialEq, Eq, Hash, Serialize, Deserialize)]
6pub struct Address {
7    pub inbox: Option<InboxId>,
8    pub user: UserId,
9    pub agent: AgentId,
10}
11
12impl TryFrom<&str> for Address {
13    type Error = Err;
14
15    fn try_from(value: &str) -> Result<Self, Err> {
16        Address::parse(value)
17    }
18}
19
20impl TryFrom<String> for Address {
21    type Error = Err;
22
23    fn try_from(value: String) -> Result<Self, Err> {
24        Address::parse(value)
25    }
26}
27
28impl Address {
29    /// Creates a new address.
30    pub fn new(inbox: Option<InboxId>, user: UserId, agent: AgentId) -> Self {
31        Address { inbox, user, agent }
32    }
33
34    /// Parse an address from a string.
35    /// https://gitlab.com/relay-mail/docs/-/wikis/Architecture/Identity#address
36    /// General format: `[inbox]#user@agent`
37    ///
38    /// # Example
39    /// ```
40    /// use relay_core::id::{Address, AgentId, InboxId, UserId};
41    ///
42    /// let address = Address::parse("work#alice.smith@example.com").unwrap();
43    /// assert_eq!(address.inbox, Some(InboxId::parse("work").unwrap()));
44    /// assert_eq!(address.user, UserId::parse("alice.smith").unwrap());
45    /// assert_eq!(address.agent, AgentId::parse("example.com").unwrap());
46    /// ```
47    pub fn parse(input: impl AsRef<str>) -> Result<Self, Err> {
48        let input = input.as_ref();
49
50        let (left, agent_str) = input.rsplit_once('@').ok_or(Err::InvalidAddress)?;
51        let agent = AgentId::parse(agent_str)?;
52
53        let (inbox_str, user_str) = left.rsplit_once('#').ok_or(Err::InvalidAddress)?;
54
55        let inbox = if inbox_str.is_empty() {
56            None
57        } else {
58            Some(InboxId::parse(inbox_str)?)
59        };
60
61        let user = UserId::parse(user_str)?;
62
63        Ok(Address { inbox, user, agent })
64    }
65
66    /// Get the canonical string representation of the address.
67    /// https://gitlab.com/relay-mail/docs/-/wikis/Architecture/Identity#canonical-form
68    pub fn canonical(&self) -> String {
69        match &self.inbox {
70            Some(inbox) => format!(
71                "{}#{}@{}",
72                inbox.canonical(),
73                self.user.canonical(),
74                self.agent.canonical()
75            ),
76            None => format!("#{}@{}", self.user.canonical(), self.agent.canonical()),
77        }
78    }
79
80    /// Get inbox id.
81    pub fn inbox(&self) -> Option<&InboxId> {
82        self.inbox.as_ref()
83    }
84
85    /// Get user id.
86    pub fn user(&self) -> &UserId {
87        &self.user
88    }
89
90    /// Get agent id.
91    pub fn agent(&self) -> &AgentId {
92        &self.agent
93    }
94}
95
96impl std::fmt::Display for Address {
97    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
98        write!(f, "{}", self.canonical())
99    }
100}
101
102#[cfg(test)]
103mod tests {
104    use super::*;
105
106    #[test]
107    fn parses_and_canonicalizes() {
108        assert_eq!(
109            Address::parse("#Bob@example.org").unwrap().canonical(),
110            "#bob@example.org"
111        );
112        assert_eq!(
113            Address::parse("wORk#Bob@example.ORG").unwrap().canonical(),
114            "work#bob@example.org"
115        );
116    }
117
118    #[test]
119    #[should_panic(expected = "called `Result::unwrap()` on an `Err` value: InvalidAddress")]
120    fn rejects_empty() {
121        let _ = Address::parse("").unwrap();
122    }
123
124    #[test]
125    #[should_panic(expected = "called `Result::unwrap()` on an `Err` value: InvalidAddress")]
126    fn rejects_invalid_chars() {
127        let _ = Address::parse("Invalid Address!").unwrap();
128    }
129
130    #[test]
131    #[should_panic(expected = "called `Result::unwrap()` on an `Err` value: InvalidAddress")]
132    fn reject_untrimmed() {
133        let _ = Address::parse("  trim_me  ").unwrap();
134    }
135
136    #[test]
137    #[should_panic(expected = "called `Result::unwrap()` on an `Err` value: InvalidAddress")]
138    fn rejects_non_ascii() {
139        let _ = Address::parse("调试输出").unwrap();
140    }
141
142    #[test]
143    #[should_panic(expected = "called `Result::unwrap()` on an `Err` value: InvalidIdentityString")]
144    fn rejects_homoglyphs() {
145        let _ = Address::parse("wоrk#аlice@us.exaмple.org").unwrap(); // Cyrillic 'о', 'а', 'м'
146    }
147}
relay_core/identity/address.rs

relay_core/identity/
address.rs
