Skip to main content

tuwunel_service/rooms/read_receipt/
data.rs

1use std::{collections::BTreeMap, sync::Arc};
2
3use futures::{
4	Stream, TryStreamExt,
5	future::{join, try_join},
6};
7use ruma::{
8	CanonicalJsonObject, EventId, OwnedEventId, RoomId, UserId,
9	events::{AnySyncEphemeralRoomEvent, receipt::ReceiptEvent},
10	serde::Raw,
11};
12use serde::{Deserialize, de::IgnoredAny};
13use tuwunel_core::{
14	Result, error,
15	result::NotFound,
16	smallvec::SmallVec,
17	trace,
18	utils::{ReadyExt, TryReadyExt, stream::TryIgnore},
19};
20use tuwunel_database::{Deserialized, Interfix, Json, KeyBuf, Map, Txn, serialize_key};
21use tuwunel_matrix::pdu::PduCount;
22
23use super::{PrivateRead, ThreadKind};
24
25pub(super) struct Data {
26	roomuserid_privateread: Arc<Map>,
27	roomuserid_lastprivatereadupdate: Arc<Map>,
28	roomuserid_privatereadsync: Arc<Map>,
29	services: Arc<crate::services::OnceServices>,
30	readreceiptid_readreceipt: Arc<Map>,
31}
32
33pub(super) type ReceiptItem<'a> = (&'a UserId, u64, Raw<AnySyncEphemeralRoomEvent>);
34
35/// Row shape shared by the active and mirrored private read maps.
36type RowKv<'a> = ((&'a RoomId, &'a UserId, &'a str), (u64, Option<u64>));
37
38/// Receipt rows an accepted update replaces.
39///
40/// A user normally holds one row per thread context; an unthreaded sweep can
41/// also catch a pre-MSC3771 row, and that second key spills to the heap.
42type Superseded = SmallVec<[KeyBuf; 1]>;
43
44/// Minimal read-back of a stored receipt row.
45///
46/// Only the content's event ids are read, so the reject path never
47/// materializes the receipts themselves. The wire shape is a JSON object,
48/// which no set type can express, hence the zero-sized value.
49#[derive(Deserialize)]
50#[expect(clippy::zero_sized_map_values)]
51struct StoredContent {
52	content: BTreeMap<OwnedEventId, IgnoredAny>,
53}
54
55impl Data {
56	pub(super) fn new(args: &crate::Args<'_>) -> Self {
57		let db = &args.db;
58		Self {
59			roomuserid_privateread: db["roomuserid_privateread"].clone(),
60			roomuserid_lastprivatereadupdate: db["roomuserid_lastprivatereadupdate"].clone(),
61			roomuserid_privatereadsync: db["roomuserid_privatereadsync"].clone(),
62			readreceiptid_readreceipt: db["readreceiptid_readreceipt"].clone(),
63			services: args.services.clone(),
64		}
65	}
66
67	/// Stores `event` as the user's receipt for its thread context, reporting
68	/// whether it advanced.
69	///
70	/// A receipt naming the stored event, or an earlier one, is rejected
71	/// without allocating a stream position or writing anything. An accepted
72	/// receipt replaces every superseded row in one transaction.
73	#[inline]
74	pub(super) async fn readreceipt_update(
75		&self,
76		user_id: &UserId,
77		room_id: &RoomId,
78		event: &ReceiptEvent,
79	) -> bool {
80		// Remote-supplied content reaches this sink over federation, so an
81		// empty receipt is rejected rather than stored as an unreadable row.
82		let Some(event_id) = event.content.keys().next() else {
83			return false;
84		};
85
86		let thread_kind = event_thread_kind(event);
87		// MSC3771: storage key suffix is `user_id || 0xFF || thread_kind` so
88		// each (user, thread-context) tuple lives in its own row. Pre-MSC3771
89		// rows have no kind tail; on an Unthreaded sweep also match the
90		// bare-user-id ending so legacy rows are superseded rather than
91		// orphaned. Kind tails ("main", `$root`) never end in `@user:host`,
92		// so the legacy match cannot collide with thread-aware rows.
93		let suffix = serialize_key((user_id, thread_kind))
94			.expect("failed to serialize receipt key suffix");
95
96		let user_id_bytes = user_id.as_bytes();
97		let legacy_match = thread_kind.is_empty();
98
99		// A bare room-id prefix also matches longer room ids, whose rows sort
100		// below ours in reverse iteration and would be reaped by the sweep.
101		let room_prefix =
102			serialize_key((room_id, Interfix)).expect("failed to serialize receipt room prefix");
103
104		let last_possible_key = (room_id, u64::MAX);
105		let (superseded, current) = self
106			.readreceiptid_readreceipt
107			.rev_stream_from_raw(&last_possible_key)
108			.ignore_err()
109			.ready_take_while(|(key, _)| key.starts_with(room_prefix.as_slice()))
110			.ready_filter_map(|(key, val)| {
111				(key.ends_with(suffix.as_slice())
112					|| (legacy_match && key.ends_with(user_id_bytes)))
113				.then_some((key, val))
114			})
115			.ready_fold((Superseded::new(), None), |(mut superseded, current), (key, val)| {
116				let current = superseded
117					.is_empty()
118					.then_some(val)
119					.and_then(stored_event_id)
120					.or(current);
121
122				superseded.push(key.into());
123
124				(superseded, current)
125			})
126			.await;
127
128		if !self
129			.receipt_advanced(current.as_deref(), event_id)
130			.await
131		{
132			return false;
133		}
134
135		let count = self.services.globals.next_count();
136		let latest_id = (room_id, *count, user_id, thread_kind);
137
138		let mut txn = superseded
139			.iter()
140			.fold(self.services.db.txn(), |mut txn, key| {
141				txn.del_raw(&self.readreceiptid_readreceipt, key);
142				txn
143			});
144
145		txn.put(&self.readreceiptid_readreceipt, latest_id, Json(event));
146		txn.execute();
147
148		true
149	}
150
151	/// Whether a receipt for `incoming` supersedes the stored one at
152	/// `current`.
153	///
154	/// An identical event id never advances. A position that does not resolve
155	/// to a known PDU falls through to acceptance, so a receipt this server
156	/// cannot order is never silently dropped.
157	pub(super) async fn receipt_advanced(
158		&self,
159		current: Option<&EventId>,
160		incoming: &EventId,
161	) -> bool {
162		match current {
163			| None => true,
164			| Some(current) if current == incoming => false,
165			| Some(current) => {
166				let (current, incoming) = join(
167					self.services.timeline.get_pdu_count(current),
168					self.services.timeline.get_pdu_count(incoming),
169				)
170				.await;
171
172				position_advances(current.ok(), incoming.ok())
173			},
174		}
175	}
176
177	#[inline]
178	pub(super) fn readreceipts_since<'a>(
179		&'a self,
180		room_id: &'a RoomId,
181		since: u64,
182		to: Option<u64>,
183	) -> impl Stream<Item = ReceiptItem<'_>> + Send + 'a {
184		self.readreceipts_since_fallible(room_id, since, to)
185			.ignore_err()
186	}
187
188	#[inline]
189	pub(super) fn readreceipts_since_fallible<'a>(
190		&'a self,
191		room_id: &'a RoomId,
192		since: u64,
193		to: Option<u64>,
194	) -> impl Stream<Item = Result<ReceiptItem<'_>>> + Send + 'a {
195		// 4-tuple key: pre-MSC3771 rows deserialize with `&str` tail empty.
196		type Key<'a> = (&'a RoomId, u64, &'a UserId, &'a str);
197		type KeyVal<'a> = (Key<'a>, CanonicalJsonObject);
198
199		let after_since = since.saturating_add(1); // +1 so we don't send the event at since
200		let first_possible_edu = (room_id, after_since);
201
202		self.readreceiptid_readreceipt
203			.stream_from(&first_possible_edu)
204			.ready_try_take_while(move |((r, c, ..), _): &KeyVal<'_>| {
205				Ok(*r == room_id && to.is_none_or(|to| *c <= to))
206			})
207			.ready_and_then(move |((_, count, user_id, _), mut json): KeyVal<'_>| {
208				json.remove("room_id");
209
210				let event = serde_json::value::to_raw_value(&json)?;
211
212				Ok((user_id, count, Raw::from_json(event)))
213			})
214	}
215
216	/// Sets the private read marker for `(room, user, thread)`, reporting
217	/// whether it advanced.
218	///
219	/// Unthreaded writes use the legacy 2-tuple `(room, user)` key shape
220	/// and sweep any pre-existing per-thread rows so the room-wide receipt
221	/// supersedes prior thread state. Threaded writes (Main, Thread, custom)
222	/// use a 3-tuple `(room, user, thread_kind)` key disjoint from the
223	/// legacy row by trailing separator. The sync gate
224	/// (`roomuserid_lastprivatereadupdate`) stays 2-tuple and bumps only when
225	/// `announce` is set, keeping it a single point query. Announced state is
226	/// mirrored separately so notification-only writes cannot alter a sync
227	/// snapshot without changing its version.
228	#[inline]
229	pub(super) async fn private_read_set(
230		&self,
231		PrivateRead {
232			room_id,
233			user_id,
234			count,
235			ts,
236			thread,
237			announce,
238		}: PrivateRead<'_>,
239	) -> bool {
240		let thread_kind = thread.as_str().unwrap_or_default();
241
242		if self
243			.private_read_position(room_id, user_id, thread_kind)
244			.await
245			.is_ok_and(|(stored, _)| count <= stored)
246		{
247			return false;
248		}
249
250		let reset_sync = if announce && !thread_kind.is_empty() {
251			let versions = try_join(
252				self.last_privateread_update_fallible(user_id, room_id),
253				self.private_read_sync_update_fallible(user_id, room_id),
254			)
255			.await;
256
257			match versions {
258				| Ok((gate, snapshot)) => gate != snapshot,
259				| Err(error) => {
260					error!(?error, "Failed to inspect the private read sync snapshot.");
261					return false;
262				},
263			}
264		} else {
265			false
266		};
267
268		let mut txn = self
269			.sweep_thread_private_reads(
270				&self.roomuserid_privateread,
271				room_id,
272				user_id,
273				thread_kind,
274				self.services.db.txn(),
275			)
276			.await;
277
278		if announce && (thread_kind.is_empty() || reset_sync) {
279			txn = match self
280				.sweep_private_read_sync(room_id, user_id, txn)
281				.await
282			{
283				| Ok(txn) => txn,
284				| Err(error) => {
285					error!(?error, "Failed to reset the private read sync snapshot.");
286					return false;
287				},
288			};
289		}
290
291		// The permit retires the sequence number on drop, so it outlives execute().
292		let next_count = announce.then(|| self.services.globals.next_count());
293		let ts = u64::from(ts.get());
294
295		if let Some(next_count) = next_count.as_deref() {
296			txn.put(&self.roomuserid_lastprivatereadupdate, (room_id, user_id), *next_count);
297			txn.put(&self.roomuserid_privatereadsync, (room_id, user_id), *next_count);
298			txn.put(
299				&self.roomuserid_privatereadsync,
300				(room_id, user_id, thread_kind),
301				(count, ts),
302			);
303		}
304
305		// Additive value tail: ts (millis); old bare-count rows read back None.
306		match thread_kind.is_empty() {
307			| true => txn.put(&self.roomuserid_privateread, (room_id, user_id), (count, ts)),
308			| false => txn.put(
309				&self.roomuserid_privateread,
310				(room_id, user_id, thread_kind),
311				(count, ts),
312			),
313		}
314
315		txn.execute();
316
317		true
318	}
319
320	/// Private read position for an exact `(room, user, thread)` context.
321	///
322	/// An unthreaded context reads the legacy 2-tuple row; a threaded one
323	/// reads its own 3-tuple row.
324	#[inline]
325	async fn private_read_position(
326		&self,
327		room_id: &RoomId,
328		user_id: &UserId,
329		thread_kind: &str,
330	) -> Result<(u64, Option<u64>)> {
331		match thread_kind.is_empty() {
332			| true =>
333				self.private_read_get_count(room_id, user_id)
334					.await,
335			| false => self
336				.roomuserid_privateread
337				.qry(&(room_id, user_id, thread_kind))
338				.await
339				.deserialized(),
340		}
341	}
342
343	/// Latest unthreaded (legacy 2-tuple) private read: `(pdu count, receipt ts
344	/// millis)`. `ts` is `None` for rows written before the ts tail was added.
345	#[inline]
346	pub(super) async fn private_read_get_count(
347		&self,
348		room_id: &RoomId,
349		user_id: &UserId,
350	) -> Result<(u64, Option<u64>)> {
351		let key = (room_id, user_id);
352		self.roomuserid_privateread
353			.qry(&key)
354			.await
355			.deserialized()
356	}
357
358	#[inline]
359	pub(super) async fn private_read_sync_get_count(
360		&self,
361		room_id: &RoomId,
362		user_id: &UserId,
363	) -> Result<(u64, Option<u64>)> {
364		let key = (room_id, user_id, "");
365		self.roomuserid_privatereadsync
366			.qry(&key)
367			.await
368			.deserialized()
369	}
370
371	#[inline]
372	pub(super) fn private_read_threaded_stream<'a>(
373		&'a self,
374		room_id: &'a RoomId,
375		user_id: &'a UserId,
376	) -> impl Stream<Item = (ThreadKind, u64, Option<u64>)> + Send + 'a {
377		private_read_row_stream(&self.roomuserid_privateread, room_id, user_id).ignore_err()
378	}
379
380	/// Queues deletion of the per-thread private read rows for `(room, user)`.
381	///
382	/// Only an unthreaded write sweeps, since its room-wide receipt supersedes
383	/// prior thread state; a threaded write touches only its own row.
384	#[inline]
385	async fn sweep_thread_private_reads(
386		&self,
387		map: &Arc<Map>,
388		room_id: &RoomId,
389		user_id: &UserId,
390		thread_kind: &str,
391		txn: Txn,
392	) -> Txn {
393		if !thread_kind.is_empty() {
394			return txn;
395		}
396
397		let prefix = (room_id, user_id, Interfix);
398
399		map.keys_prefix_raw(&prefix)
400			.ignore_err()
401			.ready_fold(txn, |mut txn, key| {
402				txn.del_raw(map, key);
403				txn
404			})
405			.await
406	}
407
408	#[inline]
409	async fn sweep_private_read_sync(
410		&self,
411		room_id: &RoomId,
412		user_id: &UserId,
413		txn: Txn,
414	) -> Result<Txn> {
415		let prefix = (room_id, user_id, Interfix);
416
417		self.roomuserid_privatereadsync
418			.keys_prefix_raw(&prefix)
419			.ready_try_fold(txn, |mut txn, key| {
420				txn.del_raw(&self.roomuserid_privatereadsync, key);
421				Ok(txn)
422			})
423			.await
424	}
425
426	#[inline]
427	pub(super) fn private_read_sync_stream_fallible<'a>(
428		&'a self,
429		room_id: &'a RoomId,
430		user_id: &'a UserId,
431	) -> impl Stream<Item = Result<(ThreadKind, u64, Option<u64>)>> + Send + 'a {
432		private_read_row_stream(&self.roomuserid_privatereadsync, room_id, user_id)
433	}
434
435	#[inline]
436	pub(super) async fn private_read_sync_update_fallible(
437		&self,
438		user_id: &UserId,
439		room_id: &RoomId,
440	) -> Result<u64> {
441		let key = (room_id, user_id);
442		self.roomuserid_privatereadsync
443			.qry(&key)
444			.await
445			.deserialized()
446			.optional()
447			.map(|count| count.unwrap_or(0))
448	}
449
450	#[inline]
451	pub(super) async fn last_privateread_update(
452		&self,
453		user_id: &UserId,
454		room_id: &RoomId,
455	) -> u64 {
456		self.last_privateread_update_fallible(user_id, room_id)
457			.await
458			.unwrap_or_default()
459	}
460
461	#[inline]
462	pub(super) async fn last_privateread_update_fallible(
463		&self,
464		user_id: &UserId,
465		room_id: &RoomId,
466	) -> Result<u64> {
467		let key = (room_id, user_id);
468		self.roomuserid_lastprivatereadupdate
469			.qry(&key)
470			.await
471			.deserialized()
472			.optional()
473			.map(|count| count.unwrap_or(0))
474	}
475
476	#[inline]
477	pub(super) async fn delete_all_read_receipts(&self, room_id: &RoomId) -> Result {
478		let prefix = (room_id, Interfix);
479
480		self.roomuserid_privateread
481			.keys_prefix_raw(&prefix)
482			.ignore_err()
483			.ready_for_each(|key| {
484				trace!("Removing key: {key:?}");
485				self.roomuserid_privateread.remove(key);
486			})
487			.await;
488
489		self.roomuserid_lastprivatereadupdate
490			.keys_prefix_raw(&prefix)
491			.ignore_err()
492			.ready_for_each(|key| {
493				trace!("Removing key: {key:?}");
494				self.roomuserid_lastprivatereadupdate.remove(key);
495			})
496			.await;
497
498		self.roomuserid_privatereadsync
499			.keys_prefix_raw(&prefix)
500			.ignore_err()
501			.ready_for_each(|key| {
502				trace!("Removing key: {key:?}");
503				self.roomuserid_privatereadsync.remove(key);
504			})
505			.await;
506
507		self.readreceiptid_readreceipt
508			.keys_prefix_raw(&prefix)
509			.ignore_err()
510			.ready_for_each(|key| {
511				trace!("Removing key: {key:?}");
512				self.readreceiptid_readreceipt.remove(key);
513			})
514			.await;
515
516		Ok(())
517	}
518}
519
520/// Per-thread marker rows under `(room, user)` in `map`.
521///
522/// Active markers in the live store and announced markers in the sync mirror
523/// share one row shape, keyed by thread kind.
524fn private_read_row_stream<'a>(
525	map: &'a Arc<Map>,
526	room_id: &'a RoomId,
527	user_id: &'a UserId,
528) -> impl Stream<Item = Result<(ThreadKind, u64, Option<u64>)>> + Send + 'a {
529	let prefix = (room_id, user_id, Interfix);
530
531	map.stream_prefix(&prefix)
532		.map_ok(|((_, _, kind), (count, ts)): RowKv<'_>| (ThreadKind::from(kind), count, ts))
533}
534
535/// Tag string used in the storage key to discriminate receipts per thread.
536/// Empty for `Unthreaded`, `"main"` for `Main`, the event-id string for
537/// `Thread(...)` (event ids start with `$`, so the values are mutually
538/// exclusive). Custom variants reuse their string form; the C/S boundary
539/// rejects them, but federation receipts may still carry them through.
540///
541/// Reads only the first `(event_id, type, user)` triple. All callers
542/// build single-entry receipts (one event id, one type, one user); a
543/// debug assertion catches future regressions. An entirely empty event
544/// or one whose only receipt lacks a thread field falls back to `""`.
545///
546/// Appended to the receipt-row key as a tolerant trailing field. Pre-
547/// MSC3771 rows have no trailing kind; they round-trip as `""`.
548fn event_thread_kind(event: &ReceiptEvent) -> &str {
549	debug_assert!(
550		event
551			.content
552			.values()
553			.all(|by_type| by_type.len() == 1
554				&& by_type.values().all(|by_user| by_user.len() == 1))
555			&& event.content.len() == 1,
556		"receipt event must carry exactly one (event_id, type, user) triple"
557	);
558
559	event
560		.content
561		.values()
562		.next()
563		.and_then(|by_type| by_type.values().next())
564		.and_then(|by_user| by_user.values().next())
565		.and_then(|receipt| receipt.thread.as_str())
566		.unwrap_or_default()
567}
568
569/// First event id named by a stored receipt row.
570///
571/// `None` when the row does not deserialize, which the caller treats as an
572/// unknown position and accepts, replacing the row.
573fn stored_event_id(val: &[u8]) -> Option<OwnedEventId> {
574	serde_json::from_slice::<StoredContent>(val)
575		.ok()?
576		.content
577		.into_keys()
578		.next()
579}
580
581/// Whether an incoming receipt position strictly advances the stored one.
582///
583/// An unresolved position on either side accepts. `PduCount` ordering places
584/// backfilled events below normal ones, so no separate branch is needed.
585pub(super) fn position_advances(current: Option<PduCount>, incoming: Option<PduCount>) -> bool {
586	current
587		.zip(incoming)
588		.is_none_or(|(current, incoming)| incoming > current)
589}