Skip to main content

tuwunel_service/rooms/read_receipt/
mod.rs

1mod data;
2#[cfg(test)]
3mod tests;
4
5use std::{collections::BTreeMap, sync::Arc};
6
7use futures::{Stream, StreamExt, TryStreamExt};
8use ruma::{
9	EventId, MilliSecondsSinceUnixEpoch, OwnedEventId, OwnedUserId, RoomId, UInt, UserId,
10	api::appservice::event::push_events::v1::EphemeralData,
11	events::{
12		AnySyncEphemeralRoomEvent, SyncEphemeralRoomEvent,
13		receipt::{
14			Receipt, ReceiptEvent, ReceiptEventContent, ReceiptThread, ReceiptType, Receipts,
15		},
16	},
17	serde::Raw,
18};
19use serde_json::value::to_raw_value;
20use tuwunel_core::{
21	Result, debug,
22	debug::INFO_SPAN_LEVEL,
23	err,
24	result::NotFound,
25	smallstr::SmallString,
26	smallvec::SmallVec,
27	utils::{BoolExt, IterStream},
28	warn,
29};
30use tuwunel_matrix::{
31	Event,
32	pdu::{PduCount, PduId, RawPduId},
33};
34
35use self::data::{Data, ReceiptItem};
36
37/// Private read receipts surfaced by `private_read_get`. One legacy
38/// unthreaded row plus zero or more per-thread rows; inline-1 catches the
39/// dominant case (a single unthreaded marker) without a heap alloc.
40pub type PrivateReadEvents = SmallVec<[Raw<AnySyncEphemeralRoomEvent>; 1]>;
41
42/// Stored thread-kind tag: `""` for `Unthreaded`, `"main"` for `Main`, or
43/// the event-id string for `Thread(...)`. v3+ event ids are 44 bytes
44/// including the leading `$`; 48 bytes inline matches the project's
45/// `StateKey` budget and stays inline for every realistic thread root.
46type ThreadKind = SmallString<[u8; 48]>;
47
48/// A private read marker write for one `(room, user, thread)` context.
49///
50/// `count` is the timeline position the marker addresses and `ts` the receipt
51/// timestamp. `announce` opens the sync gate, carrying the marker to the
52/// user's other devices; a marker the server writes on the user's behalf
53/// leaves it closed.
54#[derive(Clone, Copy, Debug)]
55pub struct PrivateRead<'a> {
56	pub room_id: &'a RoomId,
57	pub user_id: &'a UserId,
58	pub count: u64,
59	pub ts: MilliSecondsSinceUnixEpoch,
60	pub thread: &'a ReceiptThread,
61	pub announce: bool,
62}
63
64pub struct Service {
65	services: Arc<crate::services::OnceServices>,
66	db: Data,
67}
68
69impl crate::Service for Service {
70	fn build(args: &crate::Args<'_>) -> Result<Arc<Self>> {
71		Ok(Arc::new(Self {
72			services: args.services.clone(),
73			db: Data::new(args),
74		}))
75	}
76
77	fn name(&self) -> &str { crate::service::make_name(std::module_path!()) }
78}
79
80impl Service {
81	/// Replaces the previous read receipt when the incoming one advances.
82	///
83	/// Returns whether the receipt was stored. A re-posted marker allocates no
84	/// stream position, so appservice and federation delivery are both skipped.
85	#[tracing::instrument(
86		name = "receipt"
87		level = INFO_SPAN_LEVEL,
88		skip_all,
89		fields(
90			%room_id,
91			%user_id,
92			?event.content
93		)
94	)]
95	pub async fn readreceipt_update(
96		&self,
97		user_id: &UserId,
98		room_id: &RoomId,
99		event: &ReceiptEvent,
100	) -> bool {
101		if self
102			.db
103			.readreceipt_update(user_id, room_id, event)
104			.await
105			.is_false()
106		{
107			return false;
108		}
109
110		self.services
111			.sending
112			.send_edu_room_appservices(room_id, |buf| {
113				let edu = EphemeralData::Receipt(ReceiptEvent {
114					content: event.content.clone(),
115					room_id: room_id.to_owned(),
116				});
117
118				Ok(serde_json::to_writer(buf, &edu)?)
119			})
120			.await
121			.expect("edu serialization or flush failed");
122
123		if self.services.globals.user_is_local(user_id) {
124			self.services
125				.sending
126				.flush_room(room_id)
127				.await
128				.expect("room flush failed");
129		}
130
131		true
132	}
133
134	/// Whether a marker at `incoming` supersedes one stored at `current`, by
135	/// the ordering read receipts are gated on.
136	///
137	/// An identical event id never advances, and an id that does not resolve
138	/// to a known PDU on either side counts as an advance.
139	#[tracing::instrument(level = "debug", skip(self), ret(level = "trace"))]
140	pub async fn receipt_advanced(&self, current: Option<&EventId>, incoming: &EventId) -> bool {
141		self.db.receipt_advanced(current, incoming).await
142	}
143
144	/// Gets every stored private read receipt for `(room, user)`. Returns
145	/// one ephemeral event per stored row (legacy unthreaded plus per-thread
146	/// rows). An empty result means no marker is set.
147	#[tracing::instrument(skip(self), level = "debug", name = "get_private")]
148	pub async fn private_read_get(
149		&self,
150		room_id: &RoomId,
151		user_id: &UserId,
152	) -> Result<PrivateReadEvents> {
153		let shortroomid = self
154			.services
155			.short
156			.get_shortroomid(room_id)
157			.await
158			.map_err(|e| {
159				err!(Database(warn!(
160					"Short room ID does not exist in database for {room_id}: {e}"
161				)))
162			})?;
163
164		let legacy = self
165			.private_read_get_count(room_id, user_id)
166			.await
167			.ok()
168			.map(|(count, ts)| (ThreadKind::new(), count, ts));
169
170		let events = legacy
171			.into_iter()
172			.stream()
173			.chain(
174				self.db
175					.private_read_threaded_stream(room_id, user_id),
176			)
177			.filter_map(async |(kind, count, ts)| {
178				self.build_private_read_event(shortroomid, count, ts, user_id, &kind)
179					.await
180			})
181			.collect()
182			.await;
183
184		Ok(events)
185	}
186
187	/// Gets the complete announced private read snapshot for `update` without
188	/// suppressing malformed rows.
189	///
190	/// A snapshot older than the gate predates this durable mirror, so those
191	/// rows fall back to the tolerant active-state read they always published
192	/// rather than withholding the whole room after an upgrade. A newer
193	/// snapshot means a concurrent announce; that fails the bounded room range
194	/// so its cursor remains pinned. A marker naming an event that no longer
195	/// resolves is skipped rather than failing the range, which would
196	/// otherwise repeat on every request and withhold the room indefinitely.
197	#[tracing::instrument(skip(self), level = "debug", name = "get_private_fallible")]
198	pub async fn private_read_get_fallible(
199		&self,
200		room_id: &RoomId,
201		user_id: &UserId,
202		update: u64,
203	) -> Result<PrivateReadEvents> {
204		let snapshot = self
205			.db
206			.private_read_sync_update_fallible(user_id, room_id)
207			.await?;
208
209		if snapshot < update {
210			debug!(%room_id, %user_id, "Serving pre-mirror private read from the active store.");
211			return self.private_read_get(room_id, user_id).await;
212		}
213
214		if snapshot > update {
215			return Err(err!(Database(
216				"Private read snapshot advanced while assembling a bounded sync range."
217			)));
218		}
219
220		let shortroomid = async {
221			self.services
222				.short
223				.get_shortroomid(room_id)
224				.await
225				.map_err(|e| {
226					err!(Database(warn!(
227						"Short room ID does not exist in database for {room_id}: {e}"
228					)))
229				})
230		};
231
232		let shortroomid = shortroomid.await?;
233		let events = self
234			.db
235			.private_read_sync_stream_fallible(room_id, user_id)
236			.try_filter_map(async |(kind, count, ts)| {
237				self.build_private_read_event_skippable(shortroomid, count, ts, user_id, &kind)
238					.await
239			})
240			.try_collect()
241			.await?;
242
243		let confirmed = self
244			.db
245			.private_read_sync_update_fallible(user_id, room_id)
246			.await?;
247
248		if confirmed != update {
249			return Err(err!(Database(
250				"Private read snapshot changed while assembling a bounded sync range."
251			)));
252		}
253
254		Ok(events)
255	}
256
257	/// Builds one announced private read row, skipping a marker whose event
258	/// no longer resolves.
259	///
260	/// The absent case returns `Ok(None)` so the bounded range assembles
261	/// without it. Decode failures and invalid timestamps still fail the
262	/// range as real inconsistencies.
263	async fn build_private_read_event_skippable(
264		&self,
265		shortroomid: u64,
266		count: u64,
267		ts: Option<u64>,
268		user_id: &UserId,
269		thread_kind: &str,
270	) -> Result<Option<Raw<AnySyncEphemeralRoomEvent>>> {
271		let skip = || {
272			debug!(
273				count,
274				thread_kind,
275				%user_id,
276				"Skipping a private read marker naming a missing event."
277			);
278
279			None
280		};
281
282		self.build_private_read_event_fallible(shortroomid, count, ts, user_id, thread_kind)
283			.await
284			.optional()
285			.map(|event| event.or_else(skip))
286	}
287
288	async fn build_private_read_event(
289		&self,
290		shortroomid: u64,
291		count: u64,
292		ts: Option<u64>,
293		user_id: &UserId,
294		thread_kind: &str,
295	) -> Option<Raw<AnySyncEphemeralRoomEvent>> {
296		let thread = thread_kind_to_receipt(thread_kind).unwrap_or(ReceiptThread::Unthreaded);
297		let ts = ts
298			.and_then(UInt::new)
299			.map(MilliSecondsSinceUnixEpoch);
300
301		self.build_private_read_event_from(shortroomid, count, ts, user_id, thread)
302			.await
303			.ok()
304	}
305
306	async fn build_private_read_event_fallible(
307		&self,
308		shortroomid: u64,
309		count: u64,
310		ts: Option<u64>,
311		user_id: &UserId,
312		thread_kind: &str,
313	) -> Result<Raw<AnySyncEphemeralRoomEvent>> {
314		let thread = thread_kind_to_receipt(thread_kind)?;
315		let ts = ts
316			.map(|ts| {
317				UInt::new(ts)
318					.map(MilliSecondsSinceUnixEpoch)
319					.ok_or_else(|| err!(Database("Invalid private receipt timestamp {ts}.")))
320			})
321			.transpose()?;
322
323		self.build_private_read_event_from(shortroomid, count, ts, user_id, thread)
324			.await
325	}
326
327	async fn build_private_read_event_from(
328		&self,
329		shortroomid: u64,
330		count: u64,
331		ts: Option<MilliSecondsSinceUnixEpoch>,
332		user_id: &UserId,
333		thread: ReceiptThread,
334	) -> Result<Raw<AnySyncEphemeralRoomEvent>> {
335		let pdu_id: RawPduId = PduId {
336			shortroomid,
337			count: PduCount::Normal(count),
338		}
339		.into();
340		let pdu = self
341			.services
342			.timeline
343			.get_pdu_from_id(&pdu_id)
344			.await?;
345
346		let event_id: OwnedEventId = pdu.event_id().to_owned();
347		let user_id: OwnedUserId = user_id.to_owned();
348		let content: BTreeMap<OwnedEventId, Receipts> = BTreeMap::from_iter([(
349			event_id,
350			BTreeMap::from_iter([(
351				ReceiptType::ReadPrivate,
352				BTreeMap::from_iter([(user_id, Receipt { ts, thread })]),
353			)]),
354		)]);
355
356		let receipt_event_content = ReceiptEventContent(content);
357		let receipt_sync_event = SyncEphemeralRoomEvent { content: receipt_event_content };
358		let event = to_raw_value(&receipt_sync_event)?;
359
360		Ok(Raw::from_json(event))
361	}
362
363	/// Returns an iterator over the most recent read_receipts in a room that
364	/// happened after the event with id `since`.
365	#[tracing::instrument(skip(self), level = "debug")]
366	pub fn readreceipts_since<'a>(
367		&'a self,
368		room_id: &'a RoomId,
369		since: u64,
370		to: Option<u64>,
371	) -> impl Stream<Item = ReceiptItem<'_>> + Send + 'a {
372		self.db.readreceipts_since(room_id, since, to)
373	}
374
375	/// Returns read receipts in a bounded room range without suppressing
376	/// failures.
377	///
378	/// The lower bound is exclusive and the optional upper bound is inclusive.
379	/// Cursor, decode, and serialization failures remain in the stream for an
380	/// atomic caller to handle.
381	#[tracing::instrument(skip(self), level = "debug")]
382	pub fn readreceipts_since_fallible<'a>(
383		&'a self,
384		room_id: &'a RoomId,
385		since: u64,
386		to: Option<u64>,
387	) -> impl Stream<Item = Result<ReceiptItem<'_>>> + Send + 'a {
388		self.db
389			.readreceipts_since_fallible(room_id, since, to)
390	}
391
392	/// Sets a private read marker at PDU `count` for the given thread.
393	///
394	/// Unthreaded writes supersede prior per-thread rows so the room-wide
395	/// receipt subsumes thread state. Returns whether the marker advanced; a
396	/// position at or behind the stored one writes nothing.
397	#[tracing::instrument(skip(self), level = "debug", name = "set_private")]
398	pub async fn private_read_set(&self, private_read: PrivateRead<'_>) -> bool {
399		self.db.private_read_set(private_read).await
400	}
401
402	/// Returns the private read marker PDU count.
403	#[tracing::instrument(
404		name = "get_private_count",
405		level = "debug",
406		skip(self),
407		ret(level = "trace")
408	)]
409	pub async fn private_read_get_count(
410		&self,
411		room_id: &RoomId,
412		user_id: &UserId,
413	) -> Result<(u64, Option<u64>)> {
414		self.db
415			.private_read_get_count(room_id, user_id)
416			.await
417	}
418
419	/// Returns the announced unthreaded private read marker PDU count.
420	#[tracing::instrument(
421		name = "get_private_sync_count",
422		level = "debug",
423		skip(self),
424		ret(level = "trace")
425	)]
426	pub async fn private_read_sync_get_count(
427		&self,
428		room_id: &RoomId,
429		user_id: &UserId,
430	) -> Result<(u64, Option<u64>)> {
431		self.db
432			.private_read_sync_get_count(room_id, user_id)
433			.await
434	}
435
436	/// Returns the PDU count of the last private read update in this room.
437	///
438	/// Missing or unreadable update rows return zero for legacy callers.
439	/// Bounded sync callers use the fallible variant below so failures retain
440	/// the room cursor.
441	#[tracing::instrument(
442		name = "get_private_last",
443		level = "debug",
444		skip(self),
445		ret(level = "trace")
446	)]
447	pub async fn last_privateread_update(&self, user_id: &UserId, room_id: &RoomId) -> u64 {
448		self.db
449			.last_privateread_update(user_id, room_id)
450			.await
451	}
452
453	/// Returns the bounded-sync token for the last private read update.
454	///
455	/// A missing token is returned as zero. Database and decode failures are
456	/// preserved so a caller can retain its room cursor and retry the complete
457	/// range.
458	#[tracing::instrument(
459		name = "get_private_last_fallible",
460		level = "debug",
461		skip(self),
462		ret(level = "trace")
463	)]
464	pub async fn last_privateread_update_fallible(
465		&self,
466		user_id: &UserId,
467		room_id: &RoomId,
468	) -> Result<u64> {
469		self.db
470			.last_privateread_update_fallible(user_id, room_id)
471			.await
472	}
473
474	pub async fn delete_all_read_receipts(&self, room_id: &RoomId) -> Result {
475		self.db.delete_all_read_receipts(room_id).await
476	}
477}
478
479/// Reverse of `ReceiptThread::as_str`: parse a stored thread tag into the
480/// enum. Empty string maps to `Unthreaded`; `"main"` to `Main`; all other
481/// values must be valid event IDs.
482fn thread_kind_to_receipt(thread_kind: &str) -> Result<ReceiptThread> {
483	match thread_kind {
484		| "" => Ok(ReceiptThread::Unthreaded),
485		| "main" => Ok(ReceiptThread::Main),
486		| _ => OwnedEventId::try_from(thread_kind)
487			.map(ReceiptThread::Thread)
488			.map_err(|error| err!(Database("Invalid private receipt thread: {error}"))),
489	}
490}
491
492/// Packs read receipts into one sync event without suppressing malformed input.
493///
494/// Every input must deserialize as a receipt event. The caller receives any
495/// parse or serialization failure and can retain the bounded room cursor
496/// instead of publishing a partial event.
497pub fn pack_receipts_fallible<I>(
498	mut receipts: I,
499) -> Result<Raw<SyncEphemeralRoomEvent<ReceiptEventContent>>>
500where
501	I: Iterator<Item = Raw<AnySyncEphemeralRoomEvent>>,
502{
503	let content =
504		receipts.try_fold(ReceiptEventContent(BTreeMap::new()), |json, value| -> Result<_> {
505			let value = serde_json::from_str::<SyncEphemeralRoomEvent<ReceiptEventContent>>(
506				value.json().get(),
507			)?;
508
509			Ok(merge_receipts(json, value.content))
510		})?;
511
512	let event = to_raw_value(&SyncEphemeralRoomEvent { content })?;
513
514	Ok(Raw::from_json(event))
515}
516
517fn merge_receipts(
518	mut content: ReceiptEventContent,
519	incoming: ReceiptEventContent,
520) -> ReceiptEventContent {
521	for (event, receipts) in incoming {
522		let merged = content.0.entry(event).or_default();
523
524		for (receipt_type, users) in receipts {
525			merged
526				.entry(receipt_type)
527				.or_default()
528				.extend(users);
529		}
530	}
531
532	content
533}