ruma_common/
thirdparty.rs

Help
1//! Common types for the [third party networks module][thirdparty].
2//!
3//! [thirdparty]: https://spec.matrix.org/latest/client-server-api/#third-party-networks
4
5use std::{
6    collections::BTreeMap,
7    hash::{Hash, Hasher},
8};
9
10use serde::{Deserialize, Serialize};
11
12use crate::{
13    serde::StringEnum, MilliSecondsSinceUnixEpoch, OwnedRoomAliasId, OwnedUserId, PrivOwnedStr,
14};
15
16/// Metadata about a third party protocol.
17///
18/// To create an instance of this type, first create a [`ProtocolInit`] and convert it via
19/// `Protocol::from` / `.into()`.
20#[derive(Clone, Debug, Deserialize, Serialize)]
21#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
22pub struct Protocol<I = ProtocolInstance> {
23    /// Fields which may be used to identify a third party user.
24    pub user_fields: Vec<String>,
25
26    /// Fields which may be used to identify a third party location.
27    pub location_fields: Vec<String>,
28
29    /// A content URI representing an icon for the third party protocol.
30    ///
31    /// If the `compat-optional` feature is enabled, this field being absent in JSON will result
32    /// in an empty string instead of an error when deserializing.
33    #[cfg_attr(feature = "compat-optional", serde(default))]
34    pub icon: String,
35
36    /// The type definitions for the fields defined in `user_fields` and `location_fields`.
37    pub field_types: BTreeMap<String, FieldType>,
38
39    /// A list of objects representing independent instances of configuration.
40    pub instances: Vec<I>,
41}
42
43impl<I> Protocol<I> {
44    /// Convert this `Protocol<I>` to a `Protocol<J>`.
45    pub fn into<J: From<I>>(self) -> Protocol<J> {
46        let Self { user_fields, location_fields, icon, field_types, instances } = self;
47        Protocol {
48            user_fields,
49            location_fields,
50            icon,
51            field_types,
52            instances: instances.into_iter().map(J::from).collect(),
53        }
54    }
55}
56
57/// Initial set of fields of [`Protocol`].
58///
59/// This struct will not be updated even if additional fields are added to [`Protocol`] in
60/// a new (non-breaking) release of the Matrix specification.
61#[derive(Debug)]
62#[allow(clippy::exhaustive_structs)]
63pub struct ProtocolInit<I = ProtocolInstance> {
64    /// Fields which may be used to identify a third party user.
65    pub user_fields: Vec<String>,
66
67    /// Fields which may be used to identify a third party location.
68    pub location_fields: Vec<String>,
69
70    /// A content URI representing an icon for the third party protocol.
71    pub icon: String,
72
73    /// The type definitions for the fields defined in `user_fields` and `location_fields`.
74    pub field_types: BTreeMap<String, FieldType>,
75
76    /// A list of objects representing independent instances of configuration.
77    pub instances: Vec<I>,
78}
79
80impl<I> From<ProtocolInit<I>> for Protocol<I> {
81    fn from(init: ProtocolInit<I>) -> Self {
82        let ProtocolInit { user_fields, location_fields, icon, field_types, instances } = init;
83        Self { user_fields, location_fields, icon, field_types, instances }
84    }
85}
86
87/// Metadata about an instance of a third party protocol, as returned by a homeserver to a client.
88///
89/// To create an instance of this type, first create a [`ProtocolInstanceInit`] or an
90/// `AppserviceProtocolInstance` and convert it via `ProtocolInstance::from` / `.into()`.
91#[derive(Clone, Debug, Deserialize, Serialize)]
92#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
93pub struct ProtocolInstance {
94    /// A human-readable description for the protocol, such as the name.
95    pub desc: String,
96
97    /// An optional content URI representing the protocol.
98    #[serde(skip_serializing_if = "Option::is_none")]
99    pub icon: Option<String>,
100
101    /// Preset values for `fields` the client may use to search by.
102    pub fields: BTreeMap<String, String>,
103
104    /// A unique identifier across all instances.
105    pub network_id: String,
106
107    /// A unique identifier for this instance on the homeserver.
108    ///
109    /// This is a field added by the homeserver to `AppserviceProtocolInstance`. It can be used as
110    /// the value of [`RoomNetwork::ThirdParty`] in a request to the `get_public_rooms_filtered`
111    /// endpoint.
112    ///
113    /// [`RoomNetwork::ThirdParty`]: crate::directory::RoomNetwork::ThirdParty
114    #[serde(skip_serializing_if = "Option::is_none")]
115    pub instance_id: Option<String>,
116}
117
118/// Initial set of fields of [`ProtocolInstance`].
119///
120/// This struct will not be updated even if additional fields are added to [`ProtocolInstance`] in a
121/// new (non-breaking) release of the Matrix specification.
122#[derive(Debug)]
123#[allow(clippy::exhaustive_structs)]
124pub struct ProtocolInstanceInit {
125    /// A human-readable description for the protocol, such as the name.
126    pub desc: String,
127
128    /// Preset values for `fields` the client may use to search by.
129    pub fields: BTreeMap<String, String>,
130
131    /// A unique identifier across all instances.
132    pub network_id: String,
133}
134
135impl From<ProtocolInstanceInit> for ProtocolInstance {
136    fn from(init: ProtocolInstanceInit) -> Self {
137        let ProtocolInstanceInit { desc, fields, network_id } = init;
138        Self { desc, icon: None, fields, network_id, instance_id: None }
139    }
140}
141
142/// A type definition for a field used to identify third party users or locations.
143///
144/// To create an instance of this type, first create a `FieldTypeInit` and convert it via
145/// `FieldType::from` / `.into()`.
146#[derive(Clone, Debug, Deserialize, Serialize)]
147#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
148pub struct FieldType {
149    /// A regular expression for validation of a field's value.
150    pub regexp: String,
151
152    /// A placeholder serving as a valid example of the field value.
153    pub placeholder: String,
154}
155
156/// Initial set of fields of `FieldType`.
157///
158/// This struct will not be updated even if additional fields are added to `FieldType` in a new
159/// (non-breaking) release of the Matrix specification.
160#[derive(Debug)]
161#[allow(clippy::exhaustive_structs)]
162pub struct FieldTypeInit {
163    /// A regular expression for validation of a field's value.
164    pub regexp: String,
165
166    /// A placeholder serving as a valid example of the field value.
167    pub placeholder: String,
168}
169
170impl From<FieldTypeInit> for FieldType {
171    fn from(init: FieldTypeInit) -> Self {
172        let FieldTypeInit { regexp, placeholder } = init;
173        Self { regexp, placeholder }
174    }
175}
176
177/// A third party network location.
178#[derive(Clone, Debug, Deserialize, Serialize)]
179#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
180pub struct Location {
181    /// An alias for a matrix room.
182    pub alias: OwnedRoomAliasId,
183
184    /// The protocol ID that the third party location is a part of.
185    pub protocol: String,
186
187    /// Information used to identify this third party location.
188    pub fields: BTreeMap<String, String>,
189}
190
191impl Location {
192    /// Creates a new `Location` with the given alias, protocol and fields.
193    pub fn new(
194        alias: OwnedRoomAliasId,
195        protocol: String,
196        fields: BTreeMap<String, String>,
197    ) -> Self {
198        Self { alias, protocol, fields }
199    }
200}
201
202/// A third party network user.
203#[derive(Clone, Debug, Deserialize, Serialize)]
204#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
205pub struct User {
206    /// A matrix user ID representing a third party user.
207    pub userid: OwnedUserId,
208
209    /// The protocol ID that the third party user is a part of.
210    pub protocol: String,
211
212    /// Information used to identify this third party user.
213    pub fields: BTreeMap<String, String>,
214}
215
216impl User {
217    /// Creates a new `User` with the given userid, protocol and fields.
218    pub fn new(userid: OwnedUserId, protocol: String, fields: BTreeMap<String, String>) -> Self {
219        Self { userid, protocol, fields }
220    }
221}
222
223/// The medium of a third party identifier.
224#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
225#[derive(Clone, PartialEq, Eq, StringEnum)]
226#[ruma_enum(rename_all = "lowercase")]
227#[non_exhaustive]
228pub enum Medium {
229    /// Email address identifier
230    Email,
231
232    /// Phone number identifier
233    Msisdn,
234
235    #[doc(hidden)]
236    _Custom(PrivOwnedStr),
237}
238
239/// An identifier external to Matrix.
240///
241/// To create an instance of this type, first create a `ThirdPartyIdentifierInit` and convert it to
242/// this type using `ThirdPartyIdentifier::Init` / `.into()`.
243#[derive(Clone, Debug, Deserialize, Serialize)]
244#[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
245pub struct ThirdPartyIdentifier {
246    /// The third party identifier address.
247    pub address: String,
248
249    /// The medium of third party identifier.
250    pub medium: Medium,
251
252    /// The time when the identifier was validated by the identity server.
253    pub validated_at: MilliSecondsSinceUnixEpoch,
254
255    /// The time when the homeserver associated the third party identifier with the user.
256    pub added_at: MilliSecondsSinceUnixEpoch,
257}
258
259impl Eq for ThirdPartyIdentifier {}
260
261impl Hash for ThirdPartyIdentifier {
262    fn hash<H: Hasher>(&self, hasher: &mut H) {
263        (self.medium.as_str(), &self.address).hash(hasher);
264    }
265}
266
267impl PartialEq for ThirdPartyIdentifier {
268    fn eq(&self, other: &ThirdPartyIdentifier) -> bool {
269        self.address == other.address && self.medium == other.medium
270    }
271}
272
273/// Initial set of fields of `ThirdPartyIdentifier`.
274///
275/// This struct will not be updated even if additional fields are added to `ThirdPartyIdentifier`
276/// in a new (non-breaking) release of the Matrix specification.
277#[derive(Debug)]
278#[allow(clippy::exhaustive_structs)]
279pub struct ThirdPartyIdentifierInit {
280    /// The third party identifier address.
281    pub address: String,
282
283    /// The medium of third party identifier.
284    pub medium: Medium,
285
286    /// The time when the identifier was validated by the identity server.
287    pub validated_at: MilliSecondsSinceUnixEpoch,
288
289    /// The time when the homeserver associated the third party identifier with the user.
290    pub added_at: MilliSecondsSinceUnixEpoch,
291}
292
293impl From<ThirdPartyIdentifierInit> for ThirdPartyIdentifier {
294    fn from(init: ThirdPartyIdentifierInit) -> Self {
295        let ThirdPartyIdentifierInit { address, medium, validated_at, added_at } = init;
296        ThirdPartyIdentifier { address, medium, validated_at, added_at }
297    }
298}
299
300#[cfg(test)]
301mod tests {
302    use serde_json::{from_value as from_json_value, json, to_value as to_json_value};
303
304    use super::{Medium, ThirdPartyIdentifier};
305    use crate::MilliSecondsSinceUnixEpoch;
306
307    #[test]
308    fn third_party_identifier_serde() {
309        let third_party_id = ThirdPartyIdentifier {
310            address: "monkey@banana.island".into(),
311            medium: Medium::Email,
312            validated_at: MilliSecondsSinceUnixEpoch(1_535_176_800_000_u64.try_into().unwrap()),
313            added_at: MilliSecondsSinceUnixEpoch(1_535_336_848_756_u64.try_into().unwrap()),
314        };
315
316        let third_party_id_serialized = json!({
317            "medium": "email",
318            "address": "monkey@banana.island",
319            "validated_at": 1_535_176_800_000_u64,
320            "added_at": 1_535_336_848_756_u64
321        });
322
323        assert_eq!(to_json_value(third_party_id.clone()).unwrap(), third_party_id_serialized);
324        assert_eq!(third_party_id, from_json_value(third_party_id_serialized).unwrap());
325    }
326}
ruma_common/thirdparty.rs

ruma_common/
thirdparty.rs
