events: Add support for intentional mentions

According to MSC3952

Author: zecakeh

crates/ruma-common/CHANGELOG.md

@@ -20,8 +20,10 @@ Breaking changes:
   - Remove `SessionDescriptionType`, use a `String` instead. A clarification in MSC2746 / Matrix 1.7
     explains that the `type` field should not be validated but passed as-is to the WebRTC API. It
     also avoids an unnecessary conversion between the WebRTC API and the Ruma type.
-- The `reason` field in `CallHangupEventContent` is now required an defaults to `Reason::UserHangup`
+- The `reason` field in `CallHangupEventContent` is now required and defaults to `Reason::UserHangup`
   (MSC2746 / Matrix 1.7)
+- The `Replacement` relation for `RoomMessageEventContent` now takes a
+  `RoomMessageEventContentWithoutRelation` instead of a `MessageType`
 
 Improvements:
 
@@ -50,6 +52,7 @@ Improvements:
 - Stabilize support for VoIP signalling improvements (MSC2746 / Matrix 1.7)
 - Make the generated and stripped plain text reply fallback behavior more compatible with most
   of the Matrix ecosystem.
+- Add support for intentional mentions according to MSC3952 / Matrix 1.7
 
 # 0.11.3
 

crates/ruma-common/src/events.rs

@@ -102,9 +102,9 @@
 //! ));
 //! ```
 
-use serde::{de::IgnoredAny, Deserialize, Serializer};
+use serde::{de::IgnoredAny, Deserialize, Serialize, Serializer};
 
-use crate::{EventEncryptionAlgorithm, RoomVersionId};
+use crate::{EventEncryptionAlgorithm, OwnedUserId, RoomVersionId};
 
 // Needs to be public for trybuild tests
 #[doc(hidden)]
@@ -224,3 +224,37 @@ pub fn serialize_custom_event_error<T, S: Serializer>(_: &T, _: S) -> Result<S::
          `serde_json::value::to_raw_value` and `Raw::from_json`.",
     ))
 }
+
+/// Describes whether the event mentions other users or the room.
+#[derive(Clone, Debug, Default, Serialize, Deserialize)]
+#[non_exhaustive]
+pub struct Mentions {
+    /// The list of mentioned users.
+    ///
+    /// Defaults to an empty `Vec`.
+    #[serde(default, skip_serializing_if = "Vec::is_empty")]
+    pub user_ids: Vec<OwnedUserId>,
+
+    /// Whether the whole room is mentioned.
+    ///
+    /// Defaults to `false`.
+    #[serde(default, skip_serializing_if = "crate::serde::is_default")]
+    pub room: bool,
+}
+
+impl Mentions {
+    /// Create a `Mentions` with the default values.
+    pub fn new() -> Self {
+        Self::default()
+    }
+
+    /// Create a `Mentions` for the given user IDs.
+    pub fn with_user_ids(user_ids: Vec<OwnedUserId>) -> Self {
+        Self { user_ids, ..Default::default() }
+    }
+
+    /// Create a `Mentions` for a room mention.
+    pub fn with_room_mention() -> Self {
+        Self { room: true, ..Default::default() }
+    }
+}

crates/ruma-common/src/events/room/message.rs

@@ -9,9 +9,12 @@ use serde::{de::DeserializeOwned, Deserialize, Serialize};
 use serde_json::Value as JsonValue;
 
 use crate::{
-    events::relation::{CustomRelation, InReplyTo, RelationType, Replacement, Thread},
+    events::{
+        relation::{CustomRelation, InReplyTo, RelationType, Replacement, Thread},
+        Mentions,
+    },
     serde::{JsonObject, StringEnum},
-    EventId, OwnedEventId, PrivOwnedStr,
+    EventId, PrivOwnedStr,
 };
 
 mod audio;
@@ -64,13 +67,23 @@ pub struct RoomMessageEventContent {
     ///
     /// [related messages]: https://spec.matrix.org/latest/client-server-api/#forming-relationships-between-events
     #[serde(flatten, skip_serializing_if = "Option::is_none")]
-    pub relates_to: Option<Relation<MessageType>>,
+    pub relates_to: Option<Relation<RoomMessageEventContentWithoutRelation>>,
+
+    /// The [mentions] of this event.
+    ///
+    /// This should always be set to avoid triggering the legacy mention push rules. It is
+    /// recommended to use [`Self::set_mentions()`] to set this field, that will take care of
+    /// populating the fields correctly if this is a replacement.
+    ///
+    /// [mentions]: https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions
+    #[serde(rename = "m.mentions", skip_serializing_if = "Option::is_none")]
+    pub mentions: Option<Mentions>,
 }
 
 impl RoomMessageEventContent {
     /// Create a `RoomMessageEventContent` with the given `MessageType`.
     pub fn new(msgtype: MessageType) -> Self {
-        Self { msgtype, relates_to: None }
+        Self { msgtype, relates_to: None, mentions: None }
     }
 
     /// A constructor to create a plain text message.
@@ -247,6 +260,10 @@ impl RoomMessageEventContent {
     /// `original_message`.
     #[doc = include_str!(concat!(env!("CARGO_MANIFEST_DIR"), "/src/doc/rich_reply.md"))]
     ///
+    /// If the message that is replaced contains [`Mentions`], they are copied into
+    /// `m.new_content` to keep the same mentions, but not into `content` to avoid repeated
+    /// notifications.
+    ///
     /// # Panics
     ///
     /// Panics if `self` has a `formatted_body` with a format other than HTML.
@@ -255,13 +272,16 @@ impl RoomMessageEventContent {
     #[track_caller]
     pub fn make_replacement(
         mut self,
-        original_message_id: OwnedEventId,
+        original_message: &OriginalSyncRoomMessageEvent,
         replied_to_message: Option<&OriginalRoomMessageEvent>,
     ) -> Self {
         // Prepare relates_to with the untouched msgtype.
         let relates_to = Relation::Replacement(Replacement {
-            event_id: original_message_id,
-            new_content: self.msgtype.clone(),
+            event_id: original_message.event_id.clone(),
+            new_content: RoomMessageEventContentWithoutRelation {
+                msgtype: self.msgtype.clone(),
+                mentions: original_message.content.mentions.clone(),
+            },
         });
 
         let empty_formatted_body = || FormattedBody::html(String::new());
@@ -311,6 +331,43 @@ impl RoomMessageEventContent {
         self
     }
 
+    /// Set the [mentions] of this event.
+    ///
+    /// If this event is a replacement, it will update the mentions both in the `content` and the
+    /// `m.new_content` so only new mentions will trigger a notification. As such, this needs to be
+    /// called after [`Self::make_replacement()`].
+    ///
+    /// [mentions]: https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions
+    pub fn set_mentions(mut self, mentions: Mentions) -> Self {
+        if let Some(Relation::Replacement(replacement)) = &mut self.relates_to {
+            let old_mentions = &replacement.new_content.mentions;
+
+            let new_mentions = if let Some(old_mentions) = old_mentions {
+                let mut new_mentions = Mentions::new();
+
+                new_mentions.user_ids = mentions
+                    .user_ids
+                    .iter()
+                    .filter(|u| !old_mentions.user_ids.contains(*u))
+                    .cloned()
+                    .collect();
+
+                new_mentions.room = if old_mentions.room { false } else { mentions.room };
+
+                new_mentions
+            } else {
+                mentions.clone()
+            };
+
+            replacement.new_content.mentions = Some(mentions);
+            self.mentions = Some(new_mentions);
+        } else {
+            self.mentions = Some(mentions);
+        }
+
+        self
+    }
+
     /// Returns a reference to the `msgtype` string.
     ///
     /// If you want to access the message type-specific data rather than the message type itself,
@@ -352,6 +409,44 @@ impl RoomMessageEventContent {
     }
 }
 
+/// Form of [`RoomMessageEventContent`] without relation.
+///
+/// To construct this type, construct a [`RoomMessageEventContent`] and then use one of its ::from()
+/// / .into() methods.
+#[derive(Clone, Debug, Serialize)]
+#[cfg_attr(not(feature = "unstable-exhaustive-types"), non_exhaustive)]
+pub struct RoomMessageEventContentWithoutRelation {
+    /// A key which identifies the type of message being sent.
+    ///
+    /// This also holds the specific content of each message.
+    #[serde(flatten)]
+    pub msgtype: MessageType,
+
+    /// The [mentions] of this event.
+    ///
+    /// [mentions]: https://spec.matrix.org/latest/client-server-api/#user-and-room-mentions
+    #[serde(rename = "m.mentions", skip_serializing_if = "Option::is_none")]
+    pub mentions: Option<Mentions>,
+}
+
+impl RoomMessageEventContentWithoutRelation {
+    /// Transform `self` into a `RoomMessageEventContent` with the given relation.
+    pub fn with_relation(
+        self,
+        relates_to: Option<Relation<RoomMessageEventContentWithoutRelation>>,
+    ) -> RoomMessageEventContent {
+        let Self { msgtype, mentions } = self;
+        RoomMessageEventContent { msgtype, relates_to, mentions }
+    }
+}
+
+impl From<RoomMessageEventContent> for RoomMessageEventContentWithoutRelation {
+    fn from(value: RoomMessageEventContent) -> Self {
+        let RoomMessageEventContent { msgtype, mentions, .. } = value;
+        Self { msgtype, mentions }
+    }
+}
+
 /// Whether or not to forward a [`Relation::Thread`] when sending a reply.
 #[derive(Clone, Copy, Debug, PartialEq, Eq)]
 #[allow(clippy::exhaustive_enums)]

crates/ruma-common/src/events/room/message/content_serde.rs

@@ -3,22 +3,47 @@
 use serde::{de, Deserialize};
 use serde_json::value::RawValue as RawJsonValue;
 
-use super::{relation_serde::deserialize_relation, MessageType, RoomMessageEventContent};
-use crate::serde::from_raw_json_value;
+use super::{
+    relation_serde::deserialize_relation, MessageType, RoomMessageEventContent,
+    RoomMessageEventContentWithoutRelation,
+};
+use crate::{events::Mentions, serde::from_raw_json_value};
 
 impl<'de> Deserialize<'de> for RoomMessageEventContent {
     fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
     where
         D: de::Deserializer<'de>,
     {
         let json = Box::<RawJsonValue>::deserialize(deserializer)?;
+
         let mut deserializer = serde_json::Deserializer::from_str(json.get());
         let relates_to = deserialize_relation(&mut deserializer).map_err(de::Error::custom)?;
 
-        Ok(Self { msgtype: from_raw_json_value(&json)?, relates_to })
+        let MentionsDeHelper { mentions } = from_raw_json_value(&json)?;
+
+        Ok(Self { msgtype: from_raw_json_value(&json)?, relates_to, mentions })
+    }
+}
+
+impl<'de> Deserialize<'de> for RoomMessageEventContentWithoutRelation {
+    fn deserialize<D>(deserializer: D) -> Result<Self, D::Error>
+    where
+        D: de::Deserializer<'de>,
+    {
+        let json = Box::<RawJsonValue>::deserialize(deserializer)?;
+
+        let MentionsDeHelper { mentions } = from_raw_json_value(&json)?;
+
+        Ok(Self { msgtype: from_raw_json_value(&json)?, mentions })
     }
 }
 
+#[derive(Deserialize)]
+struct MentionsDeHelper {
+    #[serde(rename = "m.mentions")]
+    mentions: Option<Mentions>,
+}
+
 /// Helper struct to determine the msgtype from a `serde_json::value::RawValue`
 #[derive(Debug, Deserialize)]
 struct MessageTypeDeHelper {

crates/ruma-common/tests/events/relations.rs

@@ -107,7 +107,7 @@ fn replacement_deserialize() {
         })
     );
     assert_eq!(replacement.event_id, "$1598361704261elfgc");
-    assert_matches!(replacement.new_content, MessageType::Text(text));
+    assert_matches!(replacement.new_content.msgtype, MessageType::Text(text));
     assert_eq!(text.body, "Hello! My name is bar");
 }