Skip to main content

tuwunel_service/integrity/
moderation.rs

1//! Suspensions and locks a foreign database records.
2//!
3//! Some databases keep suspension and lock state in columns of their own, with a
4//! richer value. tuwunel keeps only the forensic `when` and `by`, with a row's
5//! presence as the flag, and copies each active foreign entry over on every boot.
6
7use std::{borrow::Cow, fmt, sync::Arc};
8
9use futures::{FutureExt, Stream, StreamExt, future::BoxFuture};
10use ruma::{MilliSecondsSinceUnixEpoch, UserId};
11use serde::Deserialize;
12use tuwunel_core::{
13	Result,
14	arrayvec::ArrayVec,
15	result::NotFound,
16	utils::{BoolExt, IterStream, TryReadyExt, stream::TryBroadbandExt},
17};
18use tuwunel_database::{Json, KeyBuf, Map, serialize_val};
19
20use super::{Check, Report, ScanExt, Summary, tally};
21use crate::{Services, users::Moderation};
22
23type Sources = ArrayVec<Source, { COLUMNS.len() }>;
24
25pub(super) static CHECK: Check = Check {
26	name: "foreign-moderation",
27	about: "Every active suspension and lock a foreign column records is copied into tuwunel's \
28	        own",
29	quiescent: true,
30	walk,
31};
32
33/// Each foreign column, with the column its entries copy into.
34///
35/// Both foreign columns hold the same entry shape, so one parser reads either.
36const COLUMNS: [(&str, &str); 2] =
37	[("userid_suspension", "userid_suspended"), ("userid_lock", "userid_locked")];
38
39/// A foreign entry, of which tuwunel keeps the time and the actor.
40///
41/// `suspended_by` is an unvalidated string in the source, so it is parsed when
42/// the entry is copied, leniently.
43#[derive(Deserialize)]
44struct Foreign<'a> {
45	suspended: bool,
46	suspended_at: MilliSecondsSinceUnixEpoch,
47	#[serde(borrow)]
48	suspended_by: Cow<'a, str>,
49}
50
51/// A foreign moderation column the database holds, opened.
52///
53/// A walk borrows the column it reads, so whoever walks one holds its source for
54/// as long as the walk runs.
55pub struct Source {
56	/// The name of the foreign column.
57	pub name: &'static str,
58
59	/// The foreign column.
60	pub map: Arc<Map>,
61
62	/// The name of the column its entries copy into.
63	pub target: &'static str,
64}
65
66/// A foreign entry the copy has yet to carry over, or cannot.
67///
68/// The copy writes each active entry into its target as tuwunel's own record, and
69/// leaves an entry that does not decode.
70pub enum Finding {
71	/// The entry is active, and its target lacks it or holds another value.
72	Uncopied {
73		/// The name of the foreign column.
74		source: &'static str,
75
76		/// The stored key, the same in both columns.
77		key: KeyBuf,
78
79		/// The record the copy writes.
80		moderation: Moderation,
81	},
82
83	/// The entry does not decode.
84	Unparsable {
85		/// The name of the foreign column.
86		source: &'static str,
87
88		/// The stored key.
89		key: KeyBuf,
90	},
91}
92
93/// One foreign entry as the copy reads it.
94///
95/// The copy writes every active entry and the check compares each with its
96/// target, so both read entries through this.
97pub(crate) enum Entry {
98	/// The entry is active, read as the record the copy writes.
99	Active {
100		/// The stored key, the same in both columns.
101		key: KeyBuf,
102
103		/// The record the copy writes.
104		moderation: Moderation,
105	},
106
107	/// The entry does not decode.
108	Unparsable {
109		/// The stored key.
110		key: KeyBuf,
111
112		/// Why it does not decode.
113		error: serde_json::Error,
114	},
115}
116
117/// Opens each foreign moderation column the database holds.
118///
119/// A column the database lacks is skipped, since its absence is no defect.
120pub fn sources(services: &Services) -> impl Iterator<Item = Result<Source>> + Send + '_ {
121	COLUMNS.into_iter().filter_map(|(name, target)| {
122		services
123			.db
124			.open_cf(name)
125			.transpose()
126			.map(|map| map.map(|map| Source { name, map, target }))
127	})
128}
129
130/// Streams each active entry of a foreign column that its target lacks or holds
131/// otherwise, and each entry that does not decode.
132///
133/// An entry is compared with its target row as the copy would write it, byte for
134/// byte. An inactive entry is not reported, as tuwunel has no record for it.
135#[tracing::instrument(
136	level = "trace",
137	skip_all,
138	fields(
139		source = source.name,
140	),
141)]
142pub fn scan<'a>(
143	services: &'a Services,
144	source: &'a Source,
145) -> impl Stream<Item = Result<Finding>> + Send + 'a {
146	let target = &services.db[source.target];
147
148	entries(services, source)
149		.broad_and_then(async move |entry| {
150			let current = match &entry {
151				| Entry::Active { key, .. } => target.get(key).map(NotFound::optional).await?,
152				| Entry::Unparsable { .. } => None,
153			};
154
155			Ok(finding(source.name, entry, current.as_deref()))
156		})
157		.ready_try_filter_map(Ok)
158}
159
160/// Streams every active entry of a foreign column, and every entry that does not
161/// decode.
162///
163/// The copy writes each active entry whatever its target holds, and reads entries
164/// as the check does. An inactive entry is left out, as tuwunel has no record for
165/// it.
166#[tracing::instrument(
167	level = "trace",
168	skip_all,
169	fields(
170		source = source.name,
171	),
172)]
173pub(crate) fn entries<'a>(
174	services: &'a Services,
175	source: &'a Source,
176) -> impl Stream<Item = Result<Entry>> + Send + 'a {
177	let fallback = services.globals.server_user.as_ref();
178
179	source
180		.map
181		.raw_scan()
182		.scanned(&services.server)
183		.ready_try_filter_map(move |(key, value)| Ok(entry(key, value, fallback)))
184}
185
186impl Report for Finding {
187	fn kind(&self) -> &'static str {
188		match self {
189			| Self::Uncopied { .. } => "uncopied-entry",
190			| Self::Unparsable { .. } => "unparsable-entry",
191		}
192	}
193}
194
195impl fmt::Display for Finding {
196	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
197		match self {
198			| Self::Uncopied { source, key, .. } => {
199				write!(
200					f,
201					"active entry {} in {source} has no copy, or another",
202					key.escape_ascii()
203				)
204			},
205			| Self::Unparsable { source, key } => {
206				write!(f, "entry {} in {source} does not decode", key.escape_ascii())
207			},
208		}
209	}
210}
211
212// The opened columns live in this future, since every column's walk borrows one.
213fn walk(services: &Services, limit: usize) -> BoxFuture<'_, Result<Summary>> {
214	async move {
215		let opened: Sources = sources(services).collect::<Result<_>>()?;
216		let findings = opened
217			.iter()
218			.stream()
219			.flat_map(|source| scan(services, source));
220
221		tally(findings, limit).await
222	}
223	.boxed() // type-erasure boundary
224}
225
226/// Judges one foreign entry against its target row as [`scan`] does.
227///
228/// `current` is the target row as it stands. An active entry is uncopied unless
229/// that row holds exactly what the copy writes.
230pub(super) fn finding(
231	source: &'static str,
232	entry: Entry,
233	current: Option<&[u8]>,
234) -> Option<Finding> {
235	let (key, moderation) = match entry {
236		| Entry::Active { key, moderation } => (key, moderation),
237		| Entry::Unparsable { key, .. } => return Some(Finding::Unparsable { source, key }),
238	};
239
240	let copied = current.is_some_and(|current| {
241		serialize_val(Json(&moderation)).is_ok_and(|expected| expected.as_slice().eq(current))
242	});
243
244	copied
245		.is_false()
246		.then_some(Finding::Uncopied { source, key, moderation })
247}
248
249/// Reads one foreign row as the copy and the check do.
250///
251/// An inactive entry is `None`, and `fallback` is the actor credited when the
252/// entry's own does not parse.
253pub(super) fn entry(key: &[u8], value: &[u8], fallback: &UserId) -> Option<Entry> {
254	let entry = match serde_json::from_slice::<Foreign<'_>>(value) {
255		| Ok(entry) => entry,
256		| Err(error) => {
257			return Some(Entry::Unparsable { key: KeyBuf::from_slice(key), error });
258		},
259	};
260
261	entry.suspended.then(|| Entry::Active {
262		key: KeyBuf::from_slice(key),
263		moderation: to_moderation(&entry, fallback),
264	})
265}
266
267/// Maps a foreign entry to tuwunel's own record.
268///
269/// An entry whose actor is unparsable is kept all the same, credited to
270/// `fallback`: the actor is forensic only, while the row's presence is the flag.
271fn to_moderation(entry: &Foreign<'_>, fallback: &UserId) -> Moderation {
272	Moderation {
273		when: entry.suspended_at,
274		by: UserId::parse(&*entry.suspended_by).unwrap_or_else(|_| fallback.to_owned()),
275	}
276}