Skip to main content

tuwunel_service/rooms/timeline/
mod.rs

1//! Stores accepted room events, outliers, and their timeline indexes.
2//!
3//! The service maps event IDs to per-room stream positions, presents events to
4//! users, and coordinates append, backfill, purge, and redaction operations.
5//! Timeline insertion is serialized by the innermost per-room lock.
6
7mod append;
8mod backfill;
9mod build;
10mod checked;
11mod create;
12mod pdus;
13mod purge;
14mod redact;
15
16#[cfg(test)]
17mod tests;
18
19use std::{fmt::Write, sync::Arc};
20
21use async_trait::async_trait;
22use futures::{
23	FutureExt, StreamExt, TryFutureExt, TryStreamExt,
24	future::{Either, select, select_ok, try_join},
25	pin_mut,
26};
27use ruma::{
28	CanonicalJsonObject, EventId, MilliSecondsSinceUnixEpoch, OwnedEventId, OwnedRoomId, RoomId,
29	UserId, api::Direction, events::room::encrypted::Relation, signatures::Verified,
30};
31use serde::Deserialize;
32use tuwunel_core::{
33	Err, Error, Result, at, err, implement,
34	utils::{
35		MutexMap, MutexMapGuard,
36		future::TryExtExt,
37		result::{LogErr, NotFound},
38		stream::{IterStream, TryReadyExt},
39	},
40	warn,
41};
42use tuwunel_database::{Database, Deserialized, Json, Map, Txn};
43/// Re-exports the typed and raw persistent timeline identifiers.
44///
45/// Both forms encode a room-local stream position suitable for database keys.
46pub use tuwunel_matrix::pdu::{PduId, RawPduId};
47use tuwunel_matrix::{
48	ShortEventId,
49	pdu::{PduCount, PduEvent},
50	room::state::resolution::FetchEvent,
51};
52
53pub use self::build::Collision;
54/// Re-exports the standard timeline item and count-key transformation.
55///
56/// Timeline consumers use these alongside the service's directional streams.
57pub use self::pdus::{PdusIterItem, bias_count};
58pub(crate) use self::{
59	append::Incoming,
60	checked::{Mapped, Position},
61	redact::Restoration,
62};
63use crate::rooms::{
64	short::{ShortRoomId, ShortStateHash},
65	threads::RedactedRoot,
66};
67
68/// Provides persistent event lookup, insertion, and room timeline traversal.
69///
70/// Accepted events and outliers occupy separate maps while event IDs point to
71/// accepted timeline positions. A per-room insertion lock serializes the final
72/// mutation stage after federation and state work.
73pub struct Service {
74	services: Arc<crate::services::OnceServices>,
75	db: Data,
76	/// Serializes timeline insertion as the leaf per-room operation.
77	///
78	/// Acquire it after any federation or state mutex held for the same room.
79	/// Never acquire either outer mutex while holding this guard.
80	pub mutex_insert: RoomMutexMap,
81}
82
83struct Data {
84	eventid_outlierpdu: Arc<Map>,
85	eventid_pduid: Arc<Map>,
86	pduid_pdu: Arc<Map>,
87	roomid_tscount_pducount: Arc<Map>,
88	db: Arc<Database>,
89}
90
91/// Extracts the relation carried by event content.
92///
93/// Shared by timeline appends and thread summary maintenance.
94#[derive(Deserialize)]
95pub(crate) struct ExtractRelatesTo {
96	#[serde(rename = "m.relates_to")]
97	/// The event's typed relation.
98	pub(crate) relates_to: Relation,
99}
100
101#[derive(Clone, Debug, Deserialize)]
102struct ExtractEventId {
103	event_id: OwnedEventId,
104}
105#[derive(Clone, Debug, Deserialize)]
106struct ExtractRelatesToEventId {
107	#[serde(rename = "m.relates_to")]
108	relates_to: ExtractEventId,
109}
110
111#[derive(Deserialize)]
112struct ExtractBody {
113	body: Option<String>,
114}
115
116type RoomMutexMap = MutexMap<OwnedRoomId, ()>;
117/// Guard proving exclusive access to a room's timeline insertion path.
118///
119/// Acquire it after any federation or state guard held for the same room, and
120/// never acquire either outer guard while retaining it.
121pub type RoomMutexGuard = MutexMapGuard<OwnedRoomId, ()>;
122
123#[async_trait]
124impl crate::Service for Service {
125	fn build(args: &crate::Args<'_>) -> Result<Arc<Self>> {
126		Ok(Arc::new(Self {
127			services: args.services.clone(),
128			db: Data {
129				eventid_outlierpdu: args.db["eventid_outlierpdu"].clone(),
130				eventid_pduid: args.db["eventid_pduid"].clone(),
131				pduid_pdu: args.db["pduid_pdu"].clone(),
132				roomid_tscount_pducount: args.db["roomid_tscount_pducount"].clone(),
133				db: args.db.clone(),
134			},
135			mutex_insert: RoomMutexMap::new(),
136		}))
137	}
138
139	async fn memory_usage(&self, out: &mut (dyn Write + Send)) -> Result {
140		let mutex_insert = self.mutex_insert.len();
141		writeln!(out, "- insert_mutex: {mutex_insert}")?;
142
143		Ok(())
144	}
145
146	fn name(&self) -> &str { crate::service::make_name(std::module_path!()) }
147}
148
149/// Replaces the stored JSON of an accepted PDU without changing its ID.
150///
151/// A definite missing-row result is returned as `NotFound`; otherwise the
152/// accepted timeline row is overwritten in place.
153#[implement(Service)]
154#[tracing::instrument(skip(self), level = "debug")]
155pub async fn replace_pdu(&self, pdu_id: &RawPduId, pdu_json: &CanonicalJsonObject) -> Result {
156	self.require_pdu(pdu_id).await?;
157
158	self.db.pduid_pdu.raw_put(pdu_id, Json(pdu_json));
159
160	Ok(())
161}
162
163/// Replaces a redacted event and its optional thread root in one batch.
164///
165/// The caller retains the room guard through this write. The root's thread
166/// index changes are part of the same batch.
167#[implement(Service)]
168#[tracing::instrument(skip(self, pdu, root), level = "debug")]
169pub(super) async fn replace_redacted_pdu(
170	&self,
171	pdu_id: &RawPduId,
172	pdu: &CanonicalJsonObject,
173	root: Option<RedactedRoot>,
174) -> Result {
175	self.require_pdu(pdu_id).await?;
176	self.redaction_txn(pdu_id, pdu, root.as_ref())
177		.execute();
178
179	Ok(())
180}
181
182/// Stages a redacted event after its thread root.
183///
184/// The redacted row comes last so it wins when a reply names itself as its root.
185#[implement(Service)]
186fn redaction_txn(
187	&self,
188	pdu_id: &RawPduId,
189	pdu: &CanonicalJsonObject,
190	root: Option<&RedactedRoot>,
191) -> Txn {
192	let mut txn = self.db.db.txn();
193
194	if let Some(root) = root {
195		self.services
196			.threads
197			.stage_redacted_root(&mut txn, root);
198	}
199
200	self.stage_replace_pdu(&mut txn, pdu_id, pdu);
201	txn
202}
203
204#[implement(Service)]
205#[tracing::instrument(skip(self), level = "debug")]
206async fn require_pdu(&self, pdu_id: &RawPduId) -> Result {
207	if self.db.pduid_pdu.get(pdu_id).await.is_not_found() {
208		return Err!(Request(NotFound("PDU does not exist.")));
209	}
210
211	Ok(())
212}
213
214/// Stage replacement of a PDU already loaded under its room's guard.
215///
216/// The caller retains the guard until the transaction commits.
217#[implement(Service)]
218pub(super) fn stage_replace_pdu(
219	&self,
220	txn: &mut Txn,
221	pdu_id: &RawPduId,
222	pdu_json: &CanonicalJsonObject,
223) {
224	txn.raw_put(&self.db.pduid_pdu, pdu_id, Json(pdu_json));
225}
226
227/// Stores a verified federation event as an outlier unless this server's copy
228/// takes precedence.
229///
230/// An accepted event keeps its copy, and so does any stored event whose new
231/// copy had to be redacted. A copy whose content matches its hash replaces an
232/// outlier, such as one stored from knock state without a hash check.
233#[implement(Service)]
234#[tracing::instrument(skip(self, pdu), level = "debug")]
235pub async fn add_verified_outlier(
236	&self,
237	event_id: &EventId,
238	pdu: &CanonicalJsonObject,
239	verified: &Verified,
240) {
241	let kept = match verified {
242		| Verified::All =>
243			self.non_outlier_pdu_exists(event_id)
244				.is_ok()
245				.await,
246		| Verified::Signatures => self.pdu_exists(event_id).await,
247	};
248
249	if !kept {
250		self.add_pdu_outlier(event_id, pdu);
251	}
252}
253
254/// Stores an event as an outlier outside the accepted room timeline.
255///
256/// The event is keyed directly by event ID and no accepted-timeline mapping or
257/// stream position is created.
258#[implement(Service)]
259#[tracing::instrument(skip(self, pdu), level = "debug")]
260pub fn add_pdu_outlier(&self, event_id: &EventId, pdu: &CanonicalJsonObject) {
261	self.db
262		.eventid_outlierpdu
263		.raw_put(event_id, Json(pdu));
264}
265
266/// Returns the earliest accepted PDU in a room, backfilled ones included.
267///
268/// Unknown or empty rooms report the underlying stream's not-found result.
269#[implement(Service)]
270#[tracing::instrument(skip(self), level = "debug")]
271pub async fn first_pdu_in_room(&self, room_id: &RoomId) -> Result<PduEvent> {
272	self.first_item_in_room(room_id).await.map(at!(1))
273}
274
275/// Returns the earliest PDU in a room's normal timeline.
276///
277/// Backfilled PDUs sort before it but are skipped, because backfill admits
278/// events with whatever timestamp their origin claims. Rooms without a normal
279/// PDU report not found.
280#[implement(Service)]
281#[tracing::instrument(skip(self), level = "debug")]
282pub async fn first_normal_pdu_in_room(&self, room_id: &RoomId) -> Result<PduEvent> {
283	self.first_item_after(room_id, Some(PduCount::Normal(0)))
284		.map_ok(at!(1))
285		.await
286}
287
288/// Returns the latest accepted PDU in a room.
289///
290/// Presentation removes sender-only transaction metadata because no requesting
291/// user is supplied.
292#[implement(Service)]
293#[tracing::instrument(skip(self), level = "debug")]
294#[inline]
295pub async fn latest_pdu_in_room(&self, room_id: &RoomId) -> Result<PduEvent> {
296	self.latest_item_in_room(None, room_id).await
297}
298
299/// Returns the earliest accepted PDU and its room-local stream count.
300///
301/// The forward room stream provides the first available item after applying
302/// ordinary presentation transformations.
303#[implement(Service)]
304#[tracing::instrument(skip(self), level = "debug")]
305pub async fn first_item_in_room(&self, room_id: &RoomId) -> Result<(PduCount, PduEvent)> {
306	self.first_item_after(room_id, None).await
307}
308
309/// Returns the first accepted PDU after an exclusive `from` count.
310///
311/// Without a count the room's backfilled PDUs come first.
312#[implement(Service)]
313async fn first_item_after(
314	&self,
315	room_id: &RoomId,
316	from: Option<PduCount>,
317) -> Result<(PduCount, PduEvent)> {
318	let pdus = self.pdus(None, room_id, from);
319
320	pin_mut!(pdus);
321	pdus.try_next()
322		.await?
323		.ok_or_else(|| err!(Request(NotFound("No PDU found in room"))))
324}
325
326/// Returns the latest accepted PDU in a room.
327///
328/// `sender_user` controls presentation of sender-only transaction metadata; it
329/// does not filter events by sender.
330#[implement(Service)]
331#[tracing::instrument(skip(self), level = "debug")]
332pub async fn latest_item_in_room(
333	&self,
334	sender_user: Option<&UserId>,
335	room_id: &RoomId,
336) -> Result<PduEvent> {
337	let pdus_rev = self.pdus_rev(sender_user, room_id, None);
338
339	pin_mut!(pdus_rev);
340	pdus_rev
341		.try_next()
342		.await?
343		.map(at!(1))
344		.ok_or_else(|| err!(Request(NotFound("No PDU's found in room"))))
345}
346
347/// Returns the state snapshot at the room event directly before a count.
348///
349/// The `before` boundary is exclusive and need not identify an existing event
350/// or even belong to the room.
351#[implement(Service)]
352#[tracing::instrument(skip(self), level = "debug")]
353pub async fn prev_shortstatehash(
354	&self,
355	room_id: &RoomId,
356	before: PduCount,
357) -> Result<ShortStateHash> {
358	let shortroomid: ShortRoomId = self
359		.services
360		.short
361		.get_shortroomid(room_id)
362		.await
363		.map_err(|e| err!(Request(NotFound("Room {room_id:?} not found: {e:?}"))))?;
364
365	let before = PduId { shortroomid, count: before };
366
367	let prev = PduId {
368		shortroomid,
369		count: self.prev_timeline_count(&before).await?,
370	};
371
372	let shorteventid = self.get_shorteventid_from_pdu_id(&prev).await?;
373
374	self.services
375		.state
376		.get_shortstatehash(shorteventid)
377		.await
378}
379
380/// Returns the state snapshot at the room event directly after a count.
381///
382/// The `after` boundary is exclusive and need not identify an existing event
383/// or even belong to the room.
384#[implement(Service)]
385#[tracing::instrument(skip(self), level = "debug")]
386pub async fn next_shortstatehash(
387	&self,
388	room_id: &RoomId,
389	after: PduCount,
390) -> Result<ShortStateHash> {
391	let shortroomid = self.shortroomid(room_id).await?;
392	let after = PduId { shortroomid, count: after };
393
394	let next = PduId {
395		shortroomid,
396		count: self.next_timeline_count(&after).await?,
397	};
398
399	let shorteventid = self.get_shorteventid_from_pdu_id(&next).await?;
400
401	self.services
402		.state
403		.get_shortstatehash(shorteventid)
404		.await
405}
406
407/// Resolves a room's short ID.
408///
409/// An unknown room is reported as not found rather than as a storage error.
410#[implement(Service)]
411async fn shortroomid(&self, room_id: &RoomId) -> Result<ShortRoomId> {
412	self.services
413		.short
414		.get_shortroomid(room_id)
415		.map_err(|e| err!(Request(NotFound("Room {room_id:?} not found: {e:?}"))))
416		.await
417}
418
419/// Returns the snapshot preceding the first room event after a count.
420///
421/// An event at the count is treated as already received, because a client's
422/// sync position is often the count of the newest event it received, and need
423/// not belong to this room. Current state stands in when no event follows, and
424/// a count before the room's first recorded snapshot is not found. A remote
425/// event's snapshot precedes it in the event graph rather than in this
426/// timeline, so the boundary suits a client's position, not a point in the
427/// room's own history.
428#[implement(Service)]
429#[tracing::instrument(skip(self), level = "debug")]
430pub async fn shortstatehash_after(
431	&self,
432	room_id: &RoomId,
433	count: PduCount,
434) -> Result<ShortStateHash> {
435	let shortroomid = self.shortroomid(room_id).await?;
436	let after = PduId { shortroomid, count };
437	let count = match self.next_timeline_count(&after).await {
438		| Ok(count) => count,
439		| Err(e) if !e.is_not_found() => return Err(e),
440		| Err(_) => {
441			return self
442				.services
443				.state
444				.get_room_shortstatehash(room_id)
445				.await;
446		},
447	};
448
449	let next = PduId { shortroomid, count };
450	let shorteventid = self.get_shorteventid_from_pdu_id(&next).await?;
451
452	self.services
453		.state
454		.get_shortstatehash(shorteventid)
455		.await
456}
457
458/// Returns the state snapshot recorded at a room timeline count.
459///
460/// The count is resolved through the room's accepted timeline row and then its
461/// event-to-state association.
462#[implement(Service)]
463#[tracing::instrument(skip(self), level = "debug")]
464pub async fn get_shortstatehash(
465	&self,
466	room_id: &RoomId,
467	count: PduCount,
468) -> Result<ShortStateHash> {
469	let shortroomid: ShortRoomId = self
470		.services
471		.short
472		.get_shortroomid(room_id)
473		.await
474		.map_err(|e| err!(Request(NotFound("Room {room_id:?} not found: {e:?}"))))?;
475
476	let pdu_id = PduId { shortroomid, count };
477
478	let shorteventid = self.get_shorteventid_from_pdu_id(&pdu_id).await?;
479
480	self.services
481		.state
482		.get_shortstatehash(shorteventid)
483		.await
484}
485
486/// Returns the room timeline count directly before an encoded PDU ID.
487///
488/// The boundary is exclusive and need not identify an existing row. Its room
489/// component selects the timeline prefix to scan.
490#[implement(Service)]
491#[tracing::instrument(skip(self), level = "debug")]
492pub async fn prev_timeline_count(&self, before: &PduId) -> Result<PduCount> {
493	let before = Self::pdu_count_to_id(before.shortroomid, before.count, Direction::Backward);
494
495	let pdu_ids = self
496		.db
497		.pduid_pdu
498		.rev_keys_raw_from(&before)
499		.ready_try_take_while(|pdu_id: &RawPduId| Ok(pdu_id.is_room_eq(before)))
500		.ready_and_then(|pdu_id: RawPduId| Ok(pdu_id.pdu_count()));
501
502	pin_mut!(pdu_ids);
503	pdu_ids
504		.try_next()
505		.await
506		.log_err()?
507		.ok_or_else(|| err!(Request(NotFound("No earlier PDU's found in room"))))
508}
509
510/// Returns the room timeline count directly after an encoded PDU ID.
511///
512/// The boundary is exclusive and need not identify an existing row. Its room
513/// component selects the timeline prefix to scan.
514#[implement(Service)]
515#[tracing::instrument(skip(self), level = "debug")]
516pub async fn next_timeline_count(&self, after: &PduId) -> Result<PduCount> {
517	let after = Self::pdu_count_to_id(after.shortroomid, after.count, Direction::Forward);
518
519	let pdu_ids = self
520		.db
521		.pduid_pdu
522		.keys_raw_from(&after)
523		.ready_try_take_while(|pdu_id: &RawPduId| Ok(pdu_id.is_room_eq(after)))
524		.ready_and_then(|pdu_id: RawPduId| Ok(pdu_id.pdu_count()));
525
526	pin_mut!(pdu_ids);
527	pdu_ids
528		.try_next()
529		.await
530		.log_err()?
531		.ok_or(err!(Request(NotFound("No more PDU's found in room"))))
532}
533
534/// Returns the latest normal timeline count at or below an optional bound.
535///
536/// Backfilled counts are not returned. When no normal event qualifies, the
537/// sentinel `PduCount::max()` is returned instead of a not-found error;
538/// `sender_user` affects presentation only.
539#[implement(Service)]
540#[tracing::instrument(skip(self), level = "debug")]
541pub async fn last_timeline_count(
542	&self,
543	sender_user: Option<&UserId>,
544	room_id: &RoomId,
545	upper_bound: Option<PduCount>,
546) -> Result<PduCount> {
547	let upper_bound = upper_bound.unwrap_or_else(PduCount::max);
548	let pdus_rev = self.pdus_rev(sender_user, room_id, None);
549
550	pin_mut!(pdus_rev);
551	let last_count = pdus_rev
552		.ready_try_skip_while(|&(pducount, _)| Ok(pducount > upper_bound))
553		.try_next()
554		.await?
555		.map(at!(0))
556		.filter(|&count| matches!(count, PduCount::Normal(_)))
557		.unwrap_or_else(PduCount::max);
558
559	Ok(last_count)
560}
561
562/// Returns the indexed event ID nearest a timestamp in one direction.
563///
564/// Forward lookup selects the first event at or after the timestamp; backward
565/// lookup selects the first event at or before it. The stored event timestamp
566/// is returned with the ID.
567#[implement(Service)]
568pub async fn get_event_id_near_ts(
569	&self,
570	room_id: &RoomId,
571	ts: MilliSecondsSinceUnixEpoch,
572	dir: Direction,
573) -> Result<(MilliSecondsSinceUnixEpoch, OwnedEventId)> {
574	self.get_pdu_id_near_ts(room_id, ts, dir)
575		.and_then(async |(ts, pdu_id)| {
576			self.get_event_id_from_pdu_id(&pdu_id)
577				.map_ok(|event_id| (ts, event_id))
578				.await
579		})
580		.await
581}
582
583/// Returns the indexed PDU ID nearest a timestamp in one direction.
584///
585/// Forward lookup selects the first event at or after the timestamp; backward
586/// lookup selects the first event at or before it. A room with no qualifying
587/// event returns `NotFound`.
588#[implement(Service)]
589pub async fn get_pdu_id_near_ts(
590	&self,
591	room_id: &RoomId,
592	ts: MilliSecondsSinceUnixEpoch,
593	dir: Direction,
594) -> Result<(MilliSecondsSinceUnixEpoch, PduId)> {
595	let pdu_ids = self.pdu_ids_near_ts(room_id, ts, dir);
596
597	pin_mut!(pdu_ids);
598	pdu_ids
599		.try_next()
600		.await?
601		.ok_or_else(|| err!(Request(NotFound("No event found near this timestamp."))))
602}
603
604/// Returns the accepted PDU nearest a timestamp in one direction.
605///
606/// The result contains the selected room-local count and decoded PDU. The
607/// current `_user_id` parameter has no effect and no presentation or visibility
608/// filtering is applied.
609#[implement(Service)]
610pub async fn get_pdu_near_ts(
611	&self,
612	_user_id: Option<&UserId>,
613	room_id: &RoomId,
614	ts: MilliSecondsSinceUnixEpoch,
615	dir: Direction,
616) -> Result<PdusIterItem> {
617	let pdus = self
618		.pdu_ids_near_ts(room_id, ts, dir)
619		.map_ok(|(ts, pdu_id)| (ts, pdu_id.into()))
620		.and_then(async |(_, pdu_id): (_, RawPduId)| {
621			self.get_pdu_from_id(&pdu_id)
622				.map_ok(|pdu| (pdu_id.pdu_count(), pdu))
623				.await
624		});
625
626	pin_mut!(pdus);
627	pdus.try_next()
628		.await?
629		.ok_or_else(|| err!(Request(NotFound("No event found near this timestamp."))))
630}
631
632#[implement(Service)]
633async fn count_to_id(
634	&self,
635	room_id: &RoomId,
636	count: PduCount,
637	dir: Direction,
638) -> Result<RawPduId> {
639	let shortroomid: ShortRoomId = self
640		.services
641		.short
642		.get_shortroomid(room_id)
643		.await
644		.map_err(|e| err!(Request(NotFound("Room {room_id:?} not found: {e:?}"))))?;
645
646	Ok(Self::pdu_count_to_id(shortroomid, count, dir))
647}
648
649#[implement(Service)]
650fn pdu_count_to_id(shortroomid: ShortRoomId, count: PduCount, dir: Direction) -> RawPduId {
651	// In raw key order, backfilled zero precedes every stored row. It has no base
652	// event, so retaining it keeps the `from` bound exclusive.
653	let count = match (count, dir) {
654		| (PduCount::Backfilled(0), Direction::Forward) => count,
655		| _ => count.saturating_inc(dir),
656	};
657
658	let pdu_id = PduId { shortroomid, count };
659
660	pdu_id.into()
661}
662
663/// Returns a decoded PDU resolved from a short event ID.
664///
665/// The short ID is expanded to an event ID before accepted and outlier storage
666/// are queried through [`Service::get_pdu`].
667#[implement(Service)]
668pub async fn get_pdu_from_shorteventid(&self, shorteventid: ShortEventId) -> Result<PduEvent> {
669	let event_id: OwnedEventId = self
670		.services
671		.short
672		.get_eventid_from_short(shorteventid)
673		.await?;
674
675	self.get_pdu(&event_id).await
676}
677
678/// Returns a decoded PDU from accepted or outlier storage.
679///
680/// Both lookups are polled concurrently, so if duplicate rows exist the first
681/// successful lookup determines the returned value.
682#[implement(Service)]
683pub async fn get_pdu(&self, event_id: &EventId) -> Result<PduEvent> { self.get(event_id).await }
684
685/// Returns a decoded PDU from outlier storage.
686///
687/// Accepted timeline storage is not consulted, and storage or decoding errors
688/// propagate to the caller.
689#[implement(Service)]
690pub async fn get_outlier_pdu(&self, event_id: &EventId) -> Result<PduEvent> {
691	self.get_outlier(event_id).await
692}
693
694/// Returns a PDU from the accepted timeline.
695///
696/// Looks up the accepted record only, without consulting outliers. Storage and
697/// decoding errors propagate to the caller.
698#[implement(Service)]
699pub async fn get_non_outlier_pdu(&self, event_id: &EventId) -> Result<PduEvent> {
700	self.get_non_outlier(event_id).await
701}
702
703/// Returns the accepted PDU at a room's timeline count.
704///
705/// A count holding no accepted event in the room is not found.
706#[implement(Service)]
707#[tracing::instrument(skip(self), level = "trace")]
708pub async fn get_pdu_at(&self, room_id: &RoomId, count: PduCount) -> Result<PduEvent> {
709	let shortroomid = self.shortroomid(room_id).await?;
710	let pdu_id: RawPduId = PduId { shortroomid, count }.into();
711
712	self.get_pdu_from_id(&pdu_id).await
713}
714
715/// Returns a decoded PDU by its accepted timeline ID.
716///
717/// The accepted row is read directly without consulting the event-ID mapping
718/// or outlier storage.
719#[implement(Service)]
720pub async fn get_pdu_from_id(&self, pdu_id: &RawPduId) -> Result<PduEvent> {
721	self.get_from_id(pdu_id).await
722}
723
724/// Returns canonical PDU JSON from accepted or outlier storage.
725///
726/// Both lookups are polled concurrently, so if duplicate rows exist the first
727/// successful lookup determines the returned value.
728#[implement(Service)]
729pub async fn get_pdu_json(&self, event_id: &EventId) -> Result<CanonicalJsonObject> {
730	self.get(event_id).await
731}
732
733/// Returns canonical PDU JSON from outlier storage.
734///
735/// Accepted timeline storage is not consulted, and storage or decoding errors
736/// propagate to the caller.
737#[implement(Service)]
738pub async fn get_outlier_pdu_json(&self, event_id: &EventId) -> Result<CanonicalJsonObject> {
739	self.get_outlier(event_id).await
740}
741
742/// Returns the JSON of a PDU from the accepted timeline.
743///
744/// Looks up the accepted record only, without consulting outliers. Storage and
745/// decoding errors propagate to the caller.
746#[implement(Service)]
747pub async fn get_non_outlier_pdu_json(&self, event_id: &EventId) -> Result<CanonicalJsonObject> {
748	self.get_non_outlier(event_id).await
749}
750
751/// Returns canonical PDU JSON by its accepted timeline ID.
752///
753/// The accepted row is read directly without consulting the event-ID mapping
754/// or outlier storage.
755#[implement(Service)]
756pub async fn get_pdu_json_from_id(&self, pdu_id: &RawPduId) -> Result<CanonicalJsonObject> {
757	self.get_from_id(pdu_id).await
758}
759
760/// Deserializes an event from accepted or outlier storage into `T`.
761///
762/// Both lookups are polled concurrently, so if duplicate rows exist the first
763/// successful lookup determines the returned value. If both fail, a storage or
764/// decoding error takes precedence over a missing record.
765#[implement(Service)]
766#[inline]
767pub async fn get<T>(&self, event_id: &EventId) -> Result<T>
768where
769	T: for<'de> Deserialize<'de>,
770{
771	// Success takes the short-circuiting branch; only two failures are joined.
772	let invert = |result: Result<T>| result.map_or_else(Ok, Err);
773	let accepted = self.get_non_outlier(event_id).map(invert);
774	let outlier = self.get_outlier(event_id).map(invert);
775
776	try_join(accepted, outlier)
777		.map(|result| match result {
778			| Err(value) => Ok(value),
779			| Ok((accepted, outlier)) if accepted.is_missing() => Err(outlier),
780			| Ok((accepted, _)) => Err(accepted),
781		})
782		.await
783}
784
785impl FetchEvent for &Service {
786	async fn get<T>(self, event_id: &EventId) -> Result<T>
787	where
788		T: for<'de> Deserialize<'de> + Send,
789	{
790		Service::get(self, event_id).await
791	}
792
793	async fn exists(self, event_id: &EventId) -> Result<bool> {
794		let non_outlier = self.non_outlier_pdu_exists(event_id);
795		let outlier = self.outlier_pdu_exists(event_id);
796		let classify = |first: Error, second: Result| match second {
797			| Ok(()) => Ok(true),
798			| Err(second) if first.is_not_found() && second.is_not_found() => Ok(false),
799			| Err(second) if first.is_not_found() => Err(second),
800			| Err(_) => Err(first),
801		};
802
803		pin_mut!(non_outlier, outlier);
804		match select(non_outlier, outlier).await {
805			| Either::Left((Ok(()), _)) | Either::Right((Ok(()), _)) => Ok(true),
806			| Either::Left((Err(first), second)) => classify(first, second.await),
807			| Either::Right((Err(first), second)) => classify(first, second.await),
808		}
809	}
810}
811
812/// Deserializes an event from outlier storage into `T`.
813///
814/// Accepted timeline storage is not consulted, and storage or decoding errors
815/// propagate to the caller.
816#[implement(Service)]
817#[inline]
818pub async fn get_outlier<T>(&self, event_id: &EventId) -> Result<T>
819where
820	T: for<'de> Deserialize<'de>,
821{
822	self.db
823		.eventid_outlierpdu
824		.get(event_id)
825		.await
826		.deserialized()
827}
828
829/// Deserializes a PDU from the accepted timeline into `T`.
830///
831/// Resolves the event ID through `eventid_pduid` and reads `pduid_pdu`, without
832/// consulting outliers. Storage and decoding errors propagate to the caller.
833#[implement(Service)]
834#[inline]
835pub async fn get_non_outlier<T>(&self, event_id: &EventId) -> Result<T>
836where
837	T: for<'de> Deserialize<'de>,
838{
839	let pdu_id = self.get_pdu_id(event_id).await?;
840
841	self.get_from_id(&pdu_id).await
842}
843
844/// Deserializes an accepted timeline row into `T` by PDU ID.
845///
846/// The row is read directly without consulting the event-ID mapping or outlier
847/// storage.
848#[implement(Service)]
849#[inline]
850pub async fn get_from_id<T>(&self, pdu_id: &RawPduId) -> Result<T>
851where
852	T: for<'de> Deserialize<'de>,
853{
854	self.db.pduid_pdu.get(pdu_id).await.deserialized()
855}
856
857/// Reports whether an event exists in accepted or outlier storage.
858///
859/// The two existence checks run concurrently, and any lookup errors are
860/// treated as absence.
861#[implement(Service)]
862pub async fn pdu_exists<'a>(&'a self, event_id: &'a EventId) -> bool {
863	let non_outlier = self.non_outlier_pdu_exists(event_id);
864	let outlier = self.outlier_pdu_exists(event_id);
865
866	pin_mut!(non_outlier, outlier);
867	select_ok([non_outlier.left_future(), outlier.right_future()])
868		.await
869		.map(at!(0))
870		.is_ok()
871}
872
873/// Reports whether every event has an accepted timeline row.
874///
875/// The probe stops at the first event without one, and an empty input reports
876/// true; a lookup error counts as absence. The rows are read one at a time, so
877/// callers pass a small set such as one event's references, never a bulk
878/// population.
879#[implement(Service)]
880pub async fn non_outlier_pdus_exist<'a, I>(&self, event_ids: I) -> bool
881where
882	I: Iterator<Item = &'a EventId> + Send,
883{
884	event_ids
885		.stream()
886		.all(|event_id| self.non_outlier_pdu_exists(event_id).is_ok())
887		.await
888}
889
890/// Returns a future that resolves on the next event-to-PDU mapping mutation.
891///
892/// Registration against the event-to-PDU mapping is eager, so the watcher is
893/// installed before the returned future is first awaited. Accepted insertion
894/// is the normal wakeup, but any mutation under the event-ID prefix can resolve
895/// the future.
896#[implement(Service)]
897pub fn watch_event<'a>(&'a self, event_id: &EventId) -> impl Future<Output = ()> + Send + 'a {
898	self.db
899		.eventid_pduid
900		.watch_raw_prefix_once(event_id)
901}
902
903/// Checks whether an event has an accepted timeline row.
904///
905/// The event-to-PDU mapping is resolved first and the target row is then tested
906/// without fetching or decoding the PDU.
907#[implement(Service)]
908pub async fn non_outlier_pdu_exists(&self, event_id: &EventId) -> Result {
909	let pduid = self.get_pdu_id(event_id).await?;
910
911	self.db.pduid_pdu.exists(&pduid).await
912}
913
914/// Checks whether an event has an outlier row.
915///
916/// Accepted timeline storage is not consulted and the PDU is not fetched or
917/// decoded.
918#[implement(Service)]
919#[inline]
920pub async fn outlier_pdu_exists(&self, event_id: &EventId) -> Result {
921	self.db.eventid_outlierpdu.exists(event_id).await
922}
923
924/// Returns the room-local timeline count assigned to an accepted event.
925///
926/// The event ID is resolved through the accepted event-to-PDU mapping.
927#[implement(Service)]
928pub async fn get_pdu_count(&self, event_id: &EventId) -> Result<PduCount> {
929	self.get_pdu_id(event_id)
930		.await
931		.map(RawPduId::pdu_count)
932}
933
934/// Returns the short event ID represented by an accepted PDU ID.
935///
936/// The accepted row supplies the full event ID, which is then resolved through
937/// the short-ID service.
938#[implement(Service)]
939pub async fn get_shorteventid_from_pdu_id(&self, pdu_id: &PduId) -> Result<ShortEventId> {
940	let event_id = self.get_event_id_from_pdu_id(pdu_id).await?;
941
942	self.services
943		.short
944		.get_shorteventid(&event_id)
945		.await
946}
947
948/// Returns the event ID stored at an accepted PDU ID.
949///
950/// The accepted row is decoded as a PDU to recover its event ID.
951#[implement(Service)]
952pub async fn get_event_id_from_pdu_id(&self, pdu_id: &PduId) -> Result<OwnedEventId> {
953	let pdu_id: RawPduId = (*pdu_id).into();
954
955	self.get_pdu_from_id(&pdu_id)
956		.map_ok(|pdu| pdu.event_id)
957		.await
958}
959
960/// Returns the accepted PDU ID associated with a short event ID.
961///
962/// The short ID is first expanded to its full event ID before the timeline
963/// mapping is read.
964#[implement(Service)]
965pub async fn get_pdu_id_from_shorteventid(&self, shorteventid: ShortEventId) -> Result<RawPduId> {
966	let event_id: OwnedEventId = self
967		.services
968		.short
969		.get_eventid_from_short(shorteventid)
970		.await?;
971
972	self.get_pdu_id(&event_id).await
973}
974
975/// Returns the accepted timeline ID associated with an event.
976///
977/// Outlier storage is not consulted because outliers have no room timeline
978/// position.
979#[implement(Service)]
980pub async fn get_pdu_id(&self, event_id: &EventId) -> Result<RawPduId> {
981	self.db
982		.eventid_pduid
983		.get(event_id)
984		.await
985		.map(|handle| RawPduId::from(&*handle))
986}