matrix_sdk_base/room/
mod.rs

1// Copyright 2025 The Matrix.org Foundation C.I.C.
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7//     http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15#![allow(clippy::assign_op_pattern)] // Triggered by bitflags! usage
16
17mod call;
18mod create;
19mod display_name;
20mod encryption;
21mod knock;
22mod latest_event;
23mod members;
24mod room_info;
25mod state;
26mod tags;
27mod tombstone;
28
29use std::{
30    collections::{BTreeMap, BTreeSet, HashSet},
31    sync::Arc,
32};
33
34pub use create::*;
35pub use display_name::{RoomDisplayName, RoomHero};
36pub(crate) use display_name::{RoomSummary, UpdatedRoomDisplayName};
37pub use encryption::EncryptionState;
38use eyeball::{AsyncLock, SharedObservable};
39use futures_util::{Stream, StreamExt};
40pub use members::{RoomMember, RoomMembersUpdate, RoomMemberships};
41pub(crate) use room_info::SyncInfo;
42pub use room_info::{
43    BaseRoomInfo, RoomInfo, RoomInfoNotableUpdate, RoomInfoNotableUpdateReasons, RoomRecencyStamp,
44    apply_redaction,
45};
46use ruma::{
47    EventId, OwnedEventId, OwnedMxcUri, OwnedRoomAliasId, OwnedRoomId, OwnedUserId, RoomId,
48    RoomVersionId, UserId,
49    events::{
50        direct::OwnedDirectUserIdentifier,
51        receipt::{Receipt, ReceiptThread, ReceiptType},
52        room::{
53            avatar,
54            guest_access::GuestAccess,
55            history_visibility::HistoryVisibility,
56            join_rules::JoinRule,
57            power_levels::{RoomPowerLevels, RoomPowerLevelsEventContent, RoomPowerLevelsSource},
58        },
59    },
60    room::RoomType,
61};
62use serde::{Deserialize, Serialize};
63pub use state::{RoomState, RoomStateFilter};
64pub(crate) use tags::RoomNotableTags;
65use tokio::sync::broadcast;
66pub use tombstone::{PredecessorRoom, SuccessorRoom};
67use tracing::{info, instrument, warn};
68
69use crate::{
70    Error,
71    deserialized_responses::MemberEvent,
72    notification_settings::RoomNotificationMode,
73    read_receipts::RoomReadReceipts,
74    store::{DynStateStore, Result as StoreResult, StateStoreExt},
75    sync::UnreadNotificationsCount,
76};
77
78/// The underlying room data structure collecting state for joined, left and
79/// invited rooms.
80#[derive(Debug, Clone)]
81pub struct Room {
82    /// The room ID.
83    pub(super) room_id: OwnedRoomId,
84
85    /// Our own user ID.
86    pub(super) own_user_id: OwnedUserId,
87
88    pub(super) info: SharedObservable<RoomInfo>,
89
90    /// A clone of the [`BaseStateStore::room_info_notable_update_sender`].
91    ///
92    /// [`BaseStateStore::room_info_notable_update_sender`]: crate::store::BaseStateStore::room_info_notable_update_sender
93    pub(super) room_info_notable_update_sender: broadcast::Sender<RoomInfoNotableUpdate>,
94
95    /// A clone of the state store.
96    pub(super) store: Arc<DynStateStore>,
97
98    /// A map for ids of room membership events in the knocking state linked to
99    /// the user id of the user affected by the member event, that the current
100    /// user has marked as seen so they can be ignored.
101    pub seen_knock_request_ids_map:
102        SharedObservable<Option<BTreeMap<OwnedEventId, OwnedUserId>>, AsyncLock>,
103
104    /// A sender that will notify receivers when room member updates happen.
105    pub room_member_updates_sender: broadcast::Sender<RoomMembersUpdate>,
106}
107
108impl Room {
109    pub(crate) fn new(
110        own_user_id: &UserId,
111        store: Arc<DynStateStore>,
112        room_id: &RoomId,
113        room_state: RoomState,
114        room_info_notable_update_sender: broadcast::Sender<RoomInfoNotableUpdate>,
115    ) -> Self {
116        let room_info = RoomInfo::new(room_id, room_state);
117        Self::restore(own_user_id, store, room_info, room_info_notable_update_sender)
118    }
119
120    pub(crate) fn restore(
121        own_user_id: &UserId,
122        store: Arc<DynStateStore>,
123        room_info: RoomInfo,
124        room_info_notable_update_sender: broadcast::Sender<RoomInfoNotableUpdate>,
125    ) -> Self {
126        let (room_member_updates_sender, _) = broadcast::channel(10);
127        Self {
128            own_user_id: own_user_id.into(),
129            room_id: room_info.room_id.clone(),
130            store,
131            info: SharedObservable::new(room_info),
132            room_info_notable_update_sender,
133            seen_knock_request_ids_map: SharedObservable::new_async(None),
134            room_member_updates_sender,
135        }
136    }
137
138    /// Get the unique room id of the room.
139    pub fn room_id(&self) -> &RoomId {
140        &self.room_id
141    }
142
143    /// Get a copy of the room creators.
144    pub fn creators(&self) -> Option<Vec<OwnedUserId>> {
145        self.info.read().creators()
146    }
147
148    /// Get our own user id.
149    pub fn own_user_id(&self) -> &UserId {
150        &self.own_user_id
151    }
152
153    /// Whether this room's [`RoomType`] is `m.space`.
154    pub fn is_space(&self) -> bool {
155        self.info.read().room_type().is_some_and(|t| *t == RoomType::Space)
156    }
157
158    /// Returns the room's type as defined in its creation event
159    /// (`m.room.create`).
160    pub fn room_type(&self) -> Option<RoomType> {
161        self.info.read().room_type().map(ToOwned::to_owned)
162    }
163
164    /// Get the unread notification counts computed server-side.
165    ///
166    /// Note: these might be incorrect for encrypted rooms, since the server
167    /// doesn't know which events are relevant standalone messages or not,
168    /// nor can it inspect mentions. If you need more precise counts for
169    /// encrypted rooms, consider using the client-side computed counts in
170    /// [`Self::num_unread_messages`], [`Self::num_unread_notifications`] and
171    /// [`Self::num_unread_mentions`].
172    pub fn unread_notification_counts(&self) -> UnreadNotificationsCount {
173        self.info.read().notification_counts
174    }
175
176    /// Get the number of unread messages (computed client-side).
177    ///
178    /// This might be more precise than [`Self::unread_notification_counts`] for
179    /// encrypted rooms.
180    pub fn num_unread_messages(&self) -> u64 {
181        self.info.read().read_receipts.num_unread
182    }
183
184    /// Get the number of unread notifications (computed client-side).
185    ///
186    /// This might be more precise than [`Self::unread_notification_counts`] for
187    /// encrypted rooms.
188    pub fn num_unread_notifications(&self) -> u64 {
189        self.info.read().read_receipts.num_notifications
190    }
191
192    /// Get the number of unread mentions (computed client-side), that is,
193    /// messages causing a highlight in a room.
194    ///
195    /// This might be more precise than [`Self::unread_notification_counts`] for
196    /// encrypted rooms.
197    pub fn num_unread_mentions(&self) -> u64 {
198        self.info.read().read_receipts.num_mentions
199    }
200
201    /// Get the detailed information about read receipts for the room.
202    pub fn read_receipts(&self) -> RoomReadReceipts {
203        self.info.read().read_receipts.clone()
204    }
205
206    /// Check if the room states have been synced
207    ///
208    /// States might be missing if we have only seen the room_id of this Room
209    /// so far, for example as the response for a `create_room` request without
210    /// being synced yet.
211    ///
212    /// Returns true if the state is fully synced, false otherwise.
213    pub fn is_state_fully_synced(&self) -> bool {
214        self.info.read().sync_info == SyncInfo::FullySynced
215    }
216
217    /// Check if the room state has been at least partially synced.
218    ///
219    /// See [`Room::is_state_fully_synced`] for more info.
220    pub fn is_state_partially_or_fully_synced(&self) -> bool {
221        self.info.read().sync_info != SyncInfo::NoState
222    }
223
224    /// Get the `prev_batch` token that was received from the last sync. May be
225    /// `None` if the last sync contained the full room history.
226    pub fn last_prev_batch(&self) -> Option<String> {
227        self.info.read().last_prev_batch.clone()
228    }
229
230    /// Get the avatar url of this room.
231    pub fn avatar_url(&self) -> Option<OwnedMxcUri> {
232        self.info.read().avatar_url().map(ToOwned::to_owned)
233    }
234
235    /// Get information about the avatar of this room.
236    pub fn avatar_info(&self) -> Option<avatar::ImageInfo> {
237        self.info.read().avatar_info().map(ToOwned::to_owned)
238    }
239
240    /// Get the canonical alias of this room.
241    pub fn canonical_alias(&self) -> Option<OwnedRoomAliasId> {
242        self.info.read().canonical_alias().map(ToOwned::to_owned)
243    }
244
245    /// Get the canonical alias of this room.
246    pub fn alt_aliases(&self) -> Vec<OwnedRoomAliasId> {
247        self.info.read().alt_aliases().to_owned()
248    }
249
250    /// Get the `m.room.create` content of this room.
251    ///
252    /// This usually isn't optional but some servers might not send an
253    /// `m.room.create` event as the first event for a given room, thus this can
254    /// be optional.
255    ///
256    /// For room versions earlier than room version 11, if the event is
257    /// redacted, all fields except `creator` will be set to their default
258    /// value.
259    pub fn create_content(&self) -> Option<RoomCreateWithCreatorEventContent> {
260        Some(self.info.read().base_info.create.as_ref()?.content.clone())
261    }
262
263    /// Is this room considered a direct message.
264    ///
265    /// Async because it can read room info from storage.
266    #[instrument(skip_all, fields(room_id = ?self.room_id))]
267    pub async fn is_direct(&self) -> StoreResult<bool> {
268        match self.state() {
269            RoomState::Joined | RoomState::Left | RoomState::Banned => {
270                Ok(!self.info.read().base_info.dm_targets.is_empty())
271            }
272
273            RoomState::Invited => {
274                let member = self.get_member(self.own_user_id()).await?;
275
276                match member {
277                    None => {
278                        info!("RoomMember not found for the user's own id");
279                        Ok(false)
280                    }
281                    Some(member) => match member.event.as_ref() {
282                        MemberEvent::Sync(_) => {
283                            warn!("Got MemberEvent::Sync in an invited room");
284                            Ok(false)
285                        }
286                        MemberEvent::Stripped(event) => {
287                            Ok(event.content.is_direct.unwrap_or(false))
288                        }
289                    },
290                }
291            }
292
293            // TODO: implement logic once we have the stripped events as we'd have with an Invite
294            RoomState::Knocked => Ok(false),
295        }
296    }
297
298    /// If this room is a direct message, get the members that we're sharing the
299    /// room with.
300    ///
301    /// *Note*: The member list might have been modified in the meantime and
302    /// the targets might not even be in the room anymore. This setting should
303    /// only be considered as guidance. We leave members in this list to allow
304    /// us to re-find a DM with a user even if they have left, since we may
305    /// want to re-invite them.
306    pub fn direct_targets(&self) -> HashSet<OwnedDirectUserIdentifier> {
307        self.info.read().base_info.dm_targets.clone()
308    }
309
310    /// If this room is a direct message, returns the number of members that
311    /// we're sharing the room with.
312    pub fn direct_targets_length(&self) -> usize {
313        self.info.read().base_info.dm_targets.len()
314    }
315
316    /// Get the guest access policy of this room.
317    pub fn guest_access(&self) -> GuestAccess {
318        self.info.read().guest_access().clone()
319    }
320
321    /// Get the history visibility policy of this room.
322    pub fn history_visibility(&self) -> Option<HistoryVisibility> {
323        self.info.read().history_visibility().cloned()
324    }
325
326    /// Get the history visibility policy of this room, or a sensible default if
327    /// the event is missing.
328    pub fn history_visibility_or_default(&self) -> HistoryVisibility {
329        self.info.read().history_visibility_or_default().clone()
330    }
331
332    /// Is the room considered to be public.
333    ///
334    /// May return `None` if the join rule event is not available.
335    pub fn is_public(&self) -> Option<bool> {
336        self.info.read().join_rule().map(|join_rule| matches!(join_rule, JoinRule::Public))
337    }
338
339    /// Get the join rule policy of this room, if available.
340    pub fn join_rule(&self) -> Option<JoinRule> {
341        self.info.read().join_rule().cloned()
342    }
343
344    /// Get the maximum power level that this room contains.
345    ///
346    /// This is useful if one wishes to normalize the power levels, e.g. from
347    /// 0-100 where 100 would be the max power level.
348    pub fn max_power_level(&self) -> i64 {
349        self.info.read().base_info.max_power_level
350    }
351
352    /// Get the service members in this room, if available.
353    pub fn service_members(&self) -> Option<BTreeSet<OwnedUserId>> {
354        self.info.read().service_members().cloned()
355    }
356
357    /// Get the current power levels of this room.
358    pub async fn power_levels(&self) -> Result<RoomPowerLevels, Error> {
359        let power_levels_content = self
360            .store
361            .get_state_event_static::<RoomPowerLevelsEventContent>(self.room_id())
362            .await?
363            .ok_or(Error::InsufficientData)?
364            .deserialize()?;
365        let creators = self.creators().ok_or(Error::InsufficientData)?;
366        let rules = self.info.read().room_version_rules_or_default();
367
368        Ok(power_levels_content.power_levels(&rules.authorization, creators))
369    }
370
371    /// Get the current power levels of this room, or a sensible default if they
372    /// are not known.
373    pub async fn power_levels_or_default(&self) -> RoomPowerLevels {
374        if let Ok(power_levels) = self.power_levels().await {
375            return power_levels;
376        }
377
378        // As a fallback, create the default power levels of a room.
379        let rules = self.info.read().room_version_rules_or_default();
380        RoomPowerLevels::new(
381            RoomPowerLevelsSource::None,
382            &rules.authorization,
383            self.creators().into_iter().flatten(),
384        )
385    }
386
387    /// Get the `m.room.name` of this room.
388    ///
389    /// The returned string may be empty if the event has been redacted, or it's
390    /// missing from storage.
391    pub fn name(&self) -> Option<String> {
392        self.info.read().name().map(ToOwned::to_owned)
393    }
394
395    /// Get the topic of the room.
396    pub fn topic(&self) -> Option<String> {
397        self.info.read().topic().map(ToOwned::to_owned)
398    }
399
400    /// Update the cached user defined notification mode.
401    ///
402    /// This is automatically recomputed on every successful sync, and the
403    /// cached result can be retrieved in
404    /// [`Self::cached_user_defined_notification_mode`].
405    pub fn update_cached_user_defined_notification_mode(&self, mode: RoomNotificationMode) {
406        self.info.update_if(|info| {
407            if info.cached_user_defined_notification_mode.as_ref() != Some(&mode) {
408                info.cached_user_defined_notification_mode = Some(mode);
409
410                true
411            } else {
412                false
413            }
414        });
415    }
416
417    /// Returns the cached user defined notification mode, if available.
418    ///
419    /// This cache is refilled every time we call
420    /// [`Self::update_cached_user_defined_notification_mode`].
421    pub fn cached_user_defined_notification_mode(&self) -> Option<RoomNotificationMode> {
422        self.info.read().cached_user_defined_notification_mode
423    }
424
425    /// Removes any existing cached value for the user defined notification
426    /// mode.
427    pub fn clear_user_defined_notification_mode(&self) {
428        self.info.update_if(|info| {
429            if info.cached_user_defined_notification_mode.is_some() {
430                info.cached_user_defined_notification_mode = None;
431                true
432            } else {
433                false
434            }
435        })
436    }
437
438    /// Get the list of users ids that are considered to be joined members of
439    /// this room.
440    pub async fn joined_user_ids(&self) -> StoreResult<Vec<OwnedUserId>> {
441        self.store.get_user_ids(self.room_id(), RoomMemberships::JOIN).await
442    }
443
444    /// Get the heroes for this room.
445    pub fn heroes(&self) -> Vec<RoomHero> {
446        self.info.read().heroes().to_vec()
447    }
448
449    /// Get the receipt as an `OwnedEventId` and `Receipt` tuple for the given
450    /// `receipt_type`, `thread` and `user_id` in this room.
451    pub async fn load_user_receipt(
452        &self,
453        receipt_type: ReceiptType,
454        thread: ReceiptThread,
455        user_id: &UserId,
456    ) -> StoreResult<Option<(OwnedEventId, Receipt)>> {
457        self.store.get_user_room_receipt_event(self.room_id(), receipt_type, thread, user_id).await
458    }
459
460    /// Load from storage the receipts as a list of `OwnedUserId` and `Receipt`
461    /// tuples for the given `receipt_type`, `thread` and `event_id` in this
462    /// room.
463    pub async fn load_event_receipts(
464        &self,
465        receipt_type: ReceiptType,
466        thread: ReceiptThread,
467        event_id: &EventId,
468    ) -> StoreResult<Vec<(OwnedUserId, Receipt)>> {
469        self.store
470            .get_event_room_receipt_events(self.room_id(), receipt_type, thread, event_id)
471            .await
472    }
473
474    /// Returns a boolean indicating if this room has been manually marked as
475    /// unread
476    pub fn is_marked_unread(&self) -> bool {
477        self.info.read().base_info.is_marked_unread
478    }
479
480    /// Returns the [`RoomVersionId`] of the room, if known.
481    pub fn version(&self) -> Option<RoomVersionId> {
482        self.info.read().room_version().cloned()
483    }
484
485    /// Returns the recency stamp of the room.
486    ///
487    /// Please read `RoomInfo::recency_stamp` to learn more.
488    pub fn recency_stamp(&self) -> Option<RoomRecencyStamp> {
489        self.info.read().recency_stamp
490    }
491
492    /// Get a `Stream` of loaded pinned events for this room.
493    /// If no pinned events are found a single empty `Vec` will be returned.
494    pub fn pinned_event_ids_stream(&self) -> impl Stream<Item = Vec<OwnedEventId>> + use<> {
495        self.info
496            .subscribe()
497            .map(|i| i.base_info.pinned_events.and_then(|c| c.pinned).unwrap_or_default())
498    }
499
500    /// Returns the current pinned event ids for this room.
501    pub fn pinned_event_ids(&self) -> Option<Vec<OwnedEventId>> {
502        self.info.read().pinned_event_ids()
503    }
504}
505
506// See https://github.com/matrix-org/matrix-rust-sdk/pull/3749#issuecomment-2312939823.
507#[cfg(not(feature = "test-send-sync"))]
508unsafe impl Send for Room {}
509
510// See https://github.com/matrix-org/matrix-rust-sdk/pull/3749#issuecomment-2312939823.
511#[cfg(not(feature = "test-send-sync"))]
512unsafe impl Sync for Room {}
513
514#[cfg(feature = "test-send-sync")]
515#[test]
516// See https://github.com/matrix-org/matrix-rust-sdk/pull/3749#issuecomment-2312939823.
517fn test_send_sync_for_room() {
518    fn assert_send_sync<
519        T: matrix_sdk_common::SendOutsideWasm + matrix_sdk_common::SyncOutsideWasm,
520    >() {
521    }
522
523    assert_send_sync::<Room>();
524}
525
526/// The possible sources of an account data type.
527#[derive(Debug, Clone, Copy, Default, PartialEq, Eq, Serialize, Deserialize)]
528pub(crate) enum AccountDataSource {
529    /// The source is account data with the stable prefix.
530    Stable,
531
532    /// The source is account data with the unstable prefix.
533    #[default]
534    Unstable,
535}
matrix_sdk_base/room/mod.rs

matrix_sdk_base/room/
mod.rs
