Skip to main content

tuwunel_service/rooms/state_cache/
update.rs

1//! Membership-transition writes for the state cache.
2//!
3//! Each transition updates paired membership indexes and removes incompatible
4//! prior states in one database transaction. Optional aggregate rebuilding
5//! refreshes room counts, server participation, and appservice decisions after
6//! the per-user transition lands.
7
8use std::{collections::HashSet, sync::Arc};
9
10use futures::{
11	FutureExt, StreamExt,
12	future::{join, join3},
13};
14use ruma::{
15	EventId, OwnedServerName, RoomId, UserId,
16	events::{
17		AnyStrippedStateEvent, AnySyncStateEvent, GlobalAccountDataEventType,
18		RoomAccountDataEventType, StateEventType,
19		direct::DirectEvent,
20		room::{
21			create::RoomCreateEventContent,
22			member::{MembershipState, RoomMemberEventContent},
23		},
24	},
25	serde::Raw,
26};
27use tuwunel_core::{
28	Result, at, implement, is_not_empty,
29	utils::{
30		BoolExt, FutureBoolExt, OptionExt, ReadyExt,
31		future::ReadyBoolExt,
32		result::{LogErr, NotFound},
33	},
34	warn,
35};
36use tuwunel_database::{Json, Map, Txn, keyval::ValBuf, serialize_key, serialize_val};
37use tuwunel_matrix::PduCount;
38
39use super::FORGOTTEN_STATE;
40
41/// Optional stripped room state attached to invite and knock transitions.
42///
43/// `None` means the caller supplied no state, while `Some` can contain an empty
44/// event vector. Invite and knock handling preserve an existing nonempty row
45/// when no new state is supplied.
46pub type StrippedRoomState = Option<Vec<Raw<AnyStrippedStateEvent>>>;
47
48struct Invite<'a> {
49	last_state: StrippedRoomState,
50	invite_via: Option<Vec<OwnedServerName>>,
51	invite_event: Option<&'a EventId>,
52}
53
54/// Parameters for one membership cache transition.
55///
56/// Borrowed identifiers remain valid only for the duration of the update. Owned
57/// event data is consumed by the selected transition.
58pub struct MembershipUpdate<'a> {
59	/// Room whose membership changed.
60	///
61	/// Membership indexes and aggregate counts are updated for this room.
62	pub room_id: &'a RoomId,
63
64	/// User whose membership changed.
65	///
66	/// Both local and remote users are represented in the membership indexes.
67	pub user_id: &'a UserId,
68
69	/// Membership event content driving the transition.
70	///
71	/// The membership state selects which indexes are written and cleared.
72	pub membership_event: RoomMemberEventContent,
73
74	/// User who sent the membership event.
75	///
76	/// The transition records it for trace attribution rather than reading it.
77	pub sender: &'a UserId,
78
79	/// Stripped room state associated with an invite or knock.
80	///
81	/// Other membership transitions leave this value unused. An absent or empty
82	/// value preserves an invite's or knock's stored state rather than clearing
83	/// it.
84	pub last_state: StrippedRoomState,
85
86	/// Servers supplied as routing hints for an invite.
87	///
88	/// Invite handling stores only non-empty lists. The routing hints commit
89	/// with the membership indexes.
90	pub invite_via: Option<Vec<OwnedServerName>>,
91
92	/// Event ID of the current invitation.
93	///
94	/// An absent ID clears any previously recorded ID on an invite transition.
95	pub invite_event: Option<&'a EventId>,
96
97	/// Whether to rebuild the room's aggregate membership counts.
98	///
99	/// Bulk state updates can defer this rebuild until all transitions are
100	/// applied.
101	pub update_joined_count: bool,
102
103	/// Stream position of the user's own join this event replaces, set only for
104	/// a profile change.
105	///
106	/// Such a join keeps a recorded position no later than the one it replaces,
107	/// so it never reads as a fresh join. Any other join records its own
108	/// position, as does a profile change over a position a forced replay
109	/// recorded after the replaced join.
110	pub replaced_join: Option<PduCount>,
111
112	/// Stream position associated with the membership event.
113	///
114	/// Count-indexed membership rows store its unsigned representation.
115	pub count: PduCount,
116}
117
118/// Applies one membership transition to the derived cache indexes.
119///
120/// Remote users are created before their transition is recorded, and paired
121/// forward and reverse rows change together. Joins can copy predecessor-room
122/// account data and keep the recorded join position across a profile change,
123/// while leaves can trigger push-badge refresh and configured forget behavior.
124/// Aggregate room counts are rebuilt only when requested by the update
125/// descriptor.
126#[implement(super::Service)]
127#[tracing::instrument(
128		level = "debug",
129		skip_all,
130		fields(
131			%room_id,
132			%user_id,
133			%sender,
134			%count,
135			?membership_event,
136		),
137	)]
138pub async fn update_membership(
139	&self,
140	MembershipUpdate {
141		room_id,
142		user_id,
143		membership_event,
144		sender,
145		last_state,
146		invite_via,
147		invite_event,
148		update_joined_count,
149		replaced_join,
150		count,
151	}: MembershipUpdate<'_>,
152) -> Result {
153	let membership = membership_event.membership;
154
155	self.ensure_remote_user(user_id).await?;
156
157	match membership {
158		| MembershipState::Join => {
159			self.handle_join(room_id, user_id, count, replaced_join)
160				.await?;
161		},
162		| MembershipState::Invite => {
163			// An ignored sender's invite is stored anyway; the recipient's list
164			// is applied when it is served, by InviteFilter::permission.
165			let invite = Invite { last_state, invite_via, invite_event };
166
167			self.mark_as_invited(user_id, room_id, count, invite)
168				.await?;
169		},
170		| MembershipState::Leave | MembershipState::Ban => {
171			self.handle_leave(room_id, user_id, count).await?;
172
173			// A departure drops the room from the account-wide badge total.
174			if self.services.globals.user_is_local(user_id) {
175				self.services
176					.sending
177					.refresh_push_badge(user_id)
178					.await
179					.log_err()
180					.ok();
181			}
182		},
183		| MembershipState::Knock => {
184			self.mark_as_knocked(user_id, room_id, count, last_state)
185				.await?;
186		},
187		| _ => {},
188	}
189
190	if update_joined_count {
191		self.update_joined_count(room_id).await;
192	}
193
194	Ok(())
195}
196
197impl<'a> MembershipUpdate<'a> {
198	/// A transition a user makes to their own membership.
199	///
200	/// The user is also the sender; the update carries no stripped state or
201	/// invite routing, is not a profile change, and rebuilds the room's aggregate
202	/// counts. A caller changes any of these by struct update.
203	#[must_use]
204	pub fn self_sent(
205		room_id: &'a RoomId,
206		user_id: &'a UserId,
207		membership_event: RoomMemberEventContent,
208		count: PduCount,
209	) -> Self {
210		Self {
211			room_id,
212			user_id,
213			membership_event,
214			sender: user_id,
215			last_state: None,
216			invite_via: None,
217			invite_event: None,
218			update_joined_count: true,
219			replaced_join: None,
220			count,
221		}
222	}
223}
224
225/// Rebuilds a room's aggregate membership and server indexes.
226///
227/// Current join, invite, and knock rows are counted, and participating servers
228/// are reconciled in one database transaction. Source-stream errors are
229/// skipped, and the room's appservice membership cache is invalidated after
230/// the transaction executes.
231#[implement(super::Service)]
232#[tracing::instrument(level = "debug", skip(self))]
233pub async fn update_joined_count(&self, room_id: &RoomId) {
234	let joined = self.joined_count(room_id);
235	let invited = self.room_members_invited(room_id).count();
236	let knocked = self.room_members_knocked(room_id).count();
237	// Overlap initial seeks; cursor traversal remains synchronous.
238	let ((joinedcount, joined_servers), invitedcount, knockedcount) =
239		join3(joined, invited, knocked).await;
240
241	let invitedcount = u64::try_from(invitedcount).unwrap_or(0);
242	let knockedcount = u64::try_from(knockedcount).unwrap_or(0);
243	let txn = Txn::insert_each_slice(&[
244		(&self.db.roomid_joinedcount, room_id, joinedcount.to_be_bytes()),
245		(&self.db.roomid_invitedcount, room_id, invitedcount.to_be_bytes()),
246		(&self.db.roomid_knockedcount, room_id, knockedcount.to_be_bytes()),
247	]);
248
249	let (txn, joined_servers) = self
250		.room_servers(room_id)
251		.ready_fold((txn, joined_servers), |(mut txn, mut servers), old_server| {
252			if !servers.remove(old_server) {
253				txn.del(&self.db.roomserverids, (room_id, old_server));
254				txn.del(&self.db.serverroomids, (old_server, room_id));
255			}
256
257			(txn, servers)
258		})
259		.await;
260
261	joined_servers
262		.iter()
263		.fold(txn, |mut txn, server| {
264			let roomserver_id =
265				serialize_key((room_id, server)).expect("failed to serialize roomserver_id");
266
267			let serverroom_id =
268				serialize_key((server, room_id)).expect("failed to serialize serverroom_id");
269
270			txn.insert_raw(&self.db.roomserverids, roomserver_id, []);
271			txn.insert_raw(&self.db.serverroomids, serverroom_id, []);
272			txn
273		})
274		.execute();
275
276	self.appservice_in_room_cache
277		.write()
278		.expect("locked")
279		.remove(room_id);
280}
281
282#[implement(super::Service)]
283fn joined_count<'a>(
284	&'a self,
285	room_id: &'a RoomId,
286) -> impl Future<Output = (u64, HashSet<OwnedServerName>)> + Send + 'a {
287	self.room_members(room_id).ready_fold(
288		(0_u64, HashSet::new()),
289		|(count, mut servers), joined| {
290			servers.insert(joined.server_name().to_owned());
291			(count.saturating_add(1), servers)
292		},
293	)
294}
295
296/// Writes the paired indexes for a current join transition.
297///
298/// Invite, leave, and knock rows for the same user and room are removed in the
299/// same transaction. This low-level helper skips once-joined bookkeeping,
300/// predecessor copying, and aggregate rebuilding performed by
301/// [`super::Service::update_membership`].
302#[implement(super::Service)]
303#[tracing::instrument(skip(self), level = "debug")]
304pub(crate) fn mark_as_joined(&self, user_id: &UserId, room_id: &RoomId, count: PduCount) {
305	let userroom_id = (user_id, room_id);
306	let userroom_id = serialize_key(userroom_id).expect("failed to serialize userroom_id");
307
308	let roomuser_id = (room_id, user_id);
309	let roomuser_id = serialize_key(roomuser_id).expect("failed to serialize roomuser_id");
310
311	let count = count.into_unsigned().to_be_bytes();
312	let mut txn = self.services.db.txn();
313
314	txn.insert_raw(&self.db.userroomid_joinedcount, &userroom_id, count);
315	txn.insert_raw(&self.db.roomuserid_joinedcount, &roomuser_id, count);
316	txn.del_raw(&self.db.userroomid_invitestate, &userroom_id);
317	txn.del_raw(&self.db.roomuserid_invitecount, &roomuser_id);
318	txn.del_raw(&self.db.userroomid_leftstate, &userroom_id);
319	txn.del_raw(&self.db.roomuserid_leftcount, &roomuser_id);
320	txn.del_raw(&self.db.userroomid_knockedstate, &userroom_id);
321	txn.del_raw(&self.db.roomuserid_knockedcount, &roomuser_id);
322	txn.execute();
323}
324
325/// Writes the paired indexes for a current leave transition.
326///
327/// The leave state starts as an empty event array, and join, invite, and knock
328/// rows are removed in the same transaction. This low-level helper skips leave
329/// policy and aggregate rebuilding performed by
330/// [`super::Service::update_membership`].
331#[implement(super::Service)]
332#[tracing::instrument(skip(self), level = "debug")]
333pub(crate) fn mark_as_left(&self, user_id: &UserId, room_id: &RoomId, count: PduCount) {
334	let userroom_id = (user_id, room_id);
335	let userroom_id = serialize_key(userroom_id).expect("failed to serialize userroom_id");
336
337	let roomuser_id = (room_id, user_id);
338	let roomuser_id = serialize_key(roomuser_id).expect("failed to serialize roomuser_id");
339
340	let leftstate = serialize_val(Json(Vec::<Raw<AnySyncStateEvent>>::new()))
341		.expect("failed to serialize left state");
342
343	let count = count.into_unsigned().to_be_bytes();
344	let mut txn = self.services.db.txn();
345
346	txn.insert_raw(&self.db.userroomid_leftstate, &userroom_id, leftstate);
347	txn.insert_raw(&self.db.roomuserid_leftcount, &roomuser_id, count);
348	txn.del_raw(&self.db.userroomid_joinedcount, &userroom_id);
349	txn.del_raw(&self.db.roomuserid_joinedcount, &roomuser_id);
350	txn.del_raw(&self.db.userroomid_invitestate, &userroom_id);
351	txn.del_raw(&self.db.roomuserid_invitecount, &roomuser_id);
352	txn.del_raw(&self.db.userroomid_knockedstate, &userroom_id);
353	txn.del_raw(&self.db.roomuserid_knockedcount, &roomuser_id);
354	txn.execute();
355}
356
357/// Writes the paired indexes for a current knock transition.
358///
359/// Missing or empty stripped state preserves an existing nonempty knock row,
360/// while a new state replaces it. Join, invite, and leave rows are removed in
361/// the same transaction, and aggregate rebuilding is left to
362/// [`super::Service::update_membership`].
363#[implement(super::Service)]
364#[tracing::instrument(skip(self, knocked_state), level = "debug")]
365pub(crate) async fn mark_as_knocked(
366	&self,
367	user_id: &UserId,
368	room_id: &RoomId,
369	count: PduCount,
370	knocked_state: StrippedRoomState,
371) -> Result {
372	let userroom_id = (user_id, room_id);
373	let userroom_id = serialize_key(userroom_id).expect("failed to serialize userroom_id");
374
375	let roomuser_id = (room_id, user_id);
376	let roomuser_id = serialize_key(roomuser_id).expect("failed to serialize roomuser_id");
377
378	let knocked_state = self
379		.stripped_state_row(&self.db.userroomid_knockedstate, &userroom_id, knocked_state)
380		.await?;
381
382	let count = count.into_unsigned().to_be_bytes();
383	let mut txn = self.services.db.txn();
384
385	txn.insert_raw(&self.db.userroomid_knockedstate, &userroom_id, knocked_state);
386	txn.insert_raw(&self.db.roomuserid_knockedcount, &roomuser_id, count);
387	txn.del_raw(&self.db.userroomid_joinedcount, &userroom_id);
388	txn.del_raw(&self.db.roomuserid_joinedcount, &roomuser_id);
389	txn.del_raw(&self.db.userroomid_invitestate, &userroom_id);
390	txn.del_raw(&self.db.roomuserid_invitecount, &roomuser_id);
391	txn.del_raw(&self.db.userroomid_leftstate, &userroom_id);
392	txn.del_raw(&self.db.roomuserid_leftcount, &roomuser_id);
393	txn.execute();
394
395	Ok(())
396}
397
398/// The stripped state a membership row stores.
399///
400/// A replay carrying no stripped state must not blank a row that has some, so
401/// missing or empty state keeps the row's stored value. A probe that fails to
402/// read the row is an error, not an absence.
403#[implement(super::Service)]
404async fn stripped_state_row(
405	&self,
406	states: &Arc<Map>,
407	userroom_id: &[u8],
408	last_state: StrippedRoomState,
409) -> Result<ValBuf> {
410	let last_state = last_state.filter(is_not_empty!());
411	let stored = last_state
412		.is_none()
413		.then_async(|| states.get(userroom_id))
414		.await
415		.transpose()
416		.optional()?
417		.flatten();
418
419	let state = stored
420		.as_deref()
421		.map(ValBuf::from_slice)
422		.unwrap_or_else(|| {
423			serialize_val(Json(last_state.unwrap_or_default()))
424				.expect("failed to serialize stripped state")
425		});
426
427	Ok(state)
428}
429
430/// Forgets a user's retained leave state for a room.
431///
432/// The state value becomes a tombstone while its departure position remains
433/// available to incremental sync. Callers hold the room state lock so a rejoin
434/// cannot race this write; a room without a recorded departure stays absent.
435#[implement(super::Service)]
436#[tracing::instrument(skip(self), level = "debug")]
437pub async fn forget(&self, room_id: &RoomId, user_id: &UserId) -> Result {
438	let userroom_id = (user_id, room_id);
439
440	if self
441		.get_departure_count(room_id, user_id)
442		.await
443		.optional()?
444		.is_none()
445	{
446		self.db.userroomid_leftstate.del(userroom_id);
447
448		return Ok(());
449	}
450
451	self.db
452		.userroomid_leftstate
453		.put_raw(userroom_id, FORGOTTEN_STATE);
454
455	Ok(())
456}
457
458#[implement(super::Service)]
459#[tracing::instrument(level = "debug", skip(self))]
460fn mark_as_once_joined(&self, user_id: &UserId, room_id: &RoomId) {
461	let key = (user_id, room_id);
462	let key = serialize_key(key).expect("failed to serialize roomuseroncejoinedid");
463	let mut txn = self.services.db.txn();
464
465	txn.insert_raw(&self.db.roomuseroncejoinedids, key, []);
466	txn.execute();
467}
468
469/// Length floor for an invite whose stripped state holds no events.
470///
471/// `mark_as_invited` below stores the state as JSON, so a row longer than the
472/// empty array carries at least one event. `has_invite_state` probes against
473/// this length, so a change to the value codec here moves that floor.
474pub(super) const EMPTY_INVITE_STATE: &[u8] = b"[]";
475
476/// Writes the paired indexes for a current invite transition.
477///
478/// Missing or empty stripped state preserves an existing nonempty invite row,
479/// while a new state replaces it. Nonempty routing hints are merged into the
480/// room's aggregate hint row and committed with the membership indexes; other
481/// membership rows are removed in the same transaction.
482#[implement(super::Service)]
483#[tracing::instrument(level = "debug", skip(self, last_state, invite_via))]
484async fn mark_as_invited(
485	&self,
486	user_id: &UserId,
487	room_id: &RoomId,
488	count: PduCount,
489	Invite { last_state, invite_via, invite_event }: Invite<'_>,
490) -> Result {
491	let userroom_id = (user_id, room_id);
492	let userroom_id = serialize_key(userroom_id).expect("failed to serialize userroom_id");
493
494	let roomuser_id = (room_id, user_id);
495	let roomuser_id = serialize_key(roomuser_id).expect("failed to serialize roomuser_id");
496
497	// A blanked row would lose the sender the read side judges the invite by.
498	let invite_state = self
499		.stripped_state_row(&self.db.userroomid_invitestate, &userroom_id, last_state)
500		.await?;
501
502	let mut txn = self.services.db.txn();
503
504	txn.insert_raw(&self.db.userroomid_invitestate, &userroom_id, invite_state);
505	txn.put(
506		&self.db.roomuserid_invitecount,
507		(room_id, user_id),
508		(count.into_unsigned(), invite_event),
509	);
510
511	txn.del_raw(&self.db.userroomid_joinedcount, &userroom_id);
512	txn.del_raw(&self.db.roomuserid_joinedcount, &roomuser_id);
513	txn.del_raw(&self.db.userroomid_leftstate, &userroom_id);
514	txn.del_raw(&self.db.roomuserid_leftcount, &roomuser_id);
515	txn.del_raw(&self.db.userroomid_knockedstate, &userroom_id);
516	txn.del_raw(&self.db.roomuserid_knockedcount, &roomuser_id);
517
518	if let Some(servers) = invite_via.filter(is_not_empty!()) {
519		self.add_servers_invite_via(&mut txn, room_id, servers)
520			.await;
521	}
522
523	txn.execute();
524
525	Ok(())
526}
527
528#[implement(super::Service)]
529#[tracing::instrument(skip(self), level = "debug")]
530async fn ensure_remote_user(&self, user_id: &UserId) -> Result {
531	if self.services.globals.user_is_local(user_id) || self.services.users.exists(user_id).await {
532		return Ok(());
533	}
534
535	self.services
536		.users
537		.create(user_id, None, None)
538		.await
539}
540
541#[implement(super::Service)]
542async fn handle_join(
543	&self,
544	room_id: &RoomId,
545	user_id: &UserId,
546	count: PduCount,
547	replaced_join: Option<PduCount>,
548) -> Result {
549	if !self.once_joined(user_id, room_id).await {
550		self.mark_as_once_joined(user_id, room_id);
551		self.copy_predecessor_data(room_id, user_id)
552			.await?;
553	}
554
555	// A missing, malformed or legacy empty row (read as zero) takes the position.
556	let keep = replaced_join
557		.map_async(async |replaced| {
558			let replaced = replaced.into_normal().into_unsigned();
559
560			self.get_joined_count(room_id, user_id)
561				.await
562				.is_ok_and(|recorded| (1..=replaced).contains(&recorded))
563		})
564		.await
565		.unwrap_or_default();
566
567	if !keep {
568		self.mark_as_joined(user_id, room_id, count);
569	}
570
571	Ok(())
572}
573
574#[implement(super::Service)]
575async fn copy_predecessor_data(&self, room_id: &RoomId, user_id: &UserId) -> Result {
576	let Ok(Some(predecessor)) = self
577		.services
578		.state_accessor
579		.room_state_get_content(room_id, &StateEventType::RoomCreate, "")
580		.await
581		.map(|content: RoomCreateEventContent| content.predecessor)
582	else {
583		return Ok(());
584	};
585
586	join(
587		self.copy_predecessor_tags(room_id, user_id, &predecessor.room_id),
588		self.copy_predecessor_direct(room_id, user_id, &predecessor.room_id),
589	)
590	.map(at!(1))
591	.await
592}
593
594#[implement(super::Service)]
595#[tracing::instrument(skip(self), level = "debug")]
596async fn copy_predecessor_tags(&self, room_id: &RoomId, user_id: &UserId, predecessor: &RoomId) {
597	let Ok(tag_event) = self
598		.services
599		.account_data
600		.get_room(predecessor, user_id, RoomAccountDataEventType::Tag)
601		.await
602	else {
603		return;
604	};
605
606	self.services
607		.account_data
608		.update(Some(room_id), user_id, RoomAccountDataEventType::Tag, &tag_event)
609		.await
610		.ok();
611}
612
613#[implement(super::Service)]
614#[tracing::instrument(skip(self), level = "debug")]
615async fn copy_predecessor_direct(
616	&self,
617	room_id: &RoomId,
618	user_id: &UserId,
619	predecessor: &RoomId,
620) -> Result {
621	let Ok(mut direct_event) = self
622		.services
623		.account_data
624		.get_global::<DirectEvent>(user_id, GlobalAccountDataEventType::Direct)
625		.await
626	else {
627		return Ok(());
628	};
629
630	let room_ids_updated =
631		direct_event
632			.content
633			.0
634			.values_mut()
635			.fold(false, |updated, room_ids| {
636				if !room_ids
637					.iter()
638					.any(|direct_room_id| direct_room_id == predecessor)
639				{
640					return updated;
641				}
642
643				room_ids.push(room_id.to_owned());
644
645				true
646			});
647
648	if !room_ids_updated {
649		return Ok(());
650	}
651
652	let event_type = GlobalAccountDataEventType::Direct
653		.to_string()
654		.into();
655
656	let direct_event =
657		serde_json::to_value(&direct_event).expect("failed to serialize DirectEvent");
658
659	self.services
660		.account_data
661		.update(None, user_id, event_type, &direct_event)
662		.await
663}
664
665#[implement(super::Service)]
666#[tracing::instrument(skip(self), level = "debug")]
667async fn handle_leave(&self, room_id: &RoomId, user_id: &UserId, count: PduCount) -> Result {
668	if self.is_forgotten(user_id, room_id).await? {
669		return Ok(());
670	}
671
672	self.mark_as_left(user_id, room_id, count);
673
674	if !self.services.globals.user_is_local(user_id) {
675		return Ok(());
676	}
677
678	if self
679		.services
680		.config
681		.rooms
682		.forget_forced_upon_leave
683		.is_false()
684	{
685		let not_disabled = self
686			.services
687			.metadata
688			.is_disabled(room_id)
689			.is_false();
690
691		let not_banned = self
692			.services
693			.metadata
694			.is_banned(room_id)
695			.is_false();
696
697		if not_disabled.and(not_banned).await {
698			return Ok(());
699		}
700	}
701
702	self.forget(room_id, user_id).await
703}