client-api: Add support for private read receipts

According to MSC2285

crates/ruma-client-api/CHANGELOG.md

@@ -6,6 +6,7 @@ Breaking changes:
   * If the lack of such an `impl` causes problems, please open a GitHub issue
 * Split `uiaa::UserIdentifier::ThirdParty` into two separate variants
 * Make `message::get_message_events::v3::Request::new`'s `from` parameter optional
+* `receipt::create_receipt` uses its own `ReceiptType`
 
 Improvements:
 
@@ -16,6 +17,7 @@ Improvements:
 * Move `filter::RelationType` to `ruma_common::events::relations`
 * Add unstable support for discovering an OpenID Connect server (MSC2965)
 * Add `SpaceRoomJoinRule::KnockRestricted` (MSC3787)
+* Add unstable support for private read receipts (MSC2285)
 
 # 0.14.1
 

crates/ruma-client-api/Cargo.toml

@@ -19,6 +19,7 @@ rustdoc-args = ["--cfg", "docsrs"]
 compat = []
 unstable-exhaustive-types = []
 unstable-msc2246 = []
+unstable-msc2285 = []
 unstable-msc2666 = []
 unstable-msc2448 = []
 unstable-msc2654 = []

crates/ruma-client-api/src/read_marker/set_read_marker.rs

@@ -3,7 +3,11 @@
 pub mod v3 {
     //! `/v3/` ([spec])
     //!
+    //! This endpoint is equivalent to calling the [`create_receipt`] endpoint,
+    //! but is provided as a way to update several read markers with a single call.
+    //!
     //! [spec]: https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidread_markers
+    //! [`create_receipt`]: crate::receipt::create_receipt
 
     use ruma_common::{api::ruma_api, EventId, RoomId};
 
@@ -24,18 +28,50 @@ pub mod v3 {
             #[ruma_api(path)]
             pub room_id: &'a RoomId,
 
-            /// The event ID the read marker should be located at.
+            /// The event ID the fully-read marker should be located at.
             ///
             /// The event MUST belong to the room.
+            ///
+            /// With the `unstable-msc2285` feature, this field is optional.
+            #[cfg(not(feature = "unstable-msc2285"))]
             #[serde(rename = "m.fully_read")]
             pub fully_read: &'a EventId,
 
-            /// The event ID to set the read receipt location at.
+            /// The event ID the fully-read marker should be located at.
             ///
-            /// This is equivalent to calling the create_read_receipt endpoint and is provided here to
+            /// The event MUST belong to the room.
-            /// save that extra call.
+            ///
+            /// This is equivalent to calling the [`create_receipt`] endpoint with a
+            /// [`ReceiptType::FullyRead`].
+            ///
+            /// Without the `unstable-msc2285` feature, this field is required.
+            ///
+            /// [`create_receipt`]: crate::receipt::create_receipt
+            /// [`ReceiptType::FullyRead`]: crate::receipt::create_receipt::v3::ReceiptType::FullyRead
+            #[cfg(feature = "unstable-msc2285")]
+            #[serde(rename = "m.fully_read")]
+            pub fully_read: Option<&'a EventId>,
+
+            /// The event ID to set the public read receipt location at.
+            ///
+            /// This is equivalent to calling the [`create_receipt`] endpoint with a
+            /// [`ReceiptType::Read`].
+            ///
+            /// [`create_receipt`]: crate::receipt::create_receipt
+            /// [`ReceiptType::Read`]: crate::receipt::create_receipt::v3::ReceiptType::Read
             #[serde(rename = "m.read", skip_serializing_if = "Option::is_none")]
             pub read_receipt: Option<&'a EventId>,
+
+            /// The event ID to set the private read receipt location at.
+            ///
+            /// This is equivalent to calling the [`create_receipt`] endpoint with a
+            /// [`ReceiptType::ReadPrivate`].
+            ///
+            /// [`create_receipt`]: crate::receipt::create_receipt
+            /// [`ReceiptType::ReadPrivate`]: crate::receipt::create_receipt::v3::ReceiptType::ReadPrivate
+            #[cfg(feature = "unstable-msc2285")]
+            #[serde(rename = "org.matrix.msc2285.read.private", alias = "m.read.private", skip_serializing_if = "Option::is_none")]
+            pub private_read_receipt: Option<&'a EventId>,
         }
 
         #[derive(Default)]
@@ -46,9 +82,21 @@ pub mod v3 {
 
     impl<'a> Request<'a> {
         /// Creates a new `Request` with the given room ID and fully read event ID.
+        ///
+        /// With the `unstable-msc2285` feature, this method doesn't have the `fully_read`
+        /// parameter.
+        #[cfg(not(feature = "unstable-msc2285"))]
         pub fn new(room_id: &'a RoomId, fully_read: &'a EventId) -> Self {
             Self { room_id, fully_read, read_receipt: None }
         }
+
+        /// Creates a new `Request` with the given room ID.
+        ///
+        /// Without the `unstable-msc2285` feature, this method takes a `fully_read` parameter.
+        #[cfg(feature = "unstable-msc2285")]
+        pub fn new(room_id: &'a RoomId) -> Self {
+            Self { room_id, fully_read: None, read_receipt: None, private_read_receipt: None }
+        }
     }
 
     impl Response {

crates/ruma-client-api/src/receipt/create_receipt.rs

@@ -5,7 +5,13 @@ pub mod v3 {
     //!
     //! [spec]: https://spec.matrix.org/v1.2/client-server-api/#post_matrixclientv3roomsroomidreceiptreceipttypeeventid
 
-    use ruma_common::{api::ruma_api, receipt::ReceiptType, EventId, RoomId};
+    use ruma_common::{
+        api::ruma_api,
+        serde::{OrdAsRefStr, PartialEqAsRefStr, PartialOrdAsRefStr, StringEnum},
+        EventId, RoomId,
+    };
+
+    use crate::PrivOwnedStr;
 
     ruma_api! {
         metadata: {
@@ -52,4 +58,47 @@ pub mod v3 {
             Self {}
         }
     }
+
+    /// The type of receipt.
+    #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
+    #[derive(Clone, Debug, PartialOrdAsRefStr, OrdAsRefStr, PartialEqAsRefStr, Eq, StringEnum)]
+    #[non_exhaustive]
+    pub enum ReceiptType {
+        /// A [public read receipt].
+        ///
+        /// Indicates that the given event has been presented to the user.
+        ///
+        /// This receipt is federated to other users.
+        ///
+        /// [public read receipt]: https://spec.matrix.org/v1.3/client-server-api/#receipts
+        #[ruma_enum(rename = "m.read")]
+        Read,
+
+        /// A [private read receipt].
+        ///
+        /// Indicates that the given event has been presented to the user.
+        ///
+        /// This read receipt is not federated so only the user and their homeserver
+        /// are aware of it.
+        ///
+        /// [private read receipt]: https://github.com/matrix-org/matrix-spec-proposals/pull/2285
+        #[cfg(feature = "unstable-msc2285")]
+        #[ruma_enum(rename = "org.matrix.msc2285.read.private", alias = "m.read.private")]
+        ReadPrivate,
+
+        /// A [fully read marker].
+        ///
+        /// Indicates that the given event has been read by the user.
+        ///
+        /// This is actually not a receipt, but a piece of room account data. It is
+        /// provided here for convenience.
+        ///
+        /// [fully read marker]: https://spec.matrix.org/v1.3/client-server-api/#fully-read-markers
+        #[cfg(feature = "unstable-msc2285")]
+        #[ruma_enum(rename = "m.fully_read")]
+        FullyRead,
+
+        #[doc(hidden)]
+        _Custom(PrivOwnedStr),
+    }
 }

crates/ruma-common/src/lib.rs

@@ -35,7 +35,6 @@ mod identifiers;
 pub mod power_levels;
 pub mod presence;
 pub mod push;
-pub mod receipt;
 pub mod room;
 pub mod serde;
 pub mod thirdparty;

crates/ruma-common/src/receipt.rs

@@ -1,19 +0,0 @@
-//! Common types for receipts.
-
-use crate::{
-    serde::{OrdAsRefStr, PartialEqAsRefStr, PartialOrdAsRefStr, StringEnum},
-    PrivOwnedStr,
-};
-
-/// The type of receipt.
-#[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/string_enum.md"))]
-#[derive(Clone, Debug, PartialOrdAsRefStr, OrdAsRefStr, PartialEqAsRefStr, Eq, StringEnum)]
-#[non_exhaustive]
-pub enum ReceiptType {
-    /// m.read
-    #[ruma_enum(rename = "m.read")]
-    Read,
-
-    #[doc(hidden)]
-    _Custom(PrivOwnedStr),
-}

crates/ruma/CHANGELOG.md

@@ -1,5 +1,10 @@
 # [unreleased]
 
+Breaking changes:
+
+* The `receipt` module is no longer exported.
+  * `ReceiptType` has been split into two types under `events` and `api::client`.
+
 # 0.6.3
 
 Bug fixes:

crates/ruma/Cargo.toml

@@ -118,7 +118,10 @@ unstable-pre-spec = [
 unstable-sanitize = ["ruma-common/unstable-sanitize"]
 unstable-msc1767 = ["ruma-common/unstable-msc1767"]
 unstable-msc2246 = ["ruma-client-api?/unstable-msc2246"]
-unstable-msc2285 = ["ruma-common/unstable-msc2285"]
+unstable-msc2285 = [
+    "ruma-client-api?/unstable-msc2285",
+    "ruma-common/unstable-msc2285"
+]
 unstable-msc2448 = [
     "ruma-client-api?/unstable-msc2448",
     "ruma-common/unstable-msc2448",

crates/ruma/src/lib.rs

@@ -160,15 +160,15 @@ pub use js_int::{int, uint, Int, UInt};
 pub use ruma_client::Client;
 pub use ruma_common::{
     authentication, device_id, device_key_id, directory, encryption, event_id, exports, matrix_uri,
-    mxc_uri, power_levels, presence, push, receipt, room, room_alias_id, room_id, room_version_id,
+    mxc_uri, power_levels, presence, push, room, room_alias_id, room_id, room_version_id, serde,
-    serde, server_name, server_signing_key_id, thirdparty, to_device, user_id, ClientSecret,
+    server_name, server_signing_key_id, thirdparty, to_device, user_id, ClientSecret, DeviceId,
-    DeviceId, DeviceKeyAlgorithm, DeviceKeyId, DeviceSignatures, DeviceSigningKeyId,
+    DeviceKeyAlgorithm, DeviceKeyId, DeviceSignatures, DeviceSigningKeyId, EntitySignatures,
-    EntitySignatures, EventEncryptionAlgorithm, EventId, IdParseError, KeyId, KeyName, MatrixToUri,
+    EventEncryptionAlgorithm, EventId, IdParseError, KeyId, KeyName, MatrixToUri, MatrixUri,
-    MatrixUri, MilliSecondsSinceUnixEpoch, MxcUri, OwnedClientSecret, OwnedDeviceId,
+    MilliSecondsSinceUnixEpoch, MxcUri, OwnedClientSecret, OwnedDeviceId, OwnedDeviceKeyId,
-    OwnedDeviceKeyId, OwnedDeviceSigningKeyId, OwnedEventId, OwnedKeyId, OwnedKeyName, OwnedMxcUri,
+    OwnedDeviceSigningKeyId, OwnedEventId, OwnedKeyId, OwnedKeyName, OwnedMxcUri, OwnedRoomAliasId,
-    OwnedRoomAliasId, OwnedRoomId, OwnedRoomOrAliasId, OwnedServerName, OwnedServerSigningKeyId,
+    OwnedRoomId, OwnedRoomOrAliasId, OwnedServerName, OwnedServerSigningKeyId, OwnedSessionId,
-    OwnedSessionId, OwnedSigningKeyId, OwnedTransactionId, OwnedUserId, PrivOwnedStr, RoomAliasId,
+    OwnedSigningKeyId, OwnedTransactionId, OwnedUserId, PrivOwnedStr, RoomAliasId, RoomId,
-    RoomId, RoomOrAliasId, RoomVersionId, SecondsSinceUnixEpoch, ServerName, ServerSignatures,
+    RoomOrAliasId, RoomVersionId, SecondsSinceUnixEpoch, ServerName, ServerSignatures,
     ServerSigningKeyId, SessionId, Signatures, SigningKeyAlgorithm, TransactionId, UserId,
 };
 #[cfg(feature = "canonical-json")]