feat(sdk): Introduce the LatestEvents API.

This patch is the first part of the new `LatestEvents` API. It contains
the “framework”, i.e. the structure, tasks, logic to make it work, but
no latest events are computed for the moment.

The Latest Events API provides a lazy, reactive and efficient way to
compute the latest event for a room or a thread.

The latest event represents the last displayable and relevant event
a room or a thread has been received. It is usually displayed in a
_summary_, e.g. below the room title in a room list.

The entry point is `LatestEvents`. It is preferable to get a reference
to it from `Client::latest_events`, which already plugs everything to
build it. `LatestEvents` is using the `EventCache` and the `SendQueue`
to respectively get known remote events (i.e. synced from the server),
or local events (i.e. ones being sent).

\## Laziness

`LatestEvents` is lazy, it means that, despites `LatestEvents`
is listening to all `EventCache` or `SendQueue` updates, it will
only do something if one is expected to get the latest event for a
particular room or a particular thread. Concretely, it means that until
`LatestEvents::listen_to_room` is called for a particular room, no
latest event will ever be computed for that room (and similarly with
`LatestEvents::listen_to_thread`).

If one is no longer interested to get the latest event for a
particular room or thread, the `LatestEvents::forget_room` and
`LatestEvents::forget_thread` methods must be used.

\## Reactive

`LatestEvents` is designed to be reactive. Use
`LatestEvents::listen_and_subscribe_to_room` (same for thread) to get
a `Subscriber`.

Author: Hywan

crates/matrix-sdk/src/client/builder/mod.rs

@@ -574,6 +574,8 @@ impl ClientBuilder {
         };
 
         let event_cache = OnceCell::new();
+        let latest_events = OnceCell::new();
+
         let inner = ClientInner::new(
             auth_ctx,
             server,
@@ -585,6 +587,7 @@ impl ClientBuilder {
             self.respect_login_well_known,
             event_cache,
             send_queue,
+            latest_events,
             #[cfg(feature = "e2e-encryption")]
             self.encryption_settings,
             #[cfg(feature = "e2e-encryption")]

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

@@ -91,11 +91,12 @@ use crate::{
         EventHandlerStore, ObservableEventHandler, SyncEvent,
     },
     http_client::HttpClient,
+    latest_events::LatestEvents,
     media::MediaError,
     notification_settings::NotificationSettings,
     room::RoomMember,
     room_preview::RoomPreview,
-    send_queue::SendQueueData,
+    send_queue::{SendQueue, SendQueueData},
     sliding_sync::Version as SlidingSyncVersion,
     sync::{RoomUpdate, SyncResponse},
     Account, AuthApi, AuthSession, Error, HttpError, Media, Pusher, RefreshTokenError, Result,
@@ -344,6 +345,11 @@ pub(crate) struct ClientInner {
     /// The `max_upload_size` value of the homeserver, it contains the max
     /// request size you can send.
     pub(crate) server_max_upload_size: Mutex<OnceCell<UInt>>,
+
+    /// The entry point to get the [`LatestEvent`] of rooms and threads.
+    ///
+    /// [`LatestEvent`]: crate::latest_event::LatestEvent
+    latest_events: OnceCell<LatestEvents>,
 }
 
 impl ClientInner {
@@ -364,6 +370,7 @@ impl ClientInner {
         respect_login_well_known: bool,
         event_cache: OnceCell<EventCache>,
         send_queue: Arc<SendQueueData>,
+        latest_events: OnceCell<LatestEvents>,
         #[cfg(feature = "e2e-encryption")] encryption_settings: EncryptionSettings,
         #[cfg(feature = "e2e-encryption")] enable_share_history_on_invite: bool,
         cross_process_store_locks_holder_name: String,
@@ -394,6 +401,7 @@ impl ClientInner {
             sync_beat: event_listener::Event::new(),
             event_cache,
             send_queue_data: send_queue,
+            latest_events,
             #[cfg(feature = "e2e-encryption")]
             e2ee: EncryptionData::new(encryption_settings),
             #[cfg(feature = "e2e-encryption")]
@@ -2638,6 +2646,7 @@ impl Client {
                 self.inner.respect_login_well_known,
                 self.inner.event_cache.clone(),
                 self.inner.send_queue_data.clone(),
+                self.inner.latest_events.clone(),
                 #[cfg(feature = "e2e-encryption")]
                 self.inner.e2ee.encryption_settings,
                 #[cfg(feature = "e2e-encryption")]
@@ -2656,6 +2665,16 @@ impl Client {
         self.inner.event_cache.get().unwrap()
     }
 
+    /// The [`LatestEvents`] instance for this [`Client`].
+    pub async fn latest_events(&self) -> &LatestEvents {
+        self.inner
+            .latest_events
+            .get_or_init(|| async {
+                LatestEvents::new(self.event_cache().clone(), SendQueue::new(self.clone()))
+            })
+            .await
+    }
+
     /// Waits until an at least partially synced room is received, and returns
     /// it.
     ///

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

@@ -637,6 +637,15 @@ pub enum RoomEventCacheGenericUpdate {
     },
 }
 
+impl RoomEventCacheGenericUpdate {
+    /// Get the room ID that has triggered this generic update.
+    pub fn room_id(&self) -> &RoomId {
+        match self {
+            Self::TimelineUpdated { room_id } => room_id,
+        }
+    }
+}
+
 /// An update related to events happened in a room.
 #[derive(Debug, Clone)]
 pub enum RoomEventCacheUpdate {

crates/matrix-sdk/src/latest_events/latest_event.rs

@@ -0,0 +1,51 @@
+// Copyright 2025 The Matrix.org Foundation C.I.C.
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+use eyeball::{AsyncLock, SharedObservable, Subscriber};
+use ruma::{EventId, OwnedEventId, OwnedRoomId, RoomId};
+
+/// The latest event of a room or a thread.
+///
+/// Use [`LatestEvent::subscribe`] to get a stream of updates.
+#[derive(Debug)]
+pub(super) struct LatestEvent {
+    /// The room owning this latest event.
+    _room_id: OwnedRoomId,
+    /// The thread (if any) owning this latest event.
+    _thread_id: Option<OwnedEventId>,
+    /// The latest event value.
+    value: SharedObservable<LatestEventValue, AsyncLock>,
+}
+
+impl LatestEvent {
+    pub(super) fn new(room_id: &RoomId, thread_id: Option<&EventId>) -> Option<Self> {
+        Some(Self {
+            _room_id: room_id.to_owned(),
+            _thread_id: thread_id.map(ToOwned::to_owned),
+            value: SharedObservable::new_async(LatestEventValue::None),
+        })
+    }
+
+    /// Return a [`Subscriber`] to new values.
+    pub async fn subscribe(&self) -> Subscriber<LatestEventValue, AsyncLock> {
+        self.value.subscribe().await
+    }
+}
+
+/// A latest event value!
+#[derive(Debug, Clone)]
+pub enum LatestEventValue {
+    /// No value has been computed yet, or no candidate value was found.
+    None,
+}