Skip to main content

tuwunel_service/integrity/
thread_summaries.rs

1//! The thread summaries stored on thread roots.
2//!
3//! A root's `unsigned` holds its thread's reply count and latest reply, kept
4//! current as replies arrive and are redacted. The roots are the ones
5//! `threadid_userids` lists.
6
7use std::{fmt, sync::Arc};
8
9use futures::{Stream, TryStreamExt};
10use ruma::{CanonicalJsonObject, UInt};
11use tuwunel_core::{
12	Result,
13	itertools::Either::{Left, Right},
14	result::NotFound,
15	utils::TryReadyExt,
16};
17use tuwunel_database::{KeyBuf, Map};
18use tuwunel_matrix::RawPduId;
19
20use super::{Check, Report, ScanExt, leading_json, tally};
21use crate::{Services, rooms::threads::Recount};
22
23pub(super) static CHECK: Check = Check {
24	name: "thread-summaries",
25	about: "Every listed thread root's summary agrees with a recount of its replies",
26	quiescent: true,
27	walk: |services, limit| tally(scan(services), limit),
28};
29
30/// A thread root whose stored summary disagrees with its replies, or cannot be
31/// read.
32///
33/// The summary rebuild rewrites a disagreeing summary, and leaves the rest. A
34/// root whose relation index holds a damaged key or reply, or whose latest reply
35/// has a damaged timeline mapping or row, is reported for that alone, since its
36/// recount is incomplete.
37pub enum Finding {
38	/// The summary's count, or its latest reply, disagrees with the replies.
39	Stale {
40		/// The root.
41		root_id: RawPduId,
42
43		/// The count the summary holds.
44		stored: Option<UInt>,
45
46		/// The count the replies give.
47		counted: Option<UInt>,
48
49		/// Whether the summary's latest reply is gone or redacted.
50		latest: bool,
51	},
52
53	/// The root's relation index holds keys too short to name a reply, or names
54	/// replies whose rows do not decode.
55	MalformedRelation {
56		/// The root.
57		root_id: RawPduId,
58
59		/// How many such relations the recount skipped.
60		malformed: usize,
61	},
62
63	/// The summary's latest reply has a timeline mapping that is not a PDU id,
64	/// or a row that does not decode.
65	MalformedLatest {
66		/// The root.
67		root_id: RawPduId,
68	},
69
70	/// The root's row does not decode.
71	Unreadable {
72		/// The root.
73		root_id: RawPduId,
74	},
75
76	/// A `threadid_userids` key is not a PDU id.
77	Unparsable {
78		/// The stored key.
79		key: KeyBuf,
80	},
81}
82
83/// Streams each listed thread root whose summary disagrees with a recount.
84///
85/// A root no longer stored, or holding no summary, is skipped as the rebuild skips
86/// it. The rebuild re-reads each root under its room lock and decides through the
87/// same recount, so the two agree. A reply or latest reply whose row the storage
88/// engine cannot read ends the stream with its error, while one whose row or
89/// mapping does not decode is a finding.
90#[tracing::instrument(level = "trace", skip_all)]
91pub fn scan(services: &Services) -> impl Stream<Item = Result<Finding>> + Send + '_ {
92	let pdus = &services.db["pduid_pdu"];
93
94	// The recount already fans out per root, so a concurrent stage here nests fan-outs.
95	services.db["threadid_userids"]
96		.raw_scan()
97		.scanned(&services.server)
98		.ready_and_then(|(key, _)| {
99			Ok(RawPduId::try_from_bytes(key).ok_or_else(|| KeyBuf::from_slice(key)))
100		})
101		.and_then(async |root_id| match root_id {
102			| Ok(root_id) => verify(services, pdus, root_id).await,
103			| Err(key) => Ok(Some(Finding::Unparsable { key })),
104		})
105		.ready_try_filter_map(Ok)
106}
107
108impl Report for Finding {
109	fn kind(&self) -> &'static str {
110		match self {
111			| Self::Stale { .. } => "stale-summary",
112			| Self::MalformedRelation { .. } => "malformed-relation",
113			| Self::MalformedLatest { .. } => "malformed-mapping",
114			| Self::Unreadable { .. } => "unreadable-root",
115			| Self::Unparsable { .. } => "unparsable-key",
116		}
117	}
118}
119
120impl fmt::Display for Finding {
121	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
122		match self {
123			| Self::Unreadable { root_id } => {
124				write!(f, "thread root {root_id:?} does not decode")
125			},
126			| Self::Unparsable { key } => {
127				write!(f, "thread key is not a PDU id: {}", key.escape_ascii())
128			},
129			| Self::MalformedLatest { root_id } => write!(
130				f,
131				"latest reply of thread root {root_id:?} has a timeline mapping or row that \
132				 does not decode"
133			),
134			| Self::MalformedRelation { root_id, malformed } => {
135				write!(
136					f,
137					"thread root {root_id:?} has {malformed} relation keys or replies that do \
138					 not decode"
139				)
140			},
141			| Self::Stale { root_id, stored, counted, latest } => {
142				let shown = |count: &Option<UInt>| count.map_or(Left("none"), Right);
143
144				write!(
145					f,
146					"summary of thread root {root_id:?} counts {} where its replies give {}, \
147					 latest reply gone or redacted: {latest}",
148					shown(stored),
149					shown(counted),
150				)
151			},
152		}
153	}
154}
155
156#[tracing::instrument(level = "debug", skip_all)]
157async fn verify(
158	services: &Services,
159	pdus: &Arc<Map>,
160	root_id: RawPduId,
161) -> Result<Option<Finding>> {
162	let Some(root) = pdus
163		.get(&root_id)
164		.await
165		.optional()?
166		.map(|root| leading_json::<CanonicalJsonObject>(&root))
167	else {
168		return Ok(None);
169	};
170
171	let Ok(root) = root else {
172		return Ok(Some(Finding::Unreadable { root_id }));
173	};
174
175	let recount = services
176		.threads
177		.recount_summary(root_id, &root)
178		.await?;
179
180	let finding = recount
181		.as_ref()
182		.and_then(|recount| finding(root_id, recount));
183
184	Ok(finding)
185}
186
187fn finding(root_id: RawPduId, recount: &Recount) -> Option<Finding> {
188	let &Recount {
189		stored,
190		counted,
191		stale_latest,
192		malformed,
193		malformed_latest,
194		..
195	} = recount;
196
197	match malformed {
198		| 0 if malformed_latest => Some(Finding::MalformedLatest { root_id }),
199		| 0 if recount.changed() => Some(Finding::Stale {
200			root_id,
201			stored,
202			counted,
203			latest: stale_latest,
204		}),
205		| 0 => None,
206		| malformed => Some(Finding::MalformedRelation { root_id, malformed }),
207	}
208}