feat(sdk): add a room method to retrieve all related events

Author: bnjbvr

crates/matrix-sdk/CHANGELOG.md

@@ -9,6 +9,10 @@ All notable changes to this project will be documented in this file.
 ### Features
 
 - `Room::list_threads()` is a new method to list all the threads in a room.
+  ([#4972](https://github.com/matrix-org/matrix-rust-sdk/pull/4972))
+- `Room::relations()` is a new method to list all the events related to another event
+  ("relations"), with additional filters for relation type or relation type + event type.
+  ([#4972](https://github.com/matrix-org/matrix-rust-sdk/pull/4972))
 
 ### Bug fixes
 

crates/matrix-sdk/src/room/messages.rs

@@ -14,22 +14,27 @@
 
 use std::fmt;
 
+use futures_util::future::join_all;
 use matrix_sdk_common::{debug::DebugStructExt as _, deserialized_responses::TimelineEvent};
 use ruma::{
     api::{
         client::{
             filter::RoomEventFilter,
             message::get_message_events,
+            relations,
             threads::get_threads::{self, v1::IncludeThreads},
         },
         Direction,
     },
     assign,
-    events::AnyStateEvent,
+    events::{relation::RelationType, AnyStateEvent, TimelineEventType},
     serde::Raw,
-    uint, RoomId, UInt,
+    uint, OwnedEventId, RoomId, UInt,
 };
 
+use super::Room;
+use crate::Result;
+
 /// Options for [`messages`][super::Room::messages].
 ///
 /// See that method and
@@ -224,3 +229,149 @@ pub struct ThreadRoots {
     /// [`super::Room::list_threads`].
     pub prev_batch_token: Option<String>,
 }
+
+/// What kind of relations should be included in a [`super::Room::relations`]
+/// query.
+#[derive(Clone, Debug, Default)]
+pub enum IncludeRelations {
+    /// Include all relations independently of their relation type.
+    #[default]
+    AllRelations,
+    /// Include all relations of a given relation type.
+    RelationsOfType(RelationType),
+    /// Include all relations of a given relation type and event type.
+    RelationsOfTypeAndEventType(RelationType, TimelineEventType),
+}
+
+/// Options for [`messages`][super::Room::relations].
+#[derive(Clone, Debug, Default)]
+pub struct RelationsOptions {
+    /// The token to start returning events from.
+    ///
+    /// This token can be obtained from a [`Relations::prev_batch_token`]
+    /// returned by a previous call to [`super::Room::relations()`].
+    ///
+    /// If `from` isn't provided the homeserver shall return a list of thread
+    /// roots from end of the timeline history.
+    pub from: Option<String>,
+
+    /// The direction to return events in.
+    ///
+    /// Defaults to backwards.
+    pub dir: Direction,
+
+    /// The maximum number of events to return.
+    ///
+    /// Default: 10.
+    pub limit: Option<UInt>,
+
+    /// Optional restrictions on the relations to include based on their type or
+    /// event type.
+    ///
+    /// Defaults to all relations.
+    pub include_relations: IncludeRelations,
+
+    /// Whether to include events which relate indirectly to the given event.
+    ///
+    /// These are events related to the given event via two or more direct
+    /// relationships.
+    pub recurse: bool,
+}
+
+impl RelationsOptions {
+    /// Converts this options object into a request, according to the filled
+    /// parameters, and returns a canonicalized response.
+    pub(super) async fn send(self, room: &Room, event: OwnedEventId) -> Result<Relations> {
+        macro_rules! fill_params {
+            ($request:expr) => {
+                assign! { $request, {
+                    from: self.from,
+                    dir: self.dir,
+                    limit: self.limit,
+                    recurse: self.recurse,
+                }}
+            };
+        }
+
+        // This match to common out the different `Response` types into a single one. It
+        // would've been nice that Ruma used the same response type for all the
+        // responses, but it is likely doing so to guard against possible future
+        // changes.
+        let (chunk, prev_batch, next_batch, recursion_depth) = match self.include_relations {
+            IncludeRelations::AllRelations => {
+                let request = fill_params!(relations::get_relating_events::v1::Request::new(
+                    room.room_id().to_owned(),
+                    event,
+                ));
+                let response = room.client.send(request).await?;
+                (response.chunk, response.prev_batch, response.next_batch, response.recursion_depth)
+            }
+
+            IncludeRelations::RelationsOfType(relation_type) => {
+                let request =
+                    fill_params!(relations::get_relating_events_with_rel_type::v1::Request::new(
+                        room.room_id().to_owned(),
+                        event,
+                        relation_type,
+                    ));
+                let response = room.client.send(request).await?;
+                (response.chunk, response.prev_batch, response.next_batch, response.recursion_depth)
+            }
+
+            IncludeRelations::RelationsOfTypeAndEventType(relation_type, timeline_event_type) => {
+                let request = fill_params!(
+                    relations::get_relating_events_with_rel_type_and_event_type::v1::Request::new(
+                        room.room_id().to_owned(),
+                        event,
+                        relation_type,
+                        timeline_event_type,
+                    )
+                );
+                let response = room.client.send(request).await?;
+                (response.chunk, response.prev_batch, response.next_batch, response.recursion_depth)
+            }
+        };
+
+        let push_ctx = room.push_context().await?;
+        let chunk = join_all(chunk.into_iter().map(|ev| {
+            // Cast safety: an `AnyMessageLikeEvent` is a subset of an `AnyTimelineEvent`.
+            room.try_decrypt_event(ev.cast(), push_ctx.as_ref())
+        }))
+        .await;
+
+        Ok(Relations {
+            chunk,
+            prev_batch_token: prev_batch,
+            next_batch_token: next_batch,
+            recursion_depth,
+        })
+    }
+}
+
+/// The result of a [`super::Room::relations`] query.
+///
+/// This is a wrapper around the Ruma equivalents, with events decrypted if
+/// needs be.
+#[derive(Debug)]
+pub struct Relations {
+    /// The events related to the specified event from the request.
+    ///
+    /// Note: the events will be sorted according to the `dir` parameter:
+    /// - if the direction was backwards, then the events will be ordered in
+    ///   reverse topological order.
+    /// - if the direction was forwards, then the events will be ordered in
+    ///   topological order.
+    pub chunk: Vec<TimelineEvent>,
+
+    /// An opaque string representing a pagination token to retrieve the
+    /// previous batch of events.
+    pub prev_batch_token: Option<String>,
+
+    /// An opaque string representing a pagination token to retrieve the next
+    /// batch of events.
+    pub next_batch_token: Option<String>,
+
+    /// If [`RelationsOptions::recurse`] was set, the depth to which the server
+    /// recursed.
+    pub recursion_depth: Option<UInt>,
+}

crates/matrix-sdk/src/room/mod.rs

@@ -54,7 +54,6 @@ use matrix_sdk_common::{
     executor::{spawn, JoinHandle},
     timeout::timeout,
 };
-use messages::{ListThreadsOptions, ThreadRoots};
 use mime::Mime;
 use reply::Reply;
 #[cfg(feature = "e2e-encryption")]
@@ -132,7 +131,10 @@ use tracing::{debug, info, instrument, warn};
 use self::futures::{SendAttachment, SendMessageLikeEvent, SendRawMessageLikeEvent};
 pub use self::{
     member::{RoomMember, RoomMemberRole},
-    messages::{EventWithContextResponse, Messages, MessagesOptions},
+    messages::{
+        EventWithContextResponse, IncludeRelations, ListThreadsOptions, Messages, MessagesOptions,
+        Relations, RelationsOptions, ThreadRoots,
+    },
 };
 #[cfg(doc)]
 use crate::event_cache::EventCache;
@@ -3568,6 +3570,27 @@ impl Room {
 
         Ok(ThreadRoots { chunk, prev_batch_token: response.next_batch })
     }
+
+    /// Retrieve a list of relations for the given event, according to the given
+    /// options.
+    ///
+    /// Since this client-server API is paginated, the return type may include a
+    /// token used to resuming back-pagination into the list of results, in
+    /// [`Relations::prev_batch_token`]. This token can be fed back into
+    /// [`RelationsOptions::from`] to continue the pagination from the previous
+    /// position.
+    ///
+    /// **Note**: if [`RelationsOptions::from`] is set for a subsequent request,
+    /// then it must be used with the same
+    /// [`RelationsOptions::include_relations`] value as the request that
+    /// returns the `from` token, otherwise the server behavior is undefined.
+    pub async fn relations(
+        &self,
+        event_id: OwnedEventId,
+        opts: RelationsOptions,
+    ) -> Result<Relations> {
+        opts.send(self, event_id).await
+    }
 }
 
 #[cfg(all(feature = "e2e-encryption", not(target_arch = "wasm32")))]
@@ -3887,7 +3910,11 @@ mod tests {
         async_test, event_factory::EventFactory, test_json, JoinedRoomBuilder, StateTestEvent,
         SyncResponseBuilder,
     };
-    use ruma::{event_id, events::room::member::MembershipState, int, room_id, user_id};
+    use ruma::{
+        event_id,
+        events::{relation::RelationType, room::member::MembershipState},
+        int, owned_event_id, room_id, user_id,
+    };
     use wiremock::{
         matchers::{header, method, path_regex},
         Mock, MockServer, ResponseTemplate,
@@ -3896,8 +3923,12 @@ mod tests {
     use super::ReportedContentScore;
     use crate::{
         config::RequestConfig,
-        room::messages::ListThreadsOptions,
-        test_utils::{client::mock_matrix_session, logged_in_client, mocks::MatrixMockServer},
+        room::messages::{IncludeRelations, ListThreadsOptions, RelationsOptions},
+        test_utils::{
+            client::mock_matrix_session,
+            logged_in_client,
+            mocks::{MatrixMockServer, RoomRelationsResponseTemplate},
+        },
         Client,
     };
 
@@ -4284,4 +4315,128 @@ mod tests {
         assert_eq!(result.chunk[0].event_id().unwrap(), eid2);
         assert!(result.prev_batch_token.is_none());
     }
+
+    #[async_test]
+    async fn test_relations() {
+        let server = MatrixMockServer::new().await;
+        let client = server.client_builder().build().await;
+
+        let room_id = room_id!("!a:b.c");
+        let sender_id = user_id!("@alice:b.c");
+        let f = EventFactory::new().room(room_id).sender(sender_id);
+
+        let target_event_id = owned_event_id!("$target");
+        let eid1 = event_id!("$1");
+        let eid2 = event_id!("$2");
+        let batch1 = vec![f.text_msg("Related event 1").event_id(eid1).into_raw_sync().cast()];
+        let batch2 = vec![f.text_msg("Related event 2").event_id(eid2).into_raw_sync().cast()];
+
+        server
+            .mock_room_relations()
+            .match_target_event(target_event_id.clone())
+            .ok(RoomRelationsResponseTemplate::default().events(batch1).next_batch("next_batch"))
+            .mock_once()
+            .mount()
+            .await;
+
+        server
+            .mock_room_relations()
+            .match_target_event(target_event_id.clone())
+            .match_from("next_batch")
+            .ok(RoomRelationsResponseTemplate::default().events(batch2))
+            .mock_once()
+            .mount()
+            .await;
+
+        let room = server.sync_joined_room(&client, room_id).await;
+
+        // Main endpoint: no relation type filtered out.
+        let mut opts = RelationsOptions {
+            include_relations: IncludeRelations::AllRelations,
+            ..Default::default()
+        };
+        let result = room
+            .relations(target_event_id.clone(), opts.clone())
+            .await
+            .expect("Failed to list relations the first time");
+        assert_eq!(result.chunk.len(), 1);
+        assert_eq!(result.chunk[0].event_id().unwrap(), eid1);
+        assert!(result.prev_batch_token.is_none());
+        assert!(result.next_batch_token.is_some());
+        assert!(result.recursion_depth.is_none());
+
+        opts.from = result.next_batch_token;
+        let result = room
+            .relations(target_event_id, opts)
+            .await
+            .expect("Failed to list relations the second time");
+        assert_eq!(result.chunk.len(), 1);
+        assert_eq!(result.chunk[0].event_id().unwrap(), eid2);
+        assert!(result.prev_batch_token.is_none());
+        assert!(result.next_batch_token.is_none());
+        assert!(result.recursion_depth.is_none());
+    }
+
+    #[async_test]
+    async fn test_relations_with_reltype() {
+        let server = MatrixMockServer::new().await;
+        let client = server.client_builder().build().await;
+
+        let room_id = room_id!("!a:b.c");
+        let sender_id = user_id!("@alice:b.c");
+        let f = EventFactory::new().room(room_id).sender(sender_id);
+
+        let target_event_id = owned_event_id!("$target");
+        let eid1 = event_id!("$1");
+        let eid2 = event_id!("$2");
+        let batch1 = vec![f.text_msg("In-thread event 1").event_id(eid1).into_raw_sync().cast()];
+        let batch2 = vec![f.text_msg("In-thread event 2").event_id(eid2).into_raw_sync().cast()];
+
+        server
+            .mock_room_relations()
+            .match_target_event(target_event_id.clone())
+            .match_subrequest(IncludeRelations::RelationsOfType(RelationType::Thread))
+            .ok(RoomRelationsResponseTemplate::default().events(batch1).next_batch("next_batch"))
+            .mock_once()
+            .mount()
+            .await;
+
+        server
+            .mock_room_relations()
+            .match_target_event(target_event_id.clone())
+            .match_from("next_batch")
+            .match_subrequest(IncludeRelations::RelationsOfType(RelationType::Thread))
+            .ok(RoomRelationsResponseTemplate::default().events(batch2))
+            .mock_once()
+            .mount()
+            .await;
+
+        let room = server.sync_joined_room(&client, room_id).await;
+
+        // Reltype-filtered endpoint, for threads \o/
+        let mut opts = RelationsOptions {
+            include_relations: IncludeRelations::RelationsOfType(RelationType::Thread),
+            ..Default::default()
+        };
+        let result = room
+            .relations(target_event_id.clone(), opts.clone())
+            .await
+            .expect("Failed to list relations the first time");
+        assert_eq!(result.chunk.len(), 1);
+        assert_eq!(result.chunk[0].event_id().unwrap(), eid1);
+        assert!(result.prev_batch_token.is_none());
+        assert!(result.next_batch_token.is_some());
+        assert!(result.recursion_depth.is_none());
+
+        opts.from = result.next_batch_token;
+        let result = room
+            .relations(target_event_id, opts)
+            .await
+            .expect("Failed to list relations the second time");
+        assert_eq!(result.chunk.len(), 1);
+        assert_eq!(result.chunk[0].event_id().unwrap(), eid2);
+        assert!(result.prev_batch_token.is_none());
+        assert!(result.next_batch_token.is_none());
+        assert!(result.recursion_depth.is_none());
+    }
 }