ruma_common/identifiers/
room_or_alias_id.rs

1//! Matrix identifiers for places where a room ID or room alias ID are used interchangeably.
2
3use std::hint::unreachable_unchecked;
4
5use ruma_macros::IdDst;
6use tracing::warn;
7
8use super::{OwnedRoomAliasId, OwnedRoomId, RoomAliasId, RoomId, server_name::ServerName};
9
10/// A Matrix [room ID] or a Matrix [room alias ID].
11///
12/// `RoomOrAliasId` is useful for APIs that accept either kind of room identifier. It is converted
13/// from a string slice, and can be converted back into a string as needed. When converted from a
14/// string slice, the variant is determined by the leading sigil character.
15///
16/// ```
17/// # use ruma_common::RoomOrAliasId;
18/// assert_eq!(<&RoomOrAliasId>::try_from("#ruma:example.com").unwrap(), "#ruma:example.com");
19///
20/// assert_eq!(
21///     <&RoomOrAliasId>::try_from("!n8f893n9:example.com").unwrap(),
22///     "!n8f893n9:example.com"
23/// );
24/// ```
25///
26/// It can be converted to a `RoomId` or a `RoomAliasId` using `::try_from()` / `.try_into()`.
27/// For example, `<&RoomId>::try_from(room_or_alias_id)` returns either `Ok(room_id)` or
28/// `Err(room_alias_id)`.
29///
30/// [room ID]: https://spec.matrix.org/latest/appendices/#room-ids
31/// [room alias ID]: https://spec.matrix.org/latest/appendices/#room-aliases
32#[repr(transparent)]
33#[derive(PartialEq, Eq, PartialOrd, Ord, Hash, IdDst)]
34#[ruma_id(validate = ruma_identifiers_validation::room_id_or_alias_id::validate)]
35pub struct RoomOrAliasId(str);
36
37impl RoomOrAliasId {
38    /// Returns the server name of the room (alias) ID.
39    pub fn server_name(&self) -> Option<&ServerName> {
40        let colon_idx = self.as_str().find(':')?;
41        let server_name = &self.as_str()[colon_idx + 1..];
42        match server_name.try_into() {
43            Ok(parsed) => Some(parsed),
44            // Room aliases are verified to contain a server name at parse time
45            Err(e) => {
46                warn!(
47                    target: "ruma_common::identifiers::room_id",
48                    server_name,
49                    "Room ID contains colon but no valid server name afterwards: {e}",
50                );
51                None
52            }
53        }
54    }
55
56    /// Whether this is a room id (starts with `'!'`)
57    pub fn is_room_id(&self) -> bool {
58        self.variant() == Variant::RoomId
59    }
60
61    /// Whether this is a room alias id (starts with `'#'`)
62    pub fn is_room_alias_id(&self) -> bool {
63        self.variant() == Variant::RoomAliasId
64    }
65
66    fn variant(&self) -> Variant {
67        match self.as_bytes().first() {
68            Some(b'!') => Variant::RoomId,
69            Some(b'#') => Variant::RoomAliasId,
70            _ => unsafe { unreachable_unchecked() },
71        }
72    }
73}
74
75#[derive(PartialEq, Eq)]
76enum Variant {
77    RoomId,
78    RoomAliasId,
79}
80
81impl<'a> From<&'a RoomId> for &'a RoomOrAliasId {
82    fn from(room_id: &'a RoomId) -> Self {
83        RoomOrAliasId::from_borrowed_unchecked(room_id.as_str())
84    }
85}
86
87impl<'a> From<&'a RoomAliasId> for &'a RoomOrAliasId {
88    fn from(room_alias_id: &'a RoomAliasId) -> Self {
89        RoomOrAliasId::from_borrowed_unchecked(room_alias_id.as_str())
90    }
91}
92
93impl From<OwnedRoomId> for OwnedRoomOrAliasId {
94    fn from(room_id: OwnedRoomId) -> Self {
95        unsafe { Self::from_inner_unchecked(room_id.into_inner()) }
96    }
97}
98
99impl From<OwnedRoomAliasId> for OwnedRoomOrAliasId {
100    fn from(room_alias_id: OwnedRoomAliasId) -> Self {
101        unsafe { Self::from_inner_unchecked(room_alias_id.into_inner()) }
102    }
103}
104
105impl<'a> TryFrom<&'a RoomOrAliasId> for &'a RoomId {
106    type Error = &'a RoomAliasId;
107
108    fn try_from(id: &'a RoomOrAliasId) -> Result<&'a RoomId, &'a RoomAliasId> {
109        match id.variant() {
110            Variant::RoomId => Ok(RoomId::from_borrowed_unchecked(id.as_str())),
111            Variant::RoomAliasId => Err(RoomAliasId::from_borrowed_unchecked(id.as_str())),
112        }
113    }
114}
115
116impl<'a> TryFrom<&'a RoomOrAliasId> for &'a RoomAliasId {
117    type Error = &'a RoomId;
118
119    fn try_from(id: &'a RoomOrAliasId) -> Result<&'a RoomAliasId, &'a RoomId> {
120        match id.variant() {
121            Variant::RoomAliasId => Ok(RoomAliasId::from_borrowed_unchecked(id.as_str())),
122            Variant::RoomId => Err(RoomId::from_borrowed_unchecked(id.as_str())),
123        }
124    }
125}
126
127impl TryFrom<OwnedRoomOrAliasId> for OwnedRoomId {
128    type Error = OwnedRoomAliasId;
129
130    fn try_from(id: OwnedRoomOrAliasId) -> Result<OwnedRoomId, OwnedRoomAliasId> {
131        let variant = id.variant();
132        let inner = id.into_inner();
133
134        unsafe {
135            match variant {
136                Variant::RoomId => Ok(Self::from_inner_unchecked(inner)),
137                Variant::RoomAliasId => Err(OwnedRoomAliasId::from_inner_unchecked(inner)),
138            }
139        }
140    }
141}
142
143impl TryFrom<OwnedRoomOrAliasId> for OwnedRoomAliasId {
144    type Error = OwnedRoomId;
145
146    fn try_from(id: OwnedRoomOrAliasId) -> Result<OwnedRoomAliasId, OwnedRoomId> {
147        let variant = id.variant();
148        let inner = id.into_inner();
149
150        unsafe {
151            match variant {
152                Variant::RoomAliasId => Ok(Self::from_inner_unchecked(inner)),
153                Variant::RoomId => Err(OwnedRoomId::from_inner_unchecked(inner)),
154            }
155        }
156    }
157}
158
159#[cfg(test)]
160mod tests {
161    use super::{OwnedRoomOrAliasId, RoomOrAliasId};
162    use crate::IdParseError;
163
164    #[test]
165    fn valid_room_id_or_alias_id_with_a_room_alias_id() {
166        assert_eq!(
167            <&RoomOrAliasId>::try_from("#ruma:example.com")
168                .expect("Failed to create RoomAliasId.")
169                .as_str(),
170            "#ruma:example.com"
171        );
172    }
173
174    #[test]
175    fn valid_room_id_or_alias_id_with_a_room_id() {
176        assert_eq!(
177            <&RoomOrAliasId>::try_from("!29fhd83h92h0:example.com")
178                .expect("Failed to create RoomId.")
179                .as_str(),
180            "!29fhd83h92h0:example.com"
181        );
182    }
183
184    #[test]
185    fn missing_sigil_for_room_id_or_alias_id() {
186        assert_eq!(
187            <&RoomOrAliasId>::try_from("ruma:example.com").unwrap_err(),
188            IdParseError::MissingLeadingSigil
189        );
190    }
191
192    #[test]
193    fn serialize_valid_room_id_or_alias_id_with_a_room_alias_id() {
194        assert_eq!(
195            serde_json::to_string(
196                <&RoomOrAliasId>::try_from("#ruma:example.com")
197                    .expect("Failed to create RoomAliasId.")
198            )
199            .expect("Failed to convert RoomAliasId to JSON."),
200            r##""#ruma:example.com""##
201        );
202    }
203
204    #[test]
205    fn serialize_valid_room_id_or_alias_id_with_a_room_id() {
206        assert_eq!(
207            serde_json::to_string(
208                <&RoomOrAliasId>::try_from("!29fhd83h92h0:example.com")
209                    .expect("Failed to create RoomId.")
210            )
211            .expect("Failed to convert RoomId to JSON."),
212            r#""!29fhd83h92h0:example.com""#
213        );
214    }
215
216    #[test]
217    fn deserialize_valid_room_id_or_alias_id_with_a_room_alias_id() {
218        assert_eq!(
219            serde_json::from_str::<OwnedRoomOrAliasId>(r##""#ruma:example.com""##)
220                .expect("Failed to convert JSON to RoomAliasId"),
221            <&RoomOrAliasId>::try_from("#ruma:example.com").expect("Failed to create RoomAliasId.")
222        );
223    }
224
225    #[test]
226    fn deserialize_valid_room_id_or_alias_id_with_a_room_id() {
227        assert_eq!(
228            serde_json::from_str::<OwnedRoomOrAliasId>(r#""!29fhd83h92h0:example.com""#)
229                .expect("Failed to convert JSON to RoomId"),
230            <&RoomOrAliasId>::try_from("!29fhd83h92h0:example.com")
231                .expect("Failed to create RoomAliasId.")
232        );
233    }
234}
ruma_common/identifiers/room_or_alias_id.rs

ruma_common/identifiers/
room_or_alias_id.rs
