diff --git a/ruma-common/src/thirdparty.rs b/ruma-common/src/thirdparty.rs index da88c3ae..70c561fa 100644 --- a/ruma-common/src/thirdparty.rs +++ b/ruma-common/src/thirdparty.rs @@ -9,7 +9,11 @@ use ruma_identifiers::{RoomAliasId, UserId}; use serde::{Deserialize, Serialize}; /// Metadata about a third party protocol. +/// +/// To create an instance of this type, first create a `ProtocolInit` and convert it via +/// `Protocol::from` / `.into()`. #[derive(Clone, Debug, Deserialize, Serialize)] +#[non_exhaustive] pub struct Protocol { /// Fields which may be used to identify a third party user. pub user_fields: Vec, @@ -27,8 +31,41 @@ pub struct Protocol { pub instances: Vec, } +/// Initial set of fields of `Protocol`. +/// +/// This struct will not be updated even if additional fields are added to `Prococol` in a new +/// (non-breaking) release of the Matrix specification. +#[derive(Debug)] +pub struct ProtocolInit { + /// Fields which may be used to identify a third party user. + pub user_fields: Vec, + + /// Fields which may be used to identify a third party location. + pub location_fields: Vec, + + /// A content URI representing an icon for the third party protocol. + pub icon: String, + + /// The type definitions for the fields defined in `user_fields` and `location_fields`. + pub field_types: BTreeMap, + + /// A list of objects representing independent instances of configuration. + pub instances: Vec, +} + +impl From for Protocol { + fn from(init: ProtocolInit) -> Self { + let ProtocolInit { user_fields, location_fields, icon, field_types, instances } = init; + Self { user_fields, location_fields, icon, field_types, instances } + } +} + /// Metadata about an instance of a third party protocol. +/// +/// To create an instance of this type, first create a `ProtocolInstanceInit` and convert it via +/// `ProtocolInstance::from` / `.into()`. #[derive(Clone, Debug, Deserialize, Serialize)] +#[non_exhaustive] pub struct ProtocolInstance { /// A human-readable description for the protocol, such as the name. pub desc: String, @@ -44,8 +81,35 @@ pub struct ProtocolInstance { pub network_id: String, } +/// Initial set of fields of `Protocol`. +/// +/// This struct will not be updated even if additional fields are added to `Prococol` in a new +/// (non-breaking) release of the Matrix specification. +#[derive(Debug)] +pub struct ProtocolInstanceInit { + /// A human-readable description for the protocol, such as the name. + pub desc: String, + + /// Preset values for `fields` the client may use to search by. + pub fields: BTreeMap, + + /// A unique identifier across all instances. + pub network_id: String, +} + +impl From for ProtocolInstance { + fn from(init: ProtocolInstanceInit) -> Self { + let ProtocolInstanceInit { desc, fields, network_id } = init; + Self { desc, icon: None, fields, network_id } + } +} + /// A type definition for a field used to identify third party users or locations. +/// +/// To create an instance of this type, first create a `FieldTypeInit` and convert it via +/// `FieldType::from` / `.into()`. #[derive(Clone, Debug, Deserialize, Serialize)] +#[non_exhaustive] pub struct FieldType { /// A regular expression for validation of a field's value. pub regexp: String, @@ -54,8 +118,29 @@ pub struct FieldType { pub placeholder: String, } +/// Initial set of fields of `FieldType`. +/// +/// This struct will not be updated even if additional fields are added to `FieldType` in a new +/// (non-breaking) release of the Matrix specification. +#[derive(Debug)] +pub struct FieldTypeInit { + /// A regular expression for validation of a field's value. + pub regexp: String, + + /// A placeholder serving as a valid example of the field value. + pub placeholder: String, +} + +impl From for FieldType { + fn from(init: FieldTypeInit) -> Self { + let FieldTypeInit { regexp, placeholder } = init; + Self { regexp, placeholder } + } +} + /// A third party network location. #[derive(Clone, Debug, Deserialize, Serialize)] +#[non_exhaustive] pub struct Location { /// An alias for a matrix room. pub alias: RoomAliasId, @@ -67,6 +152,13 @@ pub struct Location { pub fields: BTreeMap, } +impl Location { + /// Creates a new `Location` with the given alias, protocol and fields. + pub fn new(alias: RoomAliasId, protocol: String, fields: BTreeMap) -> Self { + Self { alias, protocol, fields } + } +} + /// A third party network user. #[derive(Clone, Debug, Deserialize, Serialize)] pub struct User { @@ -80,8 +172,16 @@ pub struct User { pub fields: BTreeMap, } +impl User { + /// Creates a new `User` with the given userid, protocol and fields. + pub fn new(userid: UserId, protocol: String, fields: BTreeMap) -> Self { + Self { userid, protocol, fields } + } +} + /// The medium of a third party identifier. #[derive(Clone, Copy, Debug, PartialEq, Eq, Deserialize, Serialize)] +#[non_exhaustive] #[serde(rename_all = "lowercase")] pub enum Medium { /// Email address identifier