Skip to main content

tuwunel_service/integrity/
media_files.rs

1//! The files of `mediaid_file` rows in the media directory.
2//!
3//! A row's file is named by the base64 of its key's SHA-256 digest, or under the
4//! legacy naming by the base64 of the key itself. One check covers the rename
5//! from legacy names, the other the directory once that rename is stamped.
6
7use std::{
8	collections::HashSet,
9	ffi::OsString,
10	fmt,
11	fs::{Metadata, read_dir},
12	io::{self, ErrorKind},
13	path::{Path, PathBuf},
14};
15
16use futures::{Stream, TryStreamExt, stream::once};
17use tokio::fs::symlink_metadata;
18use tuwunel_core::{
19	Err, Result, err,
20	itertools::Itertools,
21	utils::{BoolExt, TryReadyExt, stream::TryBroadbandExt},
22};
23use tuwunel_database::KeyBuf;
24
25use super::{Check, Report, ScanExt, tally};
26use crate::{
27	Services,
28	migrations::{SHA256_MEDIA, marker_present},
29};
30
31type Files = HashSet<OsString>;
32
33pub(super) static LEGACY: Check = Check {
34	name: "legacy-media-names",
35	about: "Reports only while the sha256 media rename is unstamped: no mediaid_file row's \
36	        media is still a file under its legacy name",
37	quiescent: false,
38	walk: |services, limit| tally(legacy(services), limit),
39};
40
41pub(super) static CHECK: Check = Check {
42	name: "media-files",
43	about: "Reports only once the sha256 media rename is stamped: every mediaid_file row has an \
44	        entry in the media directory under its sha256 or legacy name; with compat_file_link \
45	        it has both, and without it the legacy name is no link",
46	quiescent: true,
47	walk: |services, limit| tally(scan(services), limit),
48};
49
50/// A `mediaid_file` row whose media is still a file under its legacy name.
51///
52/// The rename moves each such file to its sha256 name, and with
53/// `compat_file_link` links the legacy name to it. A link already there is the
54/// rename's own work, so it is not reported.
55pub struct Legacy {
56	/// The stored key.
57	pub key: KeyBuf,
58}
59
60/// A `mediaid_file` row the media directory disagrees with.
61///
62/// Each kind is a case the startup media check acts on. It deletes a row missing
63/// both names only with `prune_missing`, while this check reports one either way.
64pub enum Finding {
65	/// Neither name is in the directory.
66	Missing {
67		/// The stored key.
68		key: KeyBuf,
69	},
70
71	/// With `compat_file_link`, the sha256 name is in the directory but the
72	/// legacy name is not.
73	Unlinked {
74		/// The stored key.
75		key: KeyBuf,
76	},
77
78	/// With `compat_file_link`, the legacy name is in the directory but the
79	/// sha256 name is not.
80	Unmigrated {
81		/// The stored key.
82		key: KeyBuf,
83	},
84
85	/// Without `compat_file_link`, the legacy name is a link.
86	Linked {
87		/// The stored key.
88		key: KeyBuf,
89	},
90}
91
92/// A row's legacy name, and which of its two names the directory lists.
93///
94/// Only the legacy name's kind is ever read from the filesystem past the listing,
95/// so it is the one name kept.
96struct Entry {
97	key: KeyBuf,
98	legacy: PathBuf,
99	legacy_listed: bool,
100	sha256_listed: bool,
101}
102
103/// Streams each `mediaid_file` row whose media is still a file under its legacy
104/// name, only while the sha256 rename is unstamped.
105///
106/// The legacy name is read without following a link, so the link the rename
107/// leaves with `compat_file_link` is not reported. Once the rename is stamped
108/// the startup media check owns the directory, and [`scan`] reports it.
109#[tracing::instrument(level = "trace", skip_all)]
110pub fn legacy(services: &Services) -> impl Stream<Item = Result<Legacy>> + Send + '_ {
111	once(marker_present(services, SHA256_MEDIA))
112		.map_ok(move |renamed| renamed.is_false().then(|| keys(services)))
113		.ready_try_filter_map(Ok)
114		.try_flatten()
115		.broad_and_then(async |key| unrenamed(services, key).await)
116		.ready_try_filter_map(Ok)
117}
118
119/// Streams each `mediaid_file` row the media directory disagrees with, only
120/// once the sha256 rename is stamped.
121///
122/// Every row is judged against one listing of the directory, under the four
123/// cases the startup media check acts on. A directory that does not list, or a
124/// legacy name whose kind cannot be read, is an error rather than a finding.
125#[tracing::instrument(level = "trace", skip_all)]
126pub fn scan(services: &Services) -> impl Stream<Item = Result<Finding>> + Send + '_ {
127	let compat = services.server.config.media.compat_file_link;
128
129	once(files(services))
130		.ready_try_filter_map(Ok)
131		.map_ok(move |files| entries(services, files))
132		.try_flatten()
133		.broad_and_then(move |entry| classify(entry, compat))
134		.ready_try_filter_map(Ok)
135}
136
137/// Lists the media directory, naming each entry by `dir` joined with its name.
138///
139/// The startup media check and [`scan`] test a row's two names against this
140/// listing, so both read the directory alike. The startup check drops whatever
141/// fails to read, where [`scan`] fails on it.
142pub(crate) fn listing(dir: &Path) -> io::Result<impl Iterator<Item = io::Result<OsString>>> {
143	read_dir(dir).map(|entries| entries.map_ok(|entry| entry.path().into_os_string()))
144}
145
146impl Report for Legacy {
147	fn kind(&self) -> &'static str { "unrenamed-file" }
148}
149
150impl Report for Finding {
151	fn kind(&self) -> &'static str {
152		match self {
153			| Self::Missing { .. } => "missing-file",
154			| Self::Unlinked { .. } => "missing-link",
155			| Self::Unmigrated { .. } => "unmigrated-file",
156			| Self::Linked { .. } => "stale-link",
157		}
158	}
159}
160
161impl fmt::Display for Legacy {
162	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
163		write!(f, "media {} is still a file under its legacy name", self.key.escape_ascii())
164	}
165}
166
167impl fmt::Display for Finding {
168	fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
169		match self {
170			| Self::Missing { key } => {
171				write!(
172					f,
173					"media {} has neither its sha256 nor its legacy name",
174					key.escape_ascii()
175				)
176			},
177			| Self::Unlinked { key } => {
178				write!(f, "media {} has no link under its legacy name", key.escape_ascii())
179			},
180			| Self::Unmigrated { key } => {
181				write!(f, "media {} has its legacy name but no sha256 name", key.escape_ascii())
182			},
183			| Self::Linked { key } => write!(
184				f,
185				"media {} keeps a legacy link with compat_file_link off",
186				key.escape_ascii()
187			),
188		}
189	}
190}
191
192fn keys(services: &Services) -> impl Stream<Item = Result<KeyBuf>> + Send + '_ {
193	services.db["mediaid_file"]
194		.raw_scan()
195		.scanned(&services.server)
196		.map_ok(|(key, _)| KeyBuf::from_slice(key))
197}
198
199#[tracing::instrument(level = "debug", skip_all)]
200async fn unrenamed(services: &Services, key: KeyBuf) -> Result<Option<Legacy>> {
201	let path = services.media.get_media_path_b64(&key);
202
203	symlink_metadata(&path)
204		.await
205		.map(|meta| {
206			meta.is_symlink()
207				.is_false()
208				.then_some(Legacy { key })
209		})
210		.or_else(|error| match error.kind() {
211			| ErrorKind::NotFound => Ok(None),
212			| _ => Err!("cannot read {}: {error}", path.display()),
213		})
214}
215
216/// Lists the media directory once the sha256 rename is stamped.
217///
218/// Before then the rename owns the legacy names, so there is nothing to list.
219/// Any entry that fails to read fails the whole listing.
220#[tracing::instrument(level = "debug", skip_all)]
221async fn files(services: &Services) -> Result<Option<Files>> {
222	marker_present(services, SHA256_MEDIA)
223		.await?
224		.then(|| {
225			let dir = services.media.get_media_dir();
226
227			listing(&dir)
228				.and_then(Iterator::collect)
229				.map_err(|error| {
230					err!("cannot list the media directory {}: {error}", dir.display())
231				})
232		})
233		.transpose()
234}
235
236fn entries(services: &Services, files: Files) -> impl Stream<Item = Result<Entry>> + Send + '_ {
237	keys(services).map_ok(move |key| entry(services, &files, key))
238}
239
240fn entry(services: &Services, files: &Files, key: KeyBuf) -> Entry {
241	let sha256 = services
242		.media
243		.get_media_path_sha256(&key)
244		.into_os_string();
245
246	let legacy = services.media.get_media_path_b64(&key);
247
248	Entry {
249		legacy_listed: files.contains(legacy.as_os_str()),
250		sha256_listed: files.contains(&sha256),
251		legacy,
252		key,
253	}
254}
255
256/// Judges one row as the startup media check does, reading the legacy name's
257/// kind only where the check would.
258///
259/// A row missing both names is reported whatever `prune_missing` says, since
260/// that setting decides only whether the startup check deletes it.
261#[tracing::instrument(level = "debug", skip_all)]
262async fn classify(entry: Entry, compat: bool) -> Result<Option<Finding>> {
263	let Entry {
264		key,
265		legacy,
266		legacy_listed,
267		sha256_listed,
268	} = entry;
269
270	let finding = match (legacy_listed, sha256_listed) {
271		| (false, false) => Some(Finding::Missing { key }),
272		| (false, true) if compat => Some(Finding::Unlinked { key }),
273		| (true, false) if compat => Some(Finding::Unmigrated { key }),
274		| (true, _) if !compat => is_link(&legacy)
275			.await?
276			.then_some(Finding::Linked { key }),
277		| _ => None,
278	};
279
280	Ok(finding)
281}
282
283#[tracing::instrument(level = "debug", skip_all)]
284async fn is_link(path: &Path) -> Result<bool> {
285	symlink_metadata(path)
286		.await
287		.as_ref()
288		.map(Metadata::is_symlink)
289		.map_err(|error| err!("cannot read {}: {error}", path.display()))
290}