thirdparty: Move instance_id field out of unstable-unspecified

Requires to have two different ProtocolInstance types, as this field is added by the homeserver to the response returned by the appservice.

crates/ruma-appservice-api/CHANGELOG.md

@@ -2,6 +2,35 @@
 
 Breaking changes:
 
+- The`thirdparty::get_protocol` response uses `AppserviceProtocolInstance`
+  instead of `ProtocolInstance`.
+
+# 0.12.1
+
+Improvements:
+
+- Move unstable support for sending to-device events to appservices from
+  `unstable-msc2409` to `unstable-msc4203`.
+- Stabilize support for sending ephemeral data to appservices according to
+  Matrix 1.13.
+  - `Edu` was renamed to `EphemeralData` and uses the types from ruma-events.
+  - Custom data can be accessed with the `EphemeralData::data()` method.
+  - The `unstable-msc2409` cargo feature was removed.
+
+# 0.12.0
+
+Improvements:
+
+- The `unstable-exhaustive-types` cargo feature was replaced by the
+  `ruma_unstable_exhaustive_types` compile-time `cfg` setting. Like all `cfg`
+  settings, it can be enabled at compile-time with the `RUSTFLAGS` environment
+  variable, or inside `.cargo/config.toml`. It can also be enabled by setting
+  the `RUMA_UNSTABLE_EXHAUSTIVE_TYPES` environment variable.
+
+# 0.11.0
+
+Breaking changes:
+
 - Use `OwnedOneTimeKeyId` and `OneTimeKeyAlgorithm` instead of
   `OwnedDeviceKeyId` and `DeviceKeyAlgorithm` respectively to identify one-time
   and fallback keys and their algorithm.

crates/ruma-appservice-api/src/thirdparty/get_protocol.rs

@@ -7,11 +7,14 @@ pub mod v1 {
     //!
     //! [spec]: https://spec.matrix.org/latest/application-service-api/#get_matrixappv1thirdpartyprotocolprotocol
 
+    use std::collections::BTreeMap;
+
     use ruma_common::{
         api::{request, response, Metadata},
         metadata,
-        thirdparty::Protocol,
+        thirdparty::{Protocol, ProtocolInstance, ProtocolInstanceInit},
     };
+    use serde::{Deserialize, Serialize};
 
     const METADATA: Metadata = metadata! {
         method: GET,
@@ -35,7 +38,7 @@ pub mod v1 {
     pub struct Response {
         /// Metadata about the protocol.
         #[ruma_api(body)]
-        pub protocol: Protocol,
+        pub protocol: AppserviceProtocol,
     }
 
     impl Request {
@@ -47,8 +50,55 @@ pub mod v1 {
 
     impl Response {
         /// Creates a new `Response` with the given protocol.
-        pub fn new(protocol: Protocol) -> Self {
+        pub fn new(protocol: AppserviceProtocol) -> Self {
             Self { protocol }
         }
     }
+
+    /// Metadata about a third party protocol, as returned by an appservice to a homeserver.
+    ///
+    /// To create an instance of this type, first create a [`ProtocolInit`] and convert it via
+    /// `AppserviceProtocol::from` / `.into()`.
+    ///
+    /// [`ProtocolInit`]: ruma_common::thirdparty::ProtocolInit
+    pub type AppserviceProtocol = Protocol<AppserviceProtocolInstance>;
+
+    /// Metadata about an instance of a third party protocol, as returned by an appservice to a
+    /// homeserver.
+    ///
+    /// To create an instance of this type, first create a [`ProtocolInstanceInit`] and convert it
+    /// via `AppserviceProtocolInstance::from` / `.into()`.
+    #[derive(Clone, Debug, Deserialize, Serialize)]
+    #[cfg_attr(not(ruma_unstable_exhaustive_types), non_exhaustive)]
+    pub struct AppserviceProtocolInstance {
+        /// A human-readable description for the protocol, such as the name.
+        pub desc: String,
+
+        /// An optional content URI representing the protocol.
+        #[serde(skip_serializing_if = "Option::is_none")]
+        pub icon: Option<String>,
+
+        /// Preset values for `fields` the client may use to search by.
+        pub fields: BTreeMap<String, String>,
+
+        /// A unique identifier across all instances.
+        pub network_id: String,
+    }
+
+    impl From<ProtocolInstanceInit> for AppserviceProtocolInstance {
+        fn from(init: ProtocolInstanceInit) -> Self {
+            let ProtocolInstanceInit { desc, fields, network_id } = init;
+            Self { desc, icon: None, fields, network_id }
+        }
+    }
+
+    impl From<AppserviceProtocolInstance> for ProtocolInstance {
+        fn from(value: AppserviceProtocolInstance) -> Self {
+            let AppserviceProtocolInstance { desc, icon, fields, network_id } = value;
+            let mut instance =
+                ProtocolInstance::from(ProtocolInstanceInit { desc, fields, network_id });
+            instance.icon = icon;
+            instance
+        }
+    }
 }

crates/ruma-common/CHANGELOG.md

@@ -17,6 +17,10 @@ Breaking changes:
 - `MatrixVersion` does not implement `Display` anymore as it is not correct to
   convert `V1_0` to a string. Instead `MatrixVersion::as_str()` can be used that
   only returns `None` for that same variant.
+- `MatrixVersion::(into/from)_parts` are no longer exposed as public methods.
+  They were usually used to sort `MatrixVersion`s, now the `PartialOrd` and
+  `Ord` implementations can be used instead.
+- `Protocol` and `ProtocolInit` are generic on the protocol instance type.
 
 Bug fixes:
 
@@ -27,6 +31,8 @@ Improvements:
 
 - `MatrixVersion` implements `PartialOrd` and `Ord`. The variants are ordered by
   release date, with a newer version being greater than an older version.
+- `ProtocolInstance` has an `instance_id` field, due to a clarification in the
+  spec.
 
 # 0.15.1
 

crates/ruma-common/src/thirdparty.rs

@@ -15,11 +15,11 @@ use crate::{
 
 /// Metadata about a third party protocol.
 ///
-/// To create an instance of this type, first create a `ProtocolInit` and convert it via
+/// To create an instance of this type, first create a [`ProtocolInit`] and convert it via
 /// `Protocol::from` / `.into()`.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
-pub struct Protocol {
+pub struct Protocol<I = ProtocolInstance> {
     /// Fields which may be used to identify a third party user.
     pub user_fields: Vec<String>,
 
@@ -37,16 +37,30 @@ pub struct Protocol {
     pub field_types: BTreeMap<String, FieldType>,
 
     /// A list of objects representing independent instances of configuration.
-    pub instances: Vec<ProtocolInstance>,
+    pub instances: Vec<I>,
 }
 
-/// Initial set of fields of `Protocol`.
+impl<I> Protocol<I> {
+    /// Convert this `Protocol<I>` to a `Protocol<J>`.
+    pub fn into<J: From<I>>(self) -> Protocol<J> {
+        let Self { user_fields, location_fields, icon, field_types, instances } = self;
+        Protocol {
+            user_fields,
+            location_fields,
+            icon,
+            field_types,
+            instances: instances.into_iter().map(J::from).collect(),
+        }
+    }
+}
+
+/// 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.
+/// This struct will not be updated even if additional fields are added to [`Protocol`] in
+/// a new (non-breaking) release of the Matrix specification.
 #[derive(Debug)]
 #[allow(clippy::exhaustive_structs)]
-pub struct ProtocolInit {
+pub struct ProtocolInit<I = ProtocolInstance> {
     /// Fields which may be used to identify a third party user.
     pub user_fields: Vec<String>,
 
@@ -60,20 +74,20 @@ pub struct ProtocolInit {
     pub field_types: BTreeMap<String, FieldType>,
 
     /// A list of objects representing independent instances of configuration.
-    pub instances: Vec<ProtocolInstance>,
+    pub instances: Vec<I>,
 }
 
-impl From<ProtocolInit> for Protocol {
-    fn from(init: ProtocolInit) -> Self {
+impl<I> From<ProtocolInit<I>> for Protocol<I> {
+    fn from(init: ProtocolInit<I>) -> 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.
+/// Metadata about an instance of a third party protocol, as returned by a homeserver to a client.
 ///
-/// To create an instance of this type, first create a `ProtocolInstanceInit` and convert it via
-/// `ProtocolInstance::from` / `.into()`.
+/// To create an instance of this type, first create a [`ProtocolInstanceInit`] or an
+/// `AppserviceProtocolInstance` and convert it via `ProtocolInstance::from` / `.into()`.
 #[derive(Clone, Debug, Deserialize, Serialize)]
 #[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
 pub struct ProtocolInstance {
@@ -90,18 +104,21 @@ pub struct ProtocolInstance {
     /// A unique identifier across all instances.
     pub network_id: String,
 
-    /// A unique identifier across all instances.
+    /// A unique identifier for this instance on the homeserver.
     ///
-    /// See [matrix-spec#833](https://github.com/matrix-org/matrix-spec/issues/833).
-    #[cfg(feature = "unstable-unspecified")]
+    /// This is a field added by the homeserver to `AppserviceProtocolInstance`. It can be used as
+    /// the value of [`RoomNetwork::ThirdParty`] in a request to the `get_public_rooms_filtered`
+    /// endpoint.
+    ///
+    /// [`RoomNetwork::ThirdParty`]: crate::directory::RoomNetwork::ThirdParty
     #[serde(skip_serializing_if = "Option::is_none")]
     pub instance_id: Option<String>,
 }
 
-/// Initial set of fields of `Protocol`.
+/// Initial set of fields of [`ProtocolInstance`].
 ///
-/// This struct will not be updated even if additional fields are added to `Prococol` in a new
-/// (non-breaking) release of the Matrix specification.
+/// This struct will not be updated even if additional fields are added to [`ProtocolInstance`] in a
+/// new (non-breaking) release of the Matrix specification.
 #[derive(Debug)]
 #[allow(clippy::exhaustive_structs)]
 pub struct ProtocolInstanceInit {
@@ -118,14 +135,7 @@ pub struct ProtocolInstanceInit {
 impl From<ProtocolInstanceInit> for ProtocolInstance {
     fn from(init: ProtocolInstanceInit) -> Self {
         let ProtocolInstanceInit { desc, fields, network_id } = init;
-        Self {
-            desc,
-            icon: None,
-            fields,
-            network_id,
-            #[cfg(feature = "unstable-unspecified")]
-            instance_id: None,
-        }
+        Self { desc, icon: None, fields, network_id, instance_id: None }
     }
 }