Skip to main content

tuwunel_service/rooms/state/
mod.rs

1//! Stores room state snapshots and tracks each room's forward extremities.
2//!
3//! The service associates events with compressed state hashes and replays
4//! derived cache effects when state is forced. State snapshots themselves are
5//! encoded and reconstructed by the state compressor service.
6
7mod fetch_state;
8mod prune;
9#[cfg(test)]
10mod tests;
11
12use std::{
13	collections::HashMap,
14	fmt::Write,
15	iter::once,
16	ops::Bound::{Excluded, Unbounded},
17	sync::Arc,
18};
19
20use async_trait::async_trait;
21/// Fetches state events through a held map of short state keys.
22///
23/// Sibling services share its distinction between absent state and missing storage.
24pub(crate) use fetch_state::IdMapState;
25use futures::{FutureExt, Stream, StreamExt, TryFutureExt, TryStreamExt, future::join_all};
26/// Re-exports the receive-path pruning goal calculation within the crate.
27///
28/// Sibling room services use it to pace extremity reduction.
29pub(crate) use prune::prune_goal;
30/// Re-exports the forward-extremity pruning result and invocation source.
31///
32/// Callers use these types to report pruning effects and select path-specific
33/// behavior.
34pub use prune::{PruneSummary, Trigger};
35use ruma::{
36	CanonicalJsonObject, EventId, OwnedEventId, OwnedRoomId, RoomId, RoomVersionId, UserId,
37	events::{
38		AnyStrippedStateEvent, StateEventType, TimelineEventType,
39		room::{
40			create::RoomCreateEventContent,
41			member::{MembershipState, RoomMemberEventContent},
42		},
43	},
44	room_version_rules::AuthorizationRules,
45	serde::Raw,
46};
47use serde::Deserialize;
48use serde_json::value::RawValue as RawJsonValue;
49use tuwunel_core::{
50	Error, Result, err,
51	error::inspect_debug_log,
52	implement,
53	result::{AndThenRef, FlatOk, NotFound},
54	smallvec::SmallVec,
55	trace,
56	utils::{
57		BoolExt, IterStream, MutexMap, MutexMapGuard, ReadyExt, TryFutureExtExt, TryReadyExt,
58		calculate_hash,
59		hash::sha256::Digest,
60		mutex_map::Guard,
61		stream::{TryBroadbandExt, TryIgnore, WidebandExt},
62	},
63	warn,
64};
65use tuwunel_database::{Deserialized, Ignore, Interfix, Map, Txn};
66use tuwunel_matrix::{
67	Event, PduCount, PduEvent, RoomVersionRules, StateKey, TypeStateKey,
68	room::state::resolution::{StateMap, auth_types_for_event},
69	room_version,
70};
71
72use crate::{
73	integrity::undecodable,
74	rooms::{
75		short::{ShortEventId, ShortStateHash, ShortStateKey},
76		state_cache::{MembershipUpdate, StrippedRoomState},
77		state_compressor::{
78			CompressedState, CompressedStateEvent, ShortStateInfo, compress_state_event,
79			parse_compressed_state_event,
80		},
81		timeline::Mapped,
82	},
83	services::OnceServices,
84};
85
86/// Manages current room state, event state snapshots, and forward extremities.
87///
88/// State mutations are serialized per room and delegated to the compressor for
89/// persistent delta encoding. The service also coordinates cache updates that
90/// follow forced state changes.
91pub struct Service {
92	/// Serializes room state as the middle per-room operation.
93	///
94	/// Acquire it after federation and before timeline insertion when those
95	/// mutexes share a room. Never acquire the federation mutex while holding
96	/// this guard.
97	pub mutex: RoomMutexMap,
98	services: Arc<OnceServices>,
99	db: Data,
100}
101
102struct Data {
103	shorteventid_shortstatehash: Arc<Map>,
104	roomid_shortstatehash: Arc<Map>,
105	roomid_pduleaves: Arc<Map>,
106}
107
108type RoomMutexMap = MutexMap<OwnedRoomId, ()>;
109/// Guard proving exclusive access to a room's state mutation path.
110///
111/// Acquire it after the federation guard and before the timeline insertion
112/// guard when the same operation needs all three.
113pub type RoomMutexGuard = MutexMapGuard<OwnedRoomId, ()>;
114type ForwardExtremities = SmallVec<[OwnedEventId; 1]>;
115type SummaryCell<'a> = (&'a StateEventType, &'a str);
116
117#[derive(Deserialize)]
118struct CreateEvent {
119	content: RoomCreateEventContent,
120}
121
122#[async_trait]
123impl crate::Service for Service {
124	fn build(args: &crate::Args<'_>) -> Result<Arc<Self>> {
125		Ok(Arc::new(Self {
126			mutex: RoomMutexMap::new(),
127			services: args.services.clone(),
128			db: Data {
129				shorteventid_shortstatehash: args.db["shorteventid_shortstatehash"].clone(),
130				roomid_shortstatehash: args.db["roomid_shortstatehash"].clone(),
131				roomid_pduleaves: args.db["roomid_pduleaves"].clone(),
132			},
133		}))
134	}
135
136	async fn memory_usage(&self, out: &mut (dyn Write + Send)) -> Result {
137		let mutex = self.mutex.len();
138		writeln!(out, "- state_mutex: {mutex}")?;
139
140		Ok(())
141	}
142
143	fn name(&self) -> &str { crate::service::make_name(std::module_path!()) }
144}
145
146/// Forces a room to use an existing state snapshot.
147///
148/// Resolvable membership additions replay their cache effects before the
149/// current state hash is installed. Reverse-ID and PDU lookup failures are
150/// skipped, while a membership-effect error returns before the state hash
151/// changes. Joined counts are refreshed and the cached space summary is
152/// invalidated while the caller retains the room state guard.
153#[implement(Service)]
154#[tracing::instrument(
155	name = "force",
156	level = "debug",
157	skip_all,
158	fields(
159		count = ?self.services.globals.pending_count(),
160		%shortstatehash,
161	)
162)]
163pub async fn force_state(
164	&self,
165	room_id: &RoomId,
166	shortstatehash: u64,
167	statediffnew: Arc<CompressedState>,
168	_statediffremoved: Arc<CompressedState>,
169	state_lock: &RoomMutexGuard,
170) -> Result {
171	self.prepare_force_state(room_id, &statediffnew, state_lock)
172		.await?;
173
174	self.install_force_state(room_id, shortstatehash, state_lock);
175
176	Ok(())
177}
178
179/// Replays membership additions before installing a forced state snapshot.
180///
181/// Lookup failures are skipped; membership-effect errors propagate before
182/// joined counts are refreshed. The caller retains the room state guard
183/// through preparation and installation.
184#[implement(Service)]
185#[tracing::instrument(level = "debug", skip_all)]
186pub(crate) async fn prepare_force_state(
187	&self,
188	room_id: &RoomId,
189	statediffnew: &CompressedState,
190	_state_lock: &RoomMutexGuard,
191) -> Result {
192	statediffnew
193		.iter()
194		.stream()
195		.map(|&new| parse_compressed_state_event(new).1)
196		.wide_filter_map(async |shorteventid| {
197			let event_id: OwnedEventId = self
198				.services
199				.short
200				.get_eventid_from_short(shorteventid)
201				.inspect_err(inspect_debug_log)
202				.await
203				.ok()?;
204
205			self.services
206				.timeline
207				.get_pdu(&event_id)
208				.await
209				.ok()
210		})
211		.map(Ok)
212		.try_for_each(async |pdu| match pdu.kind {
213			| TimelineEventType::RoomMember => self.force_member_effects(room_id, &pdu).await,
214			| _ => Ok(()),
215		})
216		.boxed() // size firewall
217		.await?;
218
219	self.services
220		.state_cache
221		.update_joined_count(room_id)
222		.await;
223
224	Ok(())
225}
226
227/// Installs a prepared state snapshot and invalidates its hierarchy summary.
228///
229/// Preparation and any required timeline append must have succeeded under
230/// the same room state guard before installation.
231#[implement(Service)]
232pub(crate) fn install_force_state(
233	&self,
234	room_id: &RoomId,
235	shortstatehash: u64,
236	state_lock: &RoomMutexGuard,
237) {
238	self.set_room_state(room_id, shortstatehash, state_lock);
239	self.services.spaces.cache_evict(room_id);
240}
241
242/// Record the membership transition a replayed `m.room.member` event carries.
243///
244/// A replayed invite is judged by the sender named in its stripped state, so a
245/// local invitee's row has to carry one. An event whose state key or content
246/// does not parse is skipped rather than failing the whole replay.
247#[implement(Service)]
248async fn force_member_effects(&self, room_id: &RoomId, pdu: &PduEvent) -> Result {
249	let Some(user_id) = pdu
250		.state_key
251		.as_ref()
252		.map(UserId::parse)
253		.flat_ok()
254	else {
255		return Ok(());
256	};
257
258	let Ok(membership_event): Result<RoomMemberEventContent> = pdu.get_content() else {
259		return Ok(());
260	};
261
262	let last_state = membership_event
263		.membership
264		.eq(&MembershipState::Invite)
265		.and_is(self.services.globals.user_is_local(&user_id))
266		.then_async(|| self.replayed_invite_state(room_id, &user_id, pdu))
267		.map(Option::transpose)
268		.map_ok(Option::flatten)
269		.await?;
270
271	let invite_event = membership_event
272		.membership
273		.eq(&MembershipState::Invite)
274		.then_some(pdu.event_id());
275
276	let count = self.services.globals.next_count();
277
278	self.services
279		.state_cache
280		.update_membership(MembershipUpdate {
281			room_id,
282			user_id: &user_id,
283			invite_event,
284			membership_event,
285			sender: &pdu.sender,
286			last_state,
287			invite_via: None,
288			update_joined_count: false,
289			replaced_join: None,
290			count: PduCount::Normal(*count),
291		})
292		.await
293}
294
295/// Computes stripped state for a replayed invite, unless the row has some.
296///
297/// A reset reaches this before the new state is installed, so the summary built
298/// here is thinner than what the invite itself stored. Returning nothing leaves
299/// the stored row for `mark_as_invited` to keep. A probe that fails to read
300/// the row is an error, not an absence.
301#[implement(Service)]
302async fn replayed_invite_state(
303	&self,
304	room_id: &RoomId,
305	user_id: &UserId,
306	pdu: &PduEvent,
307) -> Result<StrippedRoomState> {
308	self.services
309		.state_cache
310		.has_invite_state(user_id, room_id)
311		.await?
312		.is_false()
313		.then_async(|| self.summary_stripped(pdu))
314		.map(Ok)
315		.await
316}
317
318/// Associates an event with a complete compressed state snapshot.
319///
320/// The snapshot hash is reused when known; otherwise a short state hash and a
321/// delta from the room's current snapshot are stored together. This records the
322/// event's state without advancing the room's current state.
323#[implement(Service)]
324#[tracing::instrument(
325	name = "set",
326	level = "debug",
327	skip(self, state_ids_compressed),
328	fields(
329		count = ?self.services.globals.pending_count(),
330	)
331)]
332pub async fn set_event_state(
333	&self,
334	event_id: &EventId,
335	room_id: &RoomId,
336	state_ids_compressed: Arc<CompressedState>,
337) -> Result<ShortStateHash> {
338	const KEY_LEN: usize = size_of::<ShortEventId>();
339	const VAL_LEN: usize = size_of::<ShortStateHash>();
340
341	let shorteventid = self
342		.services
343		.short
344		.get_or_create_shorteventid(event_id)
345		.await;
346
347	let state_hash = calculate_hash(state_ids_compressed.iter().map(|s| &s[..]));
348
349	if let Ok(shortstatehash) = self
350		.services
351		.short
352		.get_shortstatehash(&state_hash)
353		.await
354	{
355		self.db
356			.shorteventid_shortstatehash
357			.aput::<KEY_LEN, VAL_LEN, _, _>(shorteventid, shortstatehash);
358
359		return Ok(shortstatehash);
360	}
361
362	let previous_shortstatehash = self.get_room_shortstatehash(room_id).await;
363	let states_parents = match previous_shortstatehash {
364		| Ok(p) =>
365			self.services
366				.state_compressor
367				.load_shortstatehash_info(p)
368				.await?,
369		| _ => Vec::new(),
370	};
371
372	let (statediffnew, statediffremoved) = if let Some(parent_stateinfo) = states_parents.last() {
373		let statediffnew: CompressedState = state_ids_compressed
374			.difference(&parent_stateinfo.full_state)
375			.copied()
376			.collect();
377
378		let statediffremoved: CompressedState = parent_stateinfo
379			.full_state
380			.difference(&state_ids_compressed)
381			.copied()
382			.collect();
383
384		(Arc::new(statediffnew), Arc::new(statediffremoved))
385	} else {
386		(state_ids_compressed, Arc::new(CompressedState::new()))
387	};
388
389	let shortstatehash = self
390		.store_snapshot(&state_hash, states_parents, || (statediffnew, statediffremoved))
391		.await?;
392
393	self.db
394		.shorteventid_shortstatehash
395		.aput::<KEY_LEN, VAL_LEN, _, _>(shorteventid, shortstatehash);
396
397	Ok(shortstatehash)
398}
399
400/// Returns the snapshot after an event: its own snapshot with the event applied.
401///
402/// An event's recorded snapshot precedes it. A state event replaces the entry
403/// under its state key, and the result is stored by hash as a delta from that
404/// snapshot, so a repeated call reuses it. Any other event returns its snapshot
405/// unchanged.
406#[implement(Service)]
407#[tracing::instrument(level = "debug", skip_all)]
408pub async fn shortstatehash_after_event<Pdu: Event>(&self, pdu: &Pdu) -> Result<ShortStateHash> {
409	let before = self.pdu_shortstatehash(pdu.event_id()).await?;
410	let Some(state_key) = pdu.state_key() else {
411		return Ok(before);
412	};
413
414	let layers = self
415		.services
416		.state_compressor
417		.load_shortstatehash_info(before)
418		.await?;
419
420	let parent = layers
421		.last()
422		.ok_or_else(|| err!(Database("Snapshot {before} has no layers")))?;
423
424	let (applied, replaced) = self
425		.state_entry_change(pdu, state_key, Some(parent.full_state.as_ref()))
426		.await;
427
428	if replaced == Some(applied) {
429		return Ok(before);
430	}
431
432	// Hashed in the set's sorted order, with the event's entry in place of the one it replaces.
433	let state = parent
434		.full_state
435		.range(..applied)
436		.chain(once(&applied))
437		.chain(
438			parent
439				.full_state
440				.range((Excluded(applied), Unbounded)),
441		)
442		.filter(|event| replaced.as_ref() != Some(*event));
443
444	let state_hash = calculate_hash(state.map(|event| &event[..]));
445
446	self.store_snapshot(&state_hash, layers, || {
447		(Arc::new([applied].into()), Arc::new(replaced.into_iter().collect()))
448	})
449	.await
450}
451
452/// Compresses a state event and finds the entry under its key in a snapshot.
453///
454/// The event's short IDs are allocated when absent, so the compressed entry is
455/// ready to store; a snapshot holds at most one entry under a key.
456#[implement(Service)]
457async fn state_entry_change<Pdu: Event>(
458	&self,
459	pdu: &Pdu,
460	state_key: &str,
461	full_state: Option<&CompressedState>,
462) -> (CompressedStateEvent, Option<CompressedStateEvent>) {
463	let event_type: StateEventType = pdu.event_type().to_cow_str().into();
464	let shortstatekey = self
465		.services
466		.short
467		.get_or_create_shortstatekey(&event_type, state_key)
468		.await;
469
470	let applied = self
471		.services
472		.state_compressor
473		.compress_state_event(shortstatekey, pdu.event_id())
474		.await;
475
476	let start = compress_state_event(shortstatekey, 0);
477	let end = compress_state_event(shortstatekey, u64::MAX);
478	let replaced =
479		full_state.and_then(|full_state| full_state.range(start..=end).next().copied());
480
481	(applied, replaced)
482}
483
484/// Stores a snapshot under its hash as a delta from its parents, unless known.
485///
486/// The delta is built only when the snapshot is new. Nothing is based on it in
487/// turn, so it never becomes a parent itself.
488#[implement(Service)]
489async fn store_snapshot(
490	&self,
491	state_hash: &Digest,
492	parents: Vec<ShortStateInfo>,
493	delta: impl FnOnce() -> (Arc<CompressedState>, Arc<CompressedState>) + Send,
494) -> Result<ShortStateHash> {
495	let save_statediff = |txn: &mut Txn, shortstatehash| {
496		let (added, removed) = delta();
497
498		self.services
499			.state_compressor
500			.save_state_from_diff(
501				txn,
502				shortstatehash,
503				added,
504				removed,
505				1_000_000, // high number because no state will be based on this one
506				parents,
507			)
508	};
509
510	self.services
511		.short
512		.get_or_create_shortstatehash(state_hash, save_statediff)
513		.map_ok(|(shortstatehash, _)| shortstatehash)
514		.await
515}
516
517/// Derives the state snapshot produced by appending a local PDU.
518///
519/// The event is associated with the preceding snapshot before a state event
520/// creates a one-entry delta and a new short state hash. A non-state event
521/// retains the preceding hash, and an unchanged state event reuses it.
522/// The event's short ID is allocated here if absent, which is the only
523/// allocation of it on the local append path.
524///
525/// # Panics
526///
527/// Panics if a room's first event is not state-bearing or if an unchanged state
528/// entry is found without a preceding room snapshot.
529#[implement(Service)]
530#[tracing::instrument(
531	name = "set",
532	level = "debug",
533	skip(self, new_pdu),
534	fields(
535		count = ?self.services.globals.pending_count(),
536	)
537)]
538pub async fn append_to_state(&self, new_pdu: &PduEvent) -> Result<u64> {
539	const KEY_LEN: usize = size_of::<ShortEventId>();
540	const VAL_LEN: usize = size_of::<ShortStateHash>();
541
542	let shorteventid = self
543		.services
544		.short
545		.get_or_create_shorteventid(&new_pdu.event_id)
546		.await;
547
548	let previous_shortstatehash = self
549		.get_room_shortstatehash(&new_pdu.room_id)
550		.await;
551
552	if let Ok(p) = previous_shortstatehash {
553		self.db
554			.shorteventid_shortstatehash
555			.aput::<KEY_LEN, VAL_LEN, _, _>(shorteventid, p);
556	}
557
558	match &new_pdu.state_key {
559		| Some(state_key) => {
560			let states_parents = match previous_shortstatehash {
561				| Ok(p) =>
562					self.services
563						.state_compressor
564						.load_shortstatehash_info(p)
565						.await?,
566				| _ => Vec::new(),
567			};
568
569			let full_state = states_parents
570				.last()
571				.map(|info| info.full_state.as_ref());
572
573			let (new, replaces) = self
574				.state_entry_change(new_pdu, state_key, full_state)
575				.await;
576
577			if Some(new) == replaces {
578				return Ok(previous_shortstatehash.expect("must exist"));
579			}
580
581			// TODO: statehash with deterministic inputs
582			let shortstatehash = self.services.globals.next_count();
583			let mut txn = self.services.db.txn();
584
585			self.services
586				.state_compressor
587				.save_state_from_diff(
588					&mut txn,
589					*shortstatehash,
590					Arc::new([new].into()),
591					Arc::new(replaces.into_iter().collect()),
592					2,
593					states_parents,
594				)?;
595
596			txn.execute();
597
598			Ok(*shortstatehash)
599		},
600		| _ => Ok(previous_shortstatehash.expect("first event in room must be a state event")),
601	}
602}
603
604/// Sets the room's current state hash without updating derived state caches.
605///
606/// The guard proves that the caller owns the room state mutation path. Callers
607/// that change effective state must update the relevant caches separately.
608#[implement(Service)]
609#[tracing::instrument(skip(self, _mutex_lock), level = "debug")]
610pub fn set_room_state(
611	&self,
612	room_id: &RoomId,
613	shortstatehash: u64,
614	// Take mutex guard to make sure users get the room state mutex
615	_mutex_lock: &RoomMutexGuard,
616) {
617	const BUFSIZE: usize = size_of::<u64>();
618
619	self.db
620		.roomid_shortstatehash
621		.raw_aput::<BUFSIZE, _, _>(room_id, shortstatehash);
622}
623
624/// Fetches the auth events required from a room's current state.
625///
626/// The required state keys are derived from the proposed event and room
627/// authorization rules. A room without current state yields an empty map, and
628/// missing short-key mappings or stored PDUs are omitted.
629#[implement(Service)]
630#[expect(clippy::too_many_arguments)]
631#[tracing::instrument(skip(self, content), level = "debug")]
632pub async fn get_auth_events(
633	&self,
634	room_id: &RoomId,
635	kind: &TimelineEventType,
636	sender: &UserId,
637	state_key: Option<&str>,
638	content: &serde_json::value::RawValue,
639	auth_rules: &AuthorizationRules,
640	include_create: bool,
641) -> Result<StateMap<PduEvent>>
642where
643	StateEventType: Send + Sync,
644	StateKey: Send + Sync,
645{
646	let Some(shortstatehash) = self
647		.get_room_shortstatehash(room_id)
648		.await
649		.optional()?
650	else {
651		return Ok(StateMap::new());
652	};
653
654	let sauthevents: HashMap<ShortStateKey, TypeStateKey> =
655		auth_types_for_event(kind, sender, state_key, content, auth_rules, include_create)?
656			.into_iter()
657			.try_stream()
658			.broad_and_then(async |(event_type, state_key): TypeStateKey| {
659				self.services
660					.short
661					.get_shortstatekey(&event_type, &state_key)
662					.await
663					.map(|sstatekey| (sstatekey, (event_type, state_key)))
664					.optional()
665			})
666			.ready_try_filter_map(Result::Ok)
667			.try_collect()
668			.await?;
669
670	let matching_state: Vec<_> = self
671		.services
672		.state_accessor
673		.state_full_shortids(shortstatehash)
674		.ready_try_filter_map(|(shortstatekey, shorteventid)| {
675			Ok(sauthevents
676				.get(&shortstatekey)
677				.map(move |(ty, sk)| ((ty, sk), shorteventid)))
678		})
679		.try_collect()
680		.await?;
681	let (state_keys, event_ids): (Vec<_>, Vec<_>) = matching_state.into_iter().unzip();
682
683	self.services
684		.short
685		.multi_get_eventid_from_short(event_ids.into_iter().stream())
686		.zip(state_keys.into_iter().stream())
687		.map(|(event_id, state_key)| {
688			event_id
689				.map(|event_id| (state_key, event_id))
690				.optional()
691		})
692		.ready_try_filter_map(Result::Ok)
693		.broad_and_then(async |((ty, sk), event_id): ((&_, &_), OwnedEventId)| {
694			self.services
695				.timeline
696				.get_pdu(&event_id)
697				.map_ok(|pdu| ((ty.clone(), sk.clone()), pdu))
698				.await
699				.optional()
700		})
701		.ready_try_filter_map(Result::Ok)
702		.try_collect()
703		.await
704}
705
706/// Builds stripped invite-state context for a membership event.
707///
708/// Recommended room state cells are fetched on a best-effort basis, then the
709/// supplied membership event is appended last. A cell absent from the current
710/// state is skipped, which is every cell before a room's first snapshot; any
711/// other failed lookup is logged and omitted.
712#[implement(Service)]
713#[tracing::instrument(skip_all, level = "debug")]
714pub async fn summary_stripped<Pdu: Event>(&self, event: &Pdu) -> Vec<Raw<AnyStrippedStateEvent>> {
715	let room_id = event.room_id();
716	let fetches = summary_cells(event).map(|cell| self.summary_state_event(room_id, cell));
717
718	join_all(fetches)
719		.await
720		.into_iter()
721		.flatten()
722		.map(Event::into_format)
723		.chain(once(event.to_format()))
724		.collect()
725}
726
727/// The room state cells a membership event's summary recommends.
728///
729/// The sender's member event is recommended only when the event is about
730/// another user, so an invite carries its inviter's (MSC4319). A knock's
731/// sender is its subject, whose earlier membership would precede the knock.
732fn summary_cells<Pdu: Event>(event: &Pdu) -> impl Iterator<Item = SummaryCell<'_>> {
733	let sender = event.sender().as_str();
734	let inviter = event
735		.state_key()
736		.ne(&Some(sender))
737		.then_some((&StateEventType::RoomMember, sender));
738
739	[
740		(&StateEventType::RoomCreate, ""),
741		(&StateEventType::RoomJoinRules, ""),
742		(&StateEventType::RoomCanonicalAlias, ""),
743		(&StateEventType::RoomName, ""),
744		(&StateEventType::RoomAvatar, ""),
745	]
746	.into_iter()
747	.chain(inviter)
748	.chain([(&StateEventType::RoomEncryption, ""), (&StateEventType::RoomTopic, "")])
749}
750
751/// Reads one recommended cell of the room's current state.
752///
753/// The cell's lookup and its event read are separate steps because both report
754/// a miss the same way, and only the first of those is an absent cell.
755#[implement(Service)]
756#[tracing::instrument(level = "trace", skip_all)]
757async fn summary_state_event(&self, room_id: &RoomId, cell: SummaryCell<'_>) -> Option<PduEvent> {
758	let (event_type, state_key) = cell;
759	let event_id = self
760		.services
761		.state_accessor
762		.room_state_get_id(room_id, event_type, state_key)
763		.map(|lookup| summary_event_id(room_id, cell, lookup))
764		.await?;
765
766	self.services
767		.timeline
768		.get_pdu(&event_id)
769		.inspect_err(unreadable_summary_event(room_id, &event_id))
770		.ok()
771		.await
772}
773
774fn summary_event_id(
775	room_id: &RoomId,
776	(event_type, state_key): SummaryCell<'_>,
777	lookup: Result<OwnedEventId>,
778) -> Option<OwnedEventId> {
779	lookup
780		.present()
781		.inspect_err(|error| {
782			warn!(
783				%room_id,
784				%event_type,
785				%state_key,
786				%error,
787				"Omitting unreadable summary state."
788			);
789		})
790		.flat_ok()
791}
792
793fn unreadable_summary_event(room_id: &RoomId, event_id: &EventId) -> impl Fn(&Error) {
794	move |error| warn!(%room_id, %event_id, %error, "Omitting unreadable summary event.")
795}
796
797/// Builds full-PDU invite-state context for a membership event.
798///
799/// Recommended stored state and the supplied event are formatted for the given
800/// room version as required by MSC4311. A recommended event absent from the
801/// current state is skipped; any other failed lookup, including an event the
802/// state references but storage cannot read as a PDU, is logged and omitted.
803/// The supplied membership event is appended last.
804#[implement(Service)]
805#[tracing::instrument(skip_all, level = "debug")]
806pub async fn summary_pdus<Pdu: Event>(
807	&self,
808	event: &Pdu,
809	event_json: &CanonicalJsonObject,
810	room_version: &RoomVersionId,
811) -> Vec<Box<RawJsonValue>> {
812	let room_id = event.room_id();
813	let membership = self
814		.services
815		.federation
816		.format_pdu_into(event_json.clone(), Some(room_version))
817		.boxed() // query-depth firewall
818		.await;
819
820	// A room with a membership event to summarize has a snapshot; a failed read is a fault.
821	let shortstatehash = self
822		.get_room_shortstatehash(room_id)
823		.inspect_err(|error| {
824			warn!(%room_id, %error, "Omitting summary state of an unreadable snapshot.");
825		})
826		.ok()
827		.await;
828
829	shortstatehash
830		.into_iter()
831		.cycle()
832		.zip(summary_cells(event))
833		.stream()
834		.wide_filter_map(|(shortstatehash, cell)| {
835			self.summary_state_pdu(room_id, shortstatehash, cell, room_version)
836		})
837		.chain(once(membership).stream())
838		.collect()
839		.await
840}
841
842#[implement(Service)]
843#[tracing::instrument(level = "trace", skip_all)]
844async fn summary_state_pdu(
845	&self,
846	room_id: &RoomId,
847	shortstatehash: ShortStateHash,
848	cell: SummaryCell<'_>,
849	room_version: &RoomVersionId,
850) -> Option<Box<RawJsonValue>> {
851	let (event_type, state_key) = cell;
852	let event_id = self
853		.services
854		.state_accessor
855		.state_get_id(shortstatehash, event_type, state_key)
856		.map(|lookup| summary_event_id(room_id, cell, lookup))
857		.await?;
858
859	// MSC4311 serves PDUs only, so the row must parse as one before it is formatted.
860	self.services
861		.timeline
862		.get_pdu(&event_id)
863		.and_then(|_| {
864			self.services
865				.federation
866				.get_pdu_into(&event_id, Some(room_version))
867		})
868		.inspect_err(unreadable_summary_event(room_id, &event_id))
869		.ok()
870		.await
871}
872
873/// Returns the authorization and event-format rules for a room.
874///
875/// The rules are selected from the room version declared by its create event.
876#[implement(Service)]
877#[inline]
878pub async fn get_room_version_rules(&self, room_id: &RoomId) -> Result<RoomVersionRules> {
879	self.get_room_version(room_id)
880		.await
881		.and_then_ref(room_version::rules)
882}
883
884#[implement(Service)]
885#[tracing::instrument(
886	level = "debug"
887	skip(self),
888	ret(level = "trace"),
889)]
890/// Returns the room version declared by the room's create event.
891///
892/// Only the event's content is decoded, so a create event stored without its
893/// room ID still yields the version. An unreadable accepted event falls back
894/// to outlier storage. Transient storage errors are preserved when neither
895/// copy can be read.
896pub async fn get_room_version(&self, room_id: &RoomId) -> Result<RoomVersionId> {
897	self.services
898		.state_accessor
899		.room_state_get_id(room_id, &StateEventType::RoomCreate, "")
900		.and_then(async |create_id| {
901			let outlier = async |accepted: Error| {
902				self.services
903					.timeline
904					.get_outlier(&create_id)
905					.map_err(|outlier| match accepted {
906						| error if error.is_transient_io() => error,
907						| _ => outlier,
908					})
909					.await
910			};
911
912			self.services
913				.timeline
914				.get_non_outlier(&create_id)
915				.or_else(outlier)
916				.await
917		})
918		.map_ok(|create: CreateEvent| create.content.room_version)
919		.map_err(|error| match error {
920			| Error::Io(_) if !error.is_not_found() => error,
921			| error => err!(Request(NotFound("No create event found: {error:?}"))),
922		})
923		.await
924}
925
926/// Returns the room version as [`Service::get_room_version`] does, resolving the
927/// room's state and the create event's timeline mapping untrusted.
928///
929/// Damage from the room's state pointer to the create event's timeline mapping is
930/// `Mapped::Damaged` where that function panics, fails or reads a prefix, and the
931/// state is rebuilt from storage alone. The accepted copy of the create event is
932/// read before the outlier, as there. Unlike that function, only a read finding
933/// no row or one that does not decode reports no create event, so any other
934/// failure, a database pool failure included, is returned as itself, the accepted
935/// copy's kept over the outlier's.
936#[implement(Service)]
937#[tracing::instrument(level = "debug", skip(self))]
938pub(crate) async fn room_version_checked(
939	&self,
940	room_id: &RoomId,
941) -> Result<Mapped<RoomVersionId>> {
942	self.services
943		.state_accessor
944		.room_state_get_id_checked(room_id, &StateEventType::RoomCreate, "")
945		.and_then(async |create_id| match create_id {
946			| Mapped::Damaged => Ok(Mapped::Damaged),
947			| Mapped::Event(create_id) =>
948				self.services
949					.timeline
950					.get_checked_keeping(&create_id, |error| !version_absent(error))
951					.await,
952		})
953		.map_ok(|create: Mapped<CreateEvent>| create.map(|create| create.content.room_version))
954		.map_err(|error| match version_absent(&error) {
955			| true => err!(Request(NotFound("No create event found: {error:?}"))),
956			| false => error,
957		})
958		.await
959}
960
961/// Whether a failed read on the way to a room's version leaves a check with no
962/// version rather than with that failure.
963///
964/// Only a missing record or a row that does not decode does. Every other error,
965/// a storage fault or a database pool failure included, is the read's own.
966pub(crate) fn version_absent(error: &Error) -> bool { error.is_missing() || undecodable(error) }
967
968#[implement(Service)]
969#[tracing::instrument(
970	level = "debug"
971	skip(self),
972	ret(level = "trace"),
973)]
974/// Returns the short hash of a room's current state snapshot.
975///
976/// The lookup reads only the current room-to-state mapping and does not
977/// reconstruct the snapshot.
978pub async fn get_room_shortstatehash(&self, room_id: &RoomId) -> Result<ShortStateHash> {
979	self.db
980		.roomid_shortstatehash
981		.get(room_id)
982		.await
983		.deserialized()
984}
985
986/// Returns the state hash recorded for an event.
987///
988/// The event ID is first resolved to its short event ID before the snapshot
989/// association is read.
990#[implement(Service)]
991pub async fn pdu_shortstatehash(&self, event_id: &EventId) -> Result<ShortStateHash> {
992	self.services
993		.short
994		.get_shorteventid(event_id)
995		.and_then(|shorteventid| self.get_shortstatehash(shorteventid))
996		.await
997}
998
999#[implement(Service)]
1000#[tracing::instrument(
1001	level = "debug"
1002	skip(self),
1003	ret(level = "trace"),
1004)]
1005/// Returns the state hash recorded for a short event ID.
1006///
1007/// This is the direct lookup used after an event ID has already been shortened.
1008pub async fn get_shortstatehash(&self, shorteventid: ShortEventId) -> Result<ShortStateHash> {
1009	const BUFSIZE: usize = size_of::<ShortEventId>();
1010
1011	self.db
1012		.shorteventid_shortstatehash
1013		.aqry::<BUFSIZE, _>(&shorteventid)
1014		.await
1015		.deserialized()
1016}
1017
1018/// Deletes a room's current state-hash mapping.
1019///
1020/// The supplied guard proves exclusive access to the room state mutation path;
1021/// compressed snapshots and event associations remain stored.
1022#[implement(Service)]
1023pub(super) fn delete_room_shortstatehash(
1024	&self,
1025	room_id: &RoomId,
1026	_mutex_lock: &Guard<OwnedRoomId, ()>,
1027) -> Result {
1028	self.db.roomid_shortstatehash.remove(room_id);
1029
1030	Ok(())
1031}
1032
1033/// Collapses a room to the resolvable forward extremity latest in stream order.
1034///
1035/// Rooms with at most one leaf, or with no leaf that resolves to a timeline
1036/// count, are left unchanged. The return value is the number of leaves removed.
1037#[implement(Service)]
1038#[tracing::instrument(
1039	level = "debug"
1040	skip_all,
1041	fields(%room_id),
1042)]
1043pub async fn collapse_forward_extremities(
1044	&self,
1045	room_id: &RoomId,
1046	state_lock: &RoomMutexGuard,
1047) -> usize {
1048	let extremities: ForwardExtremities = self
1049		.get_forward_extremities(room_id)
1050		.map(ToOwned::to_owned)
1051		.collect()
1052		.await;
1053
1054	if extremities.len() <= 1 {
1055		return 0;
1056	}
1057
1058	let survivor = join_all(extremities.iter().map(async |event_id| {
1059		self.services
1060			.timeline
1061			.get_pdu_count(event_id)
1062			.await
1063			.ok()
1064			.map(|count| (count, event_id))
1065	}))
1066	.await
1067	.into_iter()
1068	.flatten()
1069	.max_by_key(|(count, _)| *count)
1070	.map(|(_, event_id)| event_id);
1071
1072	let Some(survivor) = survivor else {
1073		return 0;
1074	};
1075
1076	self.set_forward_extremities(room_id, once(&**survivor), state_lock)
1077		.await;
1078
1079	extremities.len().saturating_sub(1)
1080}
1081
1082#[implement(Service)]
1083#[tracing::instrument(
1084	level = "trace"
1085	skip(self),
1086)]
1087/// Streams the event IDs currently stored as a room's forward extremities.
1088///
1089/// Invalid rows and cursor errors are omitted. Returned references borrow the
1090/// database cursor and must be owned before they are retained across another
1091/// poll.
1092pub fn get_forward_extremities<'a>(
1093	&'a self,
1094	room_id: &'a RoomId,
1095) -> impl Stream<Item = &EventId> + Send + '_ {
1096	let prefix = (room_id, Interfix);
1097
1098	self.db
1099		.roomid_pduleaves
1100		.keys_prefix(&prefix)
1101		.map_ok(|(_, event_id): (Ignore, &EventId)| event_id)
1102		.ignore_err()
1103}
1104
1105#[implement(Service)]
1106#[tracing::instrument(
1107	level = "debug"
1108	skip_all,
1109	fields(%room_id),
1110)]
1111/// Replaces all stored forward extremities for a room.
1112///
1113/// Deletions and insertions commit in one write batch while the caller holds
1114/// the state guard. Errors encountered while scanning old rows are ignored.
1115pub async fn set_forward_extremities<'a, I>(
1116	&'a self,
1117	room_id: &'a RoomId,
1118	event_ids: I,
1119	_state_lock: &'a RoomMutexGuard,
1120) where
1121	I: Iterator<Item = &'a EventId> + Send + 'a,
1122{
1123	let prefix = (room_id, Interfix);
1124	let leaves = &self.db.roomid_pduleaves;
1125	let txn = leaves
1126		.keys_prefix_raw(&prefix)
1127		.ignore_err()
1128		.ready_fold(self.services.db.txn(), |mut txn, key| {
1129			txn.del_raw(leaves, key);
1130			txn
1131		})
1132		.await;
1133
1134	event_ids
1135		.fold(txn, |mut txn, event_id| {
1136			txn.put_raw(leaves, (room_id, event_id), event_id);
1137			txn
1138		})
1139		.execute();
1140}
1141
1142/// Deletes every stored forward extremity for a room.
1143///
1144/// Cursor errors are ignored, so this best-effort cleanup always returns
1145/// success after removing every row it can read.
1146#[implement(Service)]
1147pub(super) async fn delete_all_rooms_forward_extremities(&self, room_id: &RoomId) -> Result {
1148	let prefix = (room_id, Interfix);
1149
1150	self.db
1151		.roomid_pduleaves
1152		.keys_prefix_raw(&prefix)
1153		.ignore_err()
1154		.ready_for_each(|key| {
1155			trace!("Removing key: {key:?}");
1156			self.db.roomid_pduleaves.remove(key);
1157		})
1158		.await;
1159
1160	Ok(())
1161}