feat(ui): Timeline consumes updates as VectorDiffs from the EventCache

crates/matrix-sdk-base/Cargo.toml

@@ -30,7 +30,10 @@ uniffi = ["dep:uniffi", "matrix-sdk-crypto?/uniffi", "matrix-sdk-common/uniffi"]
 # Private feature, see
 # https://github.com/matrix-org/matrix-rust-sdk/pull/3749#issuecomment-2312939823 for the gory
 # details.
-test-send-sync = ["matrix-sdk-crypto?/test-send-sync"]
+test-send-sync = [
+    "matrix-sdk-common/test-send-sync",
+    "matrix-sdk-crypto?/test-send-sync",
+]
 
 # "message-ids" feature doesn't do anything and is deprecated.
 message-ids = []

crates/matrix-sdk-common/Cargo.toml

@@ -18,6 +18,10 @@ targets = ["x86_64-unknown-linux-gnu", "wasm32-unknown-unknown"]
 [features]
 js = ["wasm-bindgen-futures"]
 uniffi = ["dep:uniffi"]
+# Private feature, see
+# https://github.com/matrix-org/matrix-rust-sdk/pull/3749#issuecomment-2312939823 for the gory
+# details.
+test-send-sync = []
 
 [dependencies]
 async-trait = { workspace = true }

crates/matrix-sdk-common/src/deserialized_responses.rs

@@ -308,6 +308,22 @@ pub struct EncryptionInfo {
 /// Previously, this differed from [`TimelineEvent`] by wrapping an
 /// [`AnySyncTimelineEvent`] instead of an [`AnyTimelineEvent`], but nowadays
 /// they are essentially identical, and one of them should probably be removed.
+//
+// 🚨 Note about this type, please read! 🚨
+//
+// `SyncTimelineEvent` is heavily used across the SDK crates. In some cases, we
+// are reaching a [`recursion_limit`] when the compiler is trying to figure out
+// if `SyncTimelineEvent` implements `Sync` when it's embedded in other types.
+//
+// We want to help the compiler so that one doesn't need to increase the
+// `recursion_limit`. We stop the recursive check by (un)safely implement `Sync`
+// and `Send` on `SyncTimelineEvent` directly.
+//
+// See
+// https://github.com/matrix-org/matrix-rust-sdk/pull/3749#issuecomment-2312939823
+// which has addressed this issue first
+//
+// [`recursion_limit`]: https://doc.rust-lang.org/reference/attributes/limits.html#the-recursion_limit-attribute
 #[derive(Clone, Debug, Serialize)]
 pub struct SyncTimelineEvent {
     /// The event itself, together with any information on decryption.
@@ -318,6 +334,23 @@ pub struct SyncTimelineEvent {
     pub push_actions: Vec<Action>,
 }
 
+// See https://github.com/matrix-org/matrix-rust-sdk/pull/3749#issuecomment-2312939823.
+#[cfg(not(feature = "test-send-sync"))]
+unsafe impl Send for SyncTimelineEvent {}
+
+// See https://github.com/matrix-org/matrix-rust-sdk/pull/3749#issuecomment-2312939823.
+#[cfg(not(feature = "test-send-sync"))]
+unsafe impl Sync for SyncTimelineEvent {}
+
+#[cfg(feature = "test-send-sync")]
+#[test]
+// See https://github.com/matrix-org/matrix-rust-sdk/pull/3749#issuecomment-2312939823.
+fn test_send_sync_for_sync_timeline_event() {
+    fn assert_send_sync<T: Send + Sync>() {}
+
+    assert_send_sync::<SyncTimelineEvent>();
+}
+
 impl SyncTimelineEvent {
     /// Create a new `SyncTimelineEvent` from the given raw event.
     ///

crates/matrix-sdk-ui/src/timeline/builder.rs

@@ -145,6 +145,14 @@ impl TimelineBuilder {
         self
     }
 
+    /// Use `VectorDiff`s as the new “input mechanism” for the `Timeline`.
+    ///
+    /// Read `TimelineSettings::vectordiffs_as_inputs` to learn more.
+    pub fn with_vectordiffs_as_inputs(mut self) -> Self {
+        self.settings.vectordiffs_as_inputs = true;
+        self
+    }
+
     /// Create a [`Timeline`] with the options set on this builder.
     #[tracing::instrument(
         skip(self),
@@ -154,11 +162,17 @@ impl TimelineBuilder {
         )
     )]
     pub async fn build(self) -> Result<Timeline, Error> {
-        let Self { room, settings, unable_to_decrypt_hook, focus, internal_id_prefix } = self;
+        let Self { room, mut settings, unable_to_decrypt_hook, focus, internal_id_prefix } = self;
 
         let client = room.client();
         let event_cache = client.event_cache();
 
+        // Enable `TimelineSettings::vectordiffs_as_inputs` if and only if the event
+        // cache storage is enabled.
+        settings.vectordiffs_as_inputs = event_cache.has_storage();
+
+        let settings_vectordiffs_as_inputs = settings.vectordiffs_as_inputs;
+
         // Subscribe the event cache to sync responses, in case we hadn't done it yet.
         event_cache.subscribe()?;
 
@@ -276,16 +290,32 @@ impl TimelineBuilder {
                             inner.clear().await;
                         }
 
+                        // TODO: remove once `UpdateTimelineEvents` is stabilized.
                         RoomEventCacheUpdate::AddTimelineEvents { events, origin } => {
-                            trace!("Received new timeline events.");
+                            if !settings_vectordiffs_as_inputs {
+                                trace!("Received new timeline events.");
+
+                                inner.add_events_at(
+                                    events.into_iter(),
+                                    TimelineNewItemPosition::End {                                    origin: match origin {
+                                            EventsOrigin::Sync => RemoteEventOrigin::Sync,
+                                        }
+                                    }
+                                ).await;
+                            }
+                        }
 
-                            inner.add_events_at(
-                                events.into_iter(),
-                                TimelineNewItemPosition::End {                                    origin: match origin {
+                        RoomEventCacheUpdate::UpdateTimelineEvents { diffs, origin } => {
+                            if settings_vectordiffs_as_inputs {
+                                trace!("Received new timeline events diffs");
+
+                                inner.handle_remote_events_with_diffs(
+                                    diffs,
+                                    match origin {
                                         EventsOrigin::Sync => RemoteEventOrigin::Sync,
                                     }
-                                }
-                            ).await;
+                                ).await;
+                            }
                         }
 
                         RoomEventCacheUpdate::AddEphemeralEvents { events } => {

crates/matrix-sdk-ui/src/timeline/controller/mod.rs

@@ -124,20 +124,29 @@ pub(super) struct TimelineController<P: RoomDataProvider = Room> {
     pub(crate) room_data_provider: P,
 
     /// Settings applied to this timeline.
-    settings: TimelineSettings,
+    pub(super) settings: TimelineSettings,
 }
 
 #[derive(Clone)]
 pub(super) struct TimelineSettings {
     /// Should the read receipts and read markers be handled?
     pub(super) track_read_receipts: bool,
+
     /// Event filter that controls what's rendered as a timeline item (and thus
     /// what can carry read receipts).
     pub(super) event_filter: Arc<TimelineEventFilterFn>,
+
     /// Are unparsable events added as timeline items of their own kind?
     pub(super) add_failed_to_parse: bool,
+
     /// Should the timeline items be grouped by day or month?
     pub(super) date_divider_mode: DateDividerMode,
+
+    /// Whether `VectorDiff` is the “input mechanism” to use.
+    ///
+    /// This mechanism will replace the existing one, but this runtime feature
+    /// flag is necessary for the transition and the testing phase.
+    pub(super) vectordiffs_as_inputs: bool,
 }
 
 #[cfg(not(tarpaulin_include))]
@@ -146,6 +155,7 @@ impl fmt::Debug for TimelineSettings {
         f.debug_struct("TimelineSettings")
             .field("track_read_receipts", &self.track_read_receipts)
             .field("add_failed_to_parse", &self.add_failed_to_parse)
+            .field("vectordiffs_as_inputs", &self.vectordiffs_as_inputs)
             .finish_non_exhaustive()
     }
 }
@@ -157,6 +167,7 @@ impl Default for TimelineSettings {
             event_filter: Arc::new(default_event_filter),
             add_failed_to_parse: true,
             date_divider_mode: DateDividerMode::Daily,
+            vectordiffs_as_inputs: false,
         }
     }
 }
@@ -665,6 +676,27 @@ impl<P: RoomDataProvider> TimelineController<P> {
         state.add_remote_events_at(events, position, &self.room_data_provider, &self.settings).await
     }
 
+    /// Handle updates on events as [`VectorDiff`]s.
+    pub(super) async fn handle_remote_events_with_diffs(
+        &self,
+        diffs: Vec<VectorDiff<SyncTimelineEvent>>,
+        origin: RemoteEventOrigin,
+    ) {
+        if diffs.is_empty() {
+            return;
+        }
+
+        let mut state = self.state.write().await;
+        state
+            .handle_remote_events_with_diffs(
+                diffs,
+                origin,
+                &self.room_data_provider,
+                &self.settings,
+            )
+            .await
+    }
+
     pub(super) async fn clear(&self) {
         self.state.write().await.clear();
     }
@@ -757,6 +789,7 @@ impl<P: RoomDataProvider> TimelineController<P> {
                 txn_id,
                 send_handle,
                 content,
+                &self.settings,
             )
             .await;
     }

crates/matrix-sdk-ui/src/timeline/controller/observable_items.rs

@@ -15,7 +15,7 @@
 use std::{
     cmp::Ordering,
     collections::{vec_deque::Iter, VecDeque},
-    ops::Deref,
+    ops::{Deref, RangeBounds},
     sync::Arc,
 };
 
@@ -220,6 +220,13 @@ impl<'observable_items> ObservableItemsTransaction<'observable_items> {
         self.all_remote_events.push_back(event_meta);
     }
 
+    /// Insert a new remote event at a specific index.
+    ///
+    /// Not to be confused with inserting a timeline item!
+    pub fn insert_remote_event(&mut self, event_index: usize, event_meta: EventMeta) {
+        self.all_remote_events.insert(event_index, event_meta);
+    }
+
     /// Get a remote event by using an event ID.
     pub fn get_remote_event_by_event_id_mut(
         &mut self,
@@ -1155,11 +1162,25 @@ mod observable_items_tests {
 pub struct AllRemoteEvents(VecDeque<EventMeta>);
 
 impl AllRemoteEvents {
+    /// Return a reference to a remote event.
+    pub fn get(&self, event_index: usize) -> Option<&EventMeta> {
+        self.0.get(event_index)
+    }
+
     /// Return a front-to-back iterator over all remote events.
     pub fn iter(&self) -> Iter<'_, EventMeta> {
         self.0.iter()
     }
 
+    /// Return a front-to-back iterator covering ranges of all remote events
+    /// described by `range`.
+    pub fn range<R>(&self, range: R) -> Iter<'_, EventMeta>
+    where
+        R: RangeBounds<usize>,
+    {
+        self.0.range(range)
+    }
+
     /// Remove all remote events.
     fn clear(&mut self) {
         self.0.clear();
@@ -1189,6 +1210,18 @@ impl AllRemoteEvents {
         self.0.push_back(event_meta)
     }
 
+    /// Insert a new remote event at a specific index.
+    fn insert(&mut self, event_index: usize, event_meta: EventMeta) {
+        // If there is an associated `timeline_item_index`, shift all the
+        // `timeline_item_index` that come after this one.
+        if let Some(new_timeline_item_index) = event_meta.timeline_item_index {
+            self.increment_all_timeline_item_index_after(new_timeline_item_index);
+        }
+
+        // Insert the event.
+        self.0.insert(event_index, event_meta)
+    }
+
     /// Remove one remote event at a specific index, and return it if it exists.
     fn remove(&mut self, event_index: usize) -> Option<EventMeta> {
         // Remove the event.
@@ -1261,8 +1294,7 @@ impl AllRemoteEvents {
     }
 
     /// Notify that a timeline item has been removed at
-    /// `new_timeline_item_index`. If `event_index` is `Some(_)`, it means the
-    /// remote event at `event_index` must be unmapped.
+    /// `new_timeline_item_index`.
     fn timeline_item_has_been_removed_at(&mut self, timeline_item_index_to_remove: usize) {
         for event_meta in self.0.iter_mut() {
             let mut remove_timeline_item_index = false;
@@ -1318,6 +1350,34 @@ mod all_remote_events_tests {
         }
     }
 
+    #[test]
+    fn test_range() {
+        let mut events = AllRemoteEvents::default();
+
+        // Push some events.
+        events.push_back(event_meta("$ev0", None));
+        events.push_back(event_meta("$ev1", None));
+        events.push_back(event_meta("$ev2", None));
+
+        assert_eq!(events.iter().count(), 3);
+
+        // Test a few combinations.
+        assert_eq!(events.range(..).count(), 3);
+        assert_eq!(events.range(1..).count(), 2);
+        assert_eq!(events.range(0..=1).count(), 2);
+
+        // Iterate on some of them.
+        let mut some_events = events.range(1..);
+
+        assert_matches!(some_events.next(), Some(EventMeta { event_id, .. }) => {
+            assert_eq!(event_id.as_str(), "$ev1");
+        });
+        assert_matches!(some_events.next(), Some(EventMeta { event_id, .. }) => {
+            assert_eq!(event_id.as_str(), "$ev2");
+        });
+        assert!(some_events.next().is_none());
+    }
+
     #[test]
     fn test_clear() {
         let mut events = AllRemoteEvents::default();
@@ -1399,6 +1459,37 @@ mod all_remote_events_tests {
         );
     }
 
+    #[test]
+    fn test_insert() {
+        let mut events = AllRemoteEvents::default();
+
+        // Insert on an empty set, nothing particular.
+        events.insert(0, event_meta("$ev0", Some(0)));
+
+        // Insert at the end with no `timeline_item_index`.
+        events.insert(1, event_meta("$ev1", None));
+
+        // Insert at the end with a `timeline_item_index`.
+        events.insert(2, event_meta("$ev2", Some(1)));
+
+        // Insert at the start, with a `timeline_item_index`.
+        events.insert(0, event_meta("$ev3", Some(0)));
+
+        assert_events!(
+            events,
+            [
+                // `timeline_item_index` is untouched
+                ("$ev3", Some(0)),
+                // `timeline_item_index` has been shifted once
+                ("$ev0", Some(1)),
+                // no `timeline_item_index`
+                ("$ev1", None),
+                // `timeline_item_index` has been shifted once
+                ("$ev2", Some(2)),
+            ]
+        );
+    }
+
     #[test]
     fn test_remove() {
         let mut events = AllRemoteEvents::default();