2bc41aeb8602
rules.rs
//! Where a folder search goes: not into other apps' or the system's folders. They are told by
//! their names and places (an app package, a home folder's `Library` or `AppData`, the system
//! folders at the root of a volume), never by the name of an app. Names and paths compare in
//! lowercase.
use std::path::{Component, Path, PathBuf};
/// Extensions of the packages apps and media libraries keep their files in.
const PACKAGE_EXTENSIONS: &[&str] = &[
"app",
"appex",
"bundle",
"component",
"fcpbundle",
"framework",
"imovielibrary",
"kext",
"musiclibrary",
"photolibrary",
"photoslibrary",
"plugin",
"tvlibrary",
"xpc",
];
/// The folders Windows installs programs and keeps their data and the system's in, wherever they
/// are.
const INSTALL_FOLDERS: &[&str] =
&["program files", "program files (x86)", "program files (arm)", "programdata", "$recycle.bin", "system volume information"];
/// The folders a home folder keeps apps and their data in (besides its hidden ones).
const HOME_APP_FOLDERS: &[&str] = &["library", "appdata", "applications", "snap"];
/// The folders a `Library` folder keeps apps' data in (macOS).
const LIBRARY_APP_FOLDERS: &[&str] = &["application support", "containers", "group containers", "caches", "preferences"];
/// The folders beside the home folders that apps share (macOS `Shared`, Windows `Public`).
const SHARED_FOLDERS: &[&str] = &["shared", "public"];
/// The system's folders at the root of a macOS volume (or a copy of one).
const MAC_SYSTEM: &[&str] =
&["applications", "bin", "cores", "dev", "etc", "home", "library", "net", "network", "opt", "private", "sbin", "system", "tmp", "usr", "var"];
/// The system's folders at the root of a Linux or BSD system (or a copy of one).
const UNIX_SYSTEM: &[&str] = &[
"bin",
"boot",
"dev",
"efi",
"etc",
"gnu",
"lib",
"lib32",
"lib64",
"libx32",
"lost+found",
"nix",
"opt",
"proc",
"root",
"run",
"sbin",
"snap",
"sys",
"usr",
"var",
];
/// The system's folders at the root of a Windows drive (or a copy of one), besides the install
/// folders.
const WINDOWS_SYSTEM: &[&str] =
&["windows", "windows.old", "recovery", "perflogs", "boot", "config.msi", "msocache", "$windows.~bt", "$windows.~ws", "$winreagent", "$sysreset"];
/// The most entries of a folder read to tell what kind of folder it is.
const MAX_SIBLINGS: usize = 100_000;
/// The names of the folders that show a folder is the root of a system ([`system_folders`]).
const SYSTEM_SIGNS: &[&str] = &["users", "system", "library", "applications", "windows", "program files", "etc", "usr", "bin", "sbin"];
/// Which of [`SYSTEM_SIGNS`] are among the names of a folder's folders and links.
#[derive(Clone, Copy, Debug, Default, PartialEq, Eq)]
pub(crate) struct Siblings(u16);
impl Siblings {
/// The folders and links named `names` (in any case).
#[cfg(test)]
pub(crate) fn of(names: &[&str]) -> Self {
let mut s = Self::default();
names.iter().for_each(|n| s.note(n));
s
}
/// Note a folder or link named `name` (in any case).
pub(crate) fn note(&mut self, name: &str) {
if let Some(i) = SYSTEM_SIGNS.iter().position(|s| s.eq_ignore_ascii_case(name)) {
self.0 |= 1 << i;
}
}
/// Whether a folder or link named `name`, one of [`SYSTEM_SIGNS`], was noted.
fn has(self, name: &str) -> bool {
SYSTEM_SIGNS.iter().position(|s| *s == name).is_some_and(|i| self.0 & (1 << i) != 0)
}
}
/// Why a search may not start in a folder ([`Rules::refusal`]).
#[derive(Clone, Copy, Debug, PartialEq, Eq)]
pub(crate) enum Refusal {
/// The folder is in other apps' or the system's folders, or in an app package.
Apps,
/// The folder is in the Shared or Public folder of a `Users` folder.
Shared,
}
/// A folder a walk lists, as the rules see it ([`Rules::listed`]).
pub(crate) struct Listed {
/// The folder, in lowercase.
dir: PathBuf,
/// Its name, in lowercase.
name: String,
/// The system folders in it, when it is the root of a system.
system: Option<&'static [&'static str]>,
/// It is a home folder.
home: bool,
}
/// Where a search may go.
#[derive(Clone, Debug, Default)]
pub struct Rules {
/// The home folder (canonical).
pub home: Option<PathBuf>,
/// Folders searched when picked, whatever holds them (canonical): the temporary folders, and
/// tests' folders.
pub user_content: Vec<PathBuf>,
/// Other apps' and the system's folders the environment names (canonical): never entered, and a
/// search of a folder inside one fails.
pub refused: Vec<PathBuf>,
}
/// `path` in lowercase and, on Windows, without its `\\?\` prefix ([`unprefixed`]), for comparing
/// paths.
fn lower(path: &Path) -> PathBuf {
let text = path.to_string_lossy();
let plain = if cfg!(windows) { unprefixed(&text) } else { None };
PathBuf::from(plain.as_deref().unwrap_or(&text).to_lowercase())
}
/// The system's folders a volume's root holds, when its folders (`siblings`) show it is the root of
/// an operating system.
fn system_folders(siblings: Siblings) -> Option<&'static [&'static str]> {
let has = |name: &str| siblings.has(name);
if has("users") && (has("system") || has("library") || has("applications")) {
Some(MAC_SYSTEM)
} else if has("windows") && (has("users") || has("program files")) {
Some(WINDOWS_SYSTEM)
} else if has("etc") && has("usr") && (has("bin") || has("sbin")) {
Some(UNIX_SYSTEM)
} else {
None
}
}
/// What the names of the folders and links in `dir` show ([`Siblings`]).
fn folder_siblings(dir: &Path) -> Siblings {
let mut siblings = Siblings::default();
for e in std::fs::read_dir(dir).into_iter().flatten().take(MAX_SIBLINGS).flatten() {
let name = e.file_name();
if let Some(name) = name.to_str()
&& e.file_type().is_ok_and(|t| t.is_dir() || t.is_symlink())
{
siblings.note(name);
}
}
siblings
}
/// The first `n` components of `path`.
fn prefix(path: &Path, n: usize) -> PathBuf {
path.components().take(n).collect()
}
/// `path` without the `\\?\` prefix that `std::fs::canonicalize` gives paths on Windows: `C:\…`
/// for `\\?\C:\…` and `\\server\share\…` for `\\?\UNC\server\share\…`, when every name in it can
/// be written without the prefix ([`without_verbatim`]). Other paths, and paths on other systems,
/// are returned as they are.
pub fn plain(path: PathBuf) -> PathBuf {
if !cfg!(windows) {
return path;
}
match path.to_str().and_then(without_verbatim) {
Some(p) => PathBuf::from(p),
None => path,
}
}
/// The Windows path `p` without its `\\?\` prefix, when it has one for a drive or a share: `C:\…`
/// for `\\?\C:\…` and `\\server\…` for `\\?\UNC\server\…`.
pub(crate) fn unprefixed(p: &str) -> Option<String> {
if let Some(unc) = p.strip_prefix(r"\\?\UNC\") {
return Some(format!(r"\\{unc}"));
}
let disk = p.strip_prefix(r"\\?\")?;
matches!(disk.as_bytes(), [d, b':', b'\\', ..] if d.is_ascii_alphabetic()).then(|| disk.to_string())
}
/// [`unprefixed`], when each name in the path can be written without the prefix ([`portable`]):
/// a share's server and share names, and the names below a drive's root or a share.
pub(crate) fn without_verbatim(p: &str) -> Option<String> {
let plain = unprefixed(p)?;
let (names, at_least) = match plain.strip_prefix(r"\\") {
Some(unc) => (unc, 2),
None => (plain.get(3..)?, 0),
};
let mut names: Vec<&str> = if names.is_empty() { vec![] } else { names.split('\\').collect() };
// A trailing separator.
if names.len() > at_least && names.last() == Some(&"") {
names.pop();
}
let ok = names.len() >= at_least && names.iter().all(|n| portable(n));
ok.then_some(plain)
}
/// Whether `name` can be a name in a Windows path without the `\\?\` prefix: not `.` or `..`, not
/// ending in a dot or a space, without `<>:"/\|?*` or control characters, and not a device name
/// (`CON`, `PRN`, `AUX`, `NUL`, `COM0` to `COM9`, `LPT0` to `LPT9`, these with a superscript digit,
/// `CONIN$`, `CONOUT$`), with an extension or not.
fn portable(name: &str) -> bool {
let stem = name.split('.').next().unwrap_or(name).trim_end().to_ascii_lowercase();
let numbered = |device: &str| {
stem.strip_prefix(device).is_some_and(|n| {
let mut n = n.chars();
n.next().is_some_and(|c| c.is_ascii_digit() || "¹²³".contains(c)) && n.next().is_none()
})
};
let device = ["con", "prn", "aux", "nul", "conin$", "conout$"].contains(&stem.as_str()) || numbered("com") || numbered("lpt");
!name.is_empty()
&& name != "."
&& name != ".."
&& !name.ends_with(['.', ' '])
&& !name.chars().any(|c| c < ' ' || "<>:\"/\\|?*".contains(c))
&& !device
}
impl Rules {
/// This computer's: the home folder, the temporary folders, and the app and system folders the
/// environment names.
pub fn system() -> Self {
let canonical = |p: PathBuf| p.is_absolute().then(|| std::fs::canonicalize(&p).ok()).flatten();
let var = |name: &str| std::env::var_os(name).map(PathBuf::from).and_then(canonical);
let home = var(if cfg!(windows) { "USERPROFILE" } else { "HOME" });
let user_content = [std::env::temp_dir(), PathBuf::from("/tmp")].into_iter().filter_map(canonical).collect();
let names: &[&str] = if cfg!(windows) {
&["APPDATA", "LOCALAPPDATA", "ProgramData", "ProgramFiles", "ProgramFiles(x86)", "ProgramW6432", "SystemRoot"]
} else {
&[
"XDG_CONFIG_HOME",
"XDG_DATA_HOME",
"XDG_CACHE_HOME",
"XDG_STATE_HOME",
"HOST_XDG_CONFIG_HOME",
"HOST_XDG_DATA_HOME",
"HOST_XDG_CACHE_HOME",
"HOST_XDG_STATE_HOME",
]
};
let refused = names.iter().filter_map(|n| var(n)).collect();
Rules { home, user_content, refused }
}
/// Whether `dir` is a home folder: the home folder, a folder in a `Users` or `home` folder, or
/// a folder the Flatpak document portal exports (`/run/user/<uid>/doc/<id>/<name>`).
fn is_home(&self, dir: &Path) -> bool {
if self.home.as_ref().is_some_and(|h| lower(h) == lower(dir)) {
return true;
}
let above = dir.parent().and_then(Path::file_name).map(|n| n.to_string_lossy().to_lowercase());
if matches!(above.as_deref(), Some("users" | "home")) {
return true;
}
let parts: Vec<String> = dir.components().map(|c| c.as_os_str().to_string_lossy().to_lowercase()).collect();
matches!(parts.as_slice(), [_, run, user, uid, doc, _, _] if run == "run" && user == "user" && is_number(uid) && doc == "doc")
}
/// The folder `dir`, whose folders show `siblings`, as the rules see it when a walk lists it:
/// told once for all the folders in it.
pub(crate) fn listed(&self, dir: &Path, siblings: Siblings) -> Listed {
Listed {
dir: lower(dir),
name: dir.file_name().map(|n| n.to_string_lossy().to_lowercase()).unwrap_or_default(),
system: system_folders(siblings),
home: self.is_home(dir),
}
}
/// Whether a search never enters the folder `name` in the listed folder `parent`: an app's
/// package, a Windows install folder, a system folder at the root of a volume, the folders apps
/// share beside the home folders, a `Library` folder's app data, or a home folder's hidden
/// folders and app folders.
pub(crate) fn never_in(&self, parent: &Listed, name: &str) -> bool {
let name = name.to_lowercase();
let name = name.as_str();
if Path::new(name).extension().and_then(|e| e.to_str()).is_some_and(|e| PACKAGE_EXTENSIONS.contains(&e)) || INSTALL_FOLDERS.contains(&name) {
return true;
}
if parent.system.is_some_and(|system| system.contains(&name)) {
return true;
}
match parent.name.as_str() {
"users" if SHARED_FOLDERS.contains(&name) => return true,
"library" if LIBRARY_APP_FOLDERS.contains(&name) => return true,
_ => {}
}
parent.home && (name.starts_with('.') || HOME_APP_FOLDERS.contains(&name))
}
/// [`Self::never_in`] the folder `parent`, whose folders show `siblings`.
#[cfg(test)]
pub(crate) fn never(&self, parent: &Path, siblings: Siblings, name: &str) -> bool {
self.never_in(&self.listed(parent, siblings), name)
}
/// The home folder, when the listed folder `parent` is the root of a system whose rules skip
/// the folder the home folder is in (`/usr/home/me` on FreeBSD, `/var/home/me`): a walk of the
/// root reaches it this way.
pub(crate) fn home_below(&self, parent: &Listed) -> Option<PathBuf> {
let home = self.home.as_ref()?;
let system = parent.system?;
let below = lower(home).strip_prefix(&parent.dir).ok()?.components().next()?.as_os_str().to_string_lossy().into_owned();
system.contains(&below.as_str()).then(|| home.clone())
}
/// Whether `path` is one of the refused folders.
pub(crate) fn is_refused(&self, path: &Path) -> bool {
let path = lower(path);
self.refused.iter().any(|r| lower(r) == path)
}
/// The folders that hold user content whatever holds them, as far as they hold `folder`: the
/// home folder, [`Self::user_content`], the cloud storage folders in the home folder's
/// `Library` (an app's own iCloud `Documents` folder too), removable media and a user's runtime
/// folder on Linux (network shares, the document portal).
fn bases(&self, folder: &Path) -> Vec<PathBuf> {
let mut v = self.user_content.clone();
let lowered = lower(folder);
if let Some(home) = &self.home {
v.push(home.clone());
let library = home.join("Library");
v.push(library.join("CloudStorage"));
let mobile = library.join("Mobile Documents");
v.push(mobile.join("com~apple~CloudDocs"));
let depth = mobile.components().count();
if lowered.starts_with(lower(&mobile)) && lowered.components().nth(depth + 1).is_some_and(|c| c.as_os_str() == "documents") {
v.push(prefix(folder, depth + 2));
}
}
v.push(PathBuf::from("/run/media"));
let parts: Vec<String> = folder.components().take(4).map(|c| c.as_os_str().to_string_lossy().to_lowercase()).collect();
if matches!(parts.as_slice(), [_, run, user, uid] if run == "run" && user == "user" && is_number(uid)) {
v.push(prefix(folder, 4));
}
v
}
/// Why a search may not start in `folder` (canonical), or `None` when it may: the deepest base
/// ([`Self::bases`]) or refused folder that holds it is a refused one, or a folder below that
/// base (or below the root, without one) is one a walk doesn't enter.
pub(crate) fn refusal(&self, folder: &Path) -> Option<Refusal> {
self.refusal_with(folder, folder_siblings)
}
/// [`Self::refusal`] without listing a folder: the root of a system, told by the folders it
/// holds, isn't recognized.
pub(crate) fn refusal_unlisted(&self, folder: &Path) -> Option<Refusal> {
self.refusal_with(folder, |_| Siblings::default())
}
/// [`Self::refusal`], with `siblings` telling what a folder's folders show.
fn refusal_with(&self, folder: &Path, siblings: impl Fn(&Path) -> Siblings) -> Option<Refusal> {
let lowered = lower(folder);
let held = |p: &PathBuf| lowered.starts_with(lower(p)).then(|| p.components().count());
let base = self.bases(folder).iter().filter_map(held).max();
let refused = self.refused.iter().filter_map(held).max();
let start = match (base, refused) {
(_, Some(r)) if base.is_none_or(|b| r >= b) => return Some(Refusal::Apps),
(Some(b), _) => b,
// From the root of the folder's volume.
(None, _) => folder.components().take_while(|c| matches!(c, Component::Prefix(_) | Component::RootDir)).count(),
};
let mut parent = prefix(folder, start);
for c in folder.components().skip(start) {
let child = parent.join(c);
let listed = self.listed(&parent, siblings(&parent));
let name = c.as_os_str().to_string_lossy().to_lowercase();
if listed.name == "users" && SHARED_FOLDERS.contains(&name.as_str()) {
return Some(Refusal::Shared);
}
if self.never_in(&listed, &name) || self.is_refused(&child) {
return Some(Refusal::Apps);
}
parent = child;
}
None
}
}
/// Whether `s` is a number (a user id).
fn is_number(s: &str) -> bool {
!s.is_empty() && s.bytes().all(|b| b.is_ascii_digit())
}
No file is open. Choose one in the tree, or press Ctrl+O (⌘O on a Mac) to find one by name.
Syntax highlighting could not load. The unmodified read-only text remains available above.