#![cfg_attr(
not(any(unix, windows)),
allow(
unused_variables,
dead_code,
reason = "with no strategy no tree is built, so the calls are compiled but never reached"
)
)]
use std::fs::Metadata;
use std::io::Read;
use std::path::{Path, PathBuf};
use super::{Entry, EntryKind, FileId, Opened, Tree};
use crate::error::TreeError;
use crate::path::RelPath;
mod capture;
pub use capture::{CapturedDirectory, CapturedFile, CapturedLink};
pub(super) fn canonical_root(root: &Path) -> std::io::Result<PathBuf> {
std::fs::canonicalize(root)
}
#[cfg(test)]
type Hook = Box<dyn Fn() + Send + Sync>;
macro_rules! hook {
($tree:expr, $hook:ident) => {
#[cfg(test)]
if let Some(hook) = &$tree.$hook {
hook();
}
};
}
macro_rules! each {
($handle:expr, $inner:ident => $body:expr) => {
match *$handle {
#[cfg(target_os = "linux")]
Handle::Linux(ref $inner) => $body,
#[cfg(all(unix, not(target_os = "linux")))]
Handle::OtherUnix(ref $inner) => $body,
#[cfg(windows)]
Handle::Windows(ref $inner) => $body,
}
};
}
#[cfg(windows)]
mod final_path;
#[cfg(windows)]
mod handle_path;
#[cfg(target_os = "linux")]
mod linux;
#[cfg(all(unix, not(target_os = "linux")))]
mod other_unix;
#[cfg(unix)]
mod unix_root;
#[cfg(all(test, any(unix, windows)))]
mod tests;
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Strategy {
#[cfg(target_os = "linux")]
Linux,
#[cfg(all(unix, not(target_os = "linux")))]
OtherUnix,
#[cfg(windows)]
Windows,
}
impl Strategy {
#[cfg(target_os = "linux")]
#[expect(
clippy::unnecessary_wraps,
reason = "the signature is shared with the platforms that have no strategy"
)]
fn native(_shown: &str) -> Result<Self, TreeError> {
Ok(Self::Linux)
}
#[cfg(all(unix, not(target_os = "linux")))]
#[expect(
clippy::unnecessary_wraps,
reason = "the signature is shared with the platforms that have no strategy"
)]
fn native(_shown: &str) -> Result<Self, TreeError> {
Ok(Self::OtherUnix)
}
#[cfg(windows)]
#[expect(
clippy::unnecessary_wraps,
reason = "the signature is shared with the platforms that have no strategy"
)]
fn native(_shown: &str) -> Result<Self, TreeError> {
Ok(Self::Windows)
}
#[cfg(not(any(unix, windows)))]
fn native(shown: &str) -> Result<Self, TreeError> {
Err(TreeError::Io {
path: shown.to_owned(),
source: std::io::Error::new(
std::io::ErrorKind::Unsupported,
"this platform cannot verify a handle against the root",
),
})
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
enum Want {
File,
Dir,
Listing,
}
impl Want {
fn require(self, metadata: &Metadata, shown: &str) -> Result<(), TreeError> {
let file_type = metadata.file_type();
let fits = match self {
Self::File => file_type.is_file(),
Self::Dir | Self::Listing => file_type.is_dir(),
};
if fits {
Ok(())
} else {
Err(not_regular(shown))
}
}
}
enum Handle {
#[cfg(target_os = "linux")]
Linux(linux::Handle),
#[cfg(all(unix, not(target_os = "linux")))]
OtherUnix(other_unix::Handle),
#[cfg(windows)]
Windows(handle_path::Handle),
}
impl Handle {
fn metadata(&self, shown: &str) -> Result<Metadata, TreeError> {
each!(self, inner => inner.metadata(shown))
}
fn link(
&self,
name: &str,
shown: &str,
between: impl FnOnce(),
) -> Result<(FileId, PathBuf), TreeError> {
each!(self, inner => inner.link(name, shown, between))
}
fn identity(&self, root: &Path, shown: &str) -> Result<FileId, TreeError> {
each!(self, inner => inner.identity(root, shown))
}
fn read(&self, max_bytes: u64, shown: &str) -> Result<Vec<u8>, TreeError> {
each!(self, inner => inner.read(max_bytes, shown))
}
fn entries(&self, shown: &str) -> Result<Vec<Entry>, TreeError> {
self.entries_bounded(shown, usize::MAX)
}
fn entries_bounded(&self, shown: &str, max_entries: usize) -> Result<Vec<Entry>, TreeError> {
each!(self, inner => inner.entries(shown, max_entries))
}
fn lookup(&self, name: &str, shown: &str) -> Result<Option<EntryKind>, TreeError> {
each!(self, inner => inner.lookup(name, shown))
}
fn recheck(&self, tree: &DiskTree, shown: &str) -> Result<(), TreeError> {
match *self {
#[cfg(target_os = "linux")]
Handle::Linux(ref inner) => inner.recheck(tree, shown),
#[cfg(all(unix, not(target_os = "linux")))]
Handle::OtherUnix(ref inner) => inner.recheck(&tree.root_directory, shown),
#[cfg(windows)]
Handle::Windows(ref inner) => inner.recheck(&tree.root, shown),
}
}
}
#[cfg(all(test, unix))]
fn never_blocks(flags: u32) -> bool {
#[cfg(target_os = "linux")]
let path = libc::O_PATH.cast_unsigned();
#[cfg(not(target_os = "linux"))]
let path = 0;
flags & (path | libc::O_NONBLOCK.cast_unsigned()) != 0
}
pub struct DiskTree {
root: PathBuf,
strategy: Strategy,
#[cfg(unix)]
root_directory: unix_root::Root,
#[cfg(test)]
before_open: Option<Hook>,
#[cfg(test)]
after_open: Option<Hook>,
#[cfg(test)]
after_verify: Option<Hook>,
#[cfg(test)]
after_observation: Option<Hook>,
#[cfg(all(test, unix, not(target_os = "linux")))]
mid_step: Option<Hook>,
#[cfg(all(test, unix))]
opens: std::sync::Mutex<Vec<u32>>,
}
impl std::fmt::Debug for DiskTree {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("DiskTree")
.field("root", &self.root)
.finish_non_exhaustive()
}
}
impl DiskTree {
pub(crate) fn root_path_bytes(&self) -> usize {
self.root.as_os_str().len()
}
fn directory_identity(&self, path: &RelPath) -> Result<FileId, TreeError> {
let shown = path.to_string();
let handle = self.open(path, Want::Dir, &shown)?;
self.used(&handle, &shown, |handle| {
handle.identity(&self.root, &shown)
})
}
pub(crate) fn dependency_directory_matches(
&self,
base_manifest: &RelPath,
relative: &str,
destination: &Self,
destination_manifest: &RelPath,
) -> Result<bool, TreeError> {
super::require_first_party(base_manifest)?;
super::require_first_party(destination_manifest)?;
let missing_parent = |path: &RelPath| TreeError::NotRegular {
path: path.to_string(),
};
let base = base_manifest
.parent()
.ok_or_else(|| missing_parent(base_manifest))?;
let target = destination_manifest
.parent()
.ok_or_else(|| missing_parent(destination_manifest))?;
let before = self.directory_identity(&base)?;
let declared = self.directory_tree_at(&PathBuf::from(base.as_str()).join(relative))?;
let expected = declared.directory_identity(&RelPath::root())?;
let target_identity = destination.directory_identity(&target)?;
let actual = destination.directory_tree_at(Path::new(target.as_str()))?;
let same_directory = actual.directory_identity(&RelPath::root())? == target_identity
&& expected == target_identity
&& declared.root == actual.root;
if self.directory_identity(&base)? != before {
return Err(TreeError::from_io(
&base_manifest.to_string(),
std::io::Error::other("owning directory changed while checking a reference path"),
));
}
Ok(same_directory)
}
pub fn new(root: impl AsRef<Path>) -> Result<Self, TreeError> {
let given = root.as_ref();
let shown = given.display().to_string();
let root = canonical_root(given).map_err(|e| TreeError::from_io(&shown, e))?;
let metadata = std::fs::metadata(&root).map_err(|e| TreeError::from_io(&shown, e))?;
Self::from_observed_root(root, &metadata, &shown)
}
fn from_observed_root(
root: PathBuf,
metadata: &Metadata,
shown: &str,
) -> Result<Self, TreeError> {
if !metadata.is_dir() {
return Err(TreeError::NotRegular { path: shown.into() });
}
let strategy = Strategy::native(shown)?;
#[cfg(unix)]
let root_directory = unix_root::Root::open(&root, shown)?;
#[cfg(target_os = "linux")]
if root_directory.identity() != device_identity(metadata) {
return Err(outside(shown));
}
let tree = Self::from_parts(
root,
strategy,
#[cfg(unix)]
root_directory,
);
#[cfg(target_os = "linux")]
linux::verify_root(&tree, shown)?;
Ok(tree)
}
fn from_parts(
root: PathBuf,
strategy: Strategy,
#[cfg(unix)] root_directory: unix_root::Root,
) -> Self {
Self {
root,
strategy,
#[cfg(unix)]
root_directory,
#[cfg(test)]
before_open: None,
#[cfg(test)]
after_open: None,
#[cfg(test)]
after_verify: None,
#[cfg(test)]
after_observation: None,
#[cfg(all(test, unix, not(target_os = "linux")))]
mid_step: None,
#[cfg(all(test, unix))]
opens: std::sync::Mutex::new(Vec::new()),
}
}
#[cfg(target_os = "linux")]
pub fn directory_handle(&self) -> Result<std::fs::File, TreeError> {
linux::verify_root(self, &self.root.display().to_string())?;
self.root_directory
.dir
.try_clone()
.map(std::fs::File::from)
.map_err(|e| TreeError::from_io(&self.root.display().to_string(), e))
}
fn directory_tree_at(&self, path: &Path) -> Result<Self, TreeError> {
#[cfg(target_os = "linux")]
{
let shown = path.display().to_string();
let relative = if path.as_os_str().is_empty() {
Path::new(".")
} else {
path
};
let root_directory =
unix_root::Root::open_at(&self.root_directory.dir, relative, &shown)?;
let root = std::fs::read_link(descriptor_path(&root_directory.dir))
.map_err(|e| link_read_error(&shown, e))?;
Ok(Self::from_parts(root, self.strategy, root_directory))
}
#[cfg(not(target_os = "linux"))]
Self::new(self.root.join(path))
}
pub(crate) fn byte_len(&self, path: &RelPath) -> Result<u64, TreeError> {
super::require_first_party(path)?;
let shown = path.to_string();
let handle = self.open(path, Want::File, &shown)?;
self.used(&handle, &shown, |handle| Ok(handle.metadata(&shown)?.len()))
}
pub fn read_unseen_bytes(
&self,
path: &RelPath,
max_bytes: u64,
seen: &dyn Fn(&FileId) -> bool,
) -> Result<super::OpenedBytes, TreeError> {
super::require_first_party(path)?;
let shown = path.to_string();
let handle = self.open(path, Want::File, &shown)?;
let id = handle.identity(&self.root, &shown)?;
if seen(&id) {
return Ok(super::OpenedBytes::Seen(id));
}
let bytes = self.used(&handle, &shown, |handle| handle.read(max_bytes, &shown))?;
Ok(super::OpenedBytes::Read { id, bytes })
}
#[cfg(all(test, unix))]
fn note_open(&self, flags: u32) {
assert!(
never_blocks(flags),
"an open of a name below the root could block: flags {flags:#o}"
);
self.opens.lock().expect("the open record").push(flags);
}
#[cfg(all(test, unix))]
fn recorded_opens(&self) -> Vec<u32> {
self.opens.lock().expect("the open record").clone()
}
#[cfg(any(target_os = "linux", windows))]
fn candidate(&self, path: &RelPath) -> PathBuf {
#[cfg(target_os = "linux")]
let root = descriptor_path(&self.root_directory.dir).join(".");
#[cfg(windows)]
let root = self.root.clone();
if path.is_root() {
root
} else {
root.join(path.as_str())
}
}
#[cfg(any(target_os = "linux", windows))]
fn contain(&self, candidate: &Path, shown: &str) -> Result<PathBuf, TreeError> {
let canonical =
std::fs::canonicalize(candidate).map_err(|e| TreeError::from_io(shown, e))?;
if canonical.starts_with(&self.root) {
Ok(canonical)
} else {
Err(outside(shown))
}
}
fn open(&self, path: &RelPath, want: Want, shown: &str) -> Result<Handle, TreeError> {
refuse_windows_names(path, shown)?;
match self.strategy {
#[cfg(target_os = "linux")]
Strategy::Linux => linux::open(self, path, want, shown).map(Handle::Linux),
#[cfg(all(unix, not(target_os = "linux")))]
Strategy::OtherUnix => other_unix::open(self, path, want, shown).map(Handle::OtherUnix),
#[cfg(windows)]
Strategy::Windows => handle_path::open(self, path, want, shown).map(Handle::Windows),
}
}
fn used<T>(
&self,
handle: &Handle,
shown: &str,
work: impl FnOnce(&Handle) -> Result<T, TreeError>,
) -> Result<T, TreeError> {
hook!(self, after_verify);
let result = work(handle);
handle.recheck(self, shown)?;
result
}
#[cfg(test)]
fn observed(&self) {
hook!(self, after_observation);
}
}
impl Tree for DiskTree {
fn read(&self, path: &RelPath, max_bytes: u64) -> Result<String, TreeError> {
text(self.read_bytes(path, max_bytes)?, path)
}
fn read_bytes(&self, path: &RelPath, max_bytes: u64) -> Result<Vec<u8>, TreeError> {
super::require_first_party(path)?;
let shown = path.to_string();
let handle = self.open(path, Want::File, &shown)?;
self.used(&handle, &shown, |handle| handle.read(max_bytes, &shown))
}
fn read_unseen(
&self,
path: &RelPath,
max_bytes: u64,
seen: &dyn Fn(&FileId) -> bool,
) -> Result<Opened, TreeError> {
match self.read_unseen_bytes(path, max_bytes, seen)? {
super::OpenedBytes::Seen(id) => Ok(Opened::Seen(id)),
super::OpenedBytes::Read { id, bytes } => Ok(Opened::Read {
id,
text: text(bytes, path)?,
}),
}
}
fn list(&self, path: &RelPath) -> Result<Vec<Entry>, TreeError> {
super::require_first_party(path)?;
let shown = path.to_string();
let handle = self.open(path, Want::Listing, &shown)?;
let mut entries = self.used(&handle, &shown, |handle| handle.entries(&shown))?;
entries.sort();
Ok(entries)
}
fn entry(&self, path: &RelPath) -> Result<Option<EntryKind>, TreeError> {
super::require_first_party(path)?;
let shown = path.to_string();
refuse_windows_names(path, &shown)?;
let (Some(name), Some(parent)) = (path.file_name(), path.parent()) else {
return Ok(Some(EntryKind::Dir));
};
let climbs = name == "..";
let directory = if climbs { path } else { &parent };
let handle = match self.open(directory, Want::Dir, &shown) {
Ok(handle) => handle,
Err(TreeError::NotFound { .. } | TreeError::NotRegular { .. }) => return Ok(None),
Err(other) => return Err(other),
};
self.used(&handle, &shown, |handle| {
if climbs {
Ok(Some(EntryKind::Dir))
} else {
handle.lookup(name, &shown)
}
})
}
}
#[cfg(any(target_os = "linux", windows))]
fn kind_of(file_type: std::fs::FileType) -> EntryKind {
if file_type.is_symlink() {
EntryKind::Symlink
} else if file_type.is_dir() {
EntryKind::Dir
} else if file_type.is_file() {
EntryKind::File
} else {
EntryKind::Other
}
}
#[cfg(any(target_os = "linux", windows))]
fn lookup(path: &Path, shown: &str) -> Result<Option<EntryKind>, TreeError> {
match std::fs::symlink_metadata(path) {
Ok(metadata) => Ok(Some(kind_of(metadata.file_type()))),
Err(e)
if matches!(
e.kind(),
std::io::ErrorKind::NotFound | std::io::ErrorKind::NotADirectory
) =>
{
Ok(None)
}
Err(e) => Err(TreeError::from_io(shown, e)),
}
}
#[cfg(any(target_os = "linux", windows))]
fn read_entries(listing: &Path, shown: &str, max_entries: usize) -> Result<Vec<Entry>, TreeError> {
let mut entries = Vec::new();
for item in std::fs::read_dir(listing).map_err(|e| TreeError::from_io(shown, e))? {
let item = item.map_err(|e| TreeError::from_io(shown, e))?;
entry_room(entries.len(), max_entries, shown)?;
let name = item
.file_name()
.into_string()
.map_err(|raw| TreeError::NonUtf8Name {
path: shown.to_owned(),
name: raw.to_string_lossy().into_owned(),
})?;
let file_type = item.file_type().map_err(|e| TreeError::from_io(shown, e))?;
entries.push(Entry {
name,
kind: kind_of(file_type),
});
}
Ok(entries)
}
fn entry_room(count: usize, max_entries: usize, shown: &str) -> Result<(), TreeError> {
if count < max_entries {
Ok(())
} else {
Err(TreeError::from_io(
shown,
std::io::Error::new(
std::io::ErrorKind::InvalidData,
format!(
"directory entry limit {max_entries} exceeded; increase the admitted capture budget"
),
),
))
}
}
#[cfg(any(target_os = "linux", windows))]
fn refuse_unless_directory(candidate: &Path, shown: &str) -> Result<(), TreeError> {
let own = std::fs::symlink_metadata(candidate).map_err(|e| TreeError::from_io(shown, e))?;
if own.is_dir() {
Ok(())
} else {
Err(not_regular(shown))
}
}
#[cfg(any(target_os = "linux", windows))]
fn open_error(shown: &str, error: std::io::Error) -> TreeError {
if crate::error::is_symlink_loop(&error) {
not_regular(shown)
} else {
TreeError::from_io(shown, error)
}
}
#[cfg(any(target_os = "linux", windows))]
fn link_read_error(shown: &str, source: std::io::Error) -> TreeError {
TreeError::Io {
path: shown.to_owned(),
source,
}
}
#[cfg(any(target_os = "linux", windows))]
fn verify_handle_path(root: &Path, handle_path: &Path, shown: &str) -> Result<(), TreeError> {
if handle_path.starts_with(root) {
Ok(())
} else {
Err(outside(shown))
}
}
#[cfg(target_os = "linux")]
fn verify_linux_link(root: &Path, handle_link: &Path, shown: &str) -> Result<(), TreeError> {
let target = std::fs::read_link(handle_link).map_err(|e| link_read_error(shown, e))?;
verify_handle_path(root, &target, shown)
}
#[cfg(target_os = "linux")]
fn descriptor_path(handle: &impl std::os::fd::AsRawFd) -> PathBuf {
PathBuf::from(format!("/proc/self/fd/{}", handle.as_raw_fd()))
}
fn read_capped(source: impl Read, max_bytes: u64, shown: &str) -> Result<Vec<u8>, TreeError> {
let mut bytes = Vec::new();
source
.take(max_bytes.saturating_add(1))
.read_to_end(&mut bytes)
.map_err(|e| TreeError::from_io(shown, e))?;
if u64::try_from(bytes.len()).map_or(true, |len| len > max_bytes) {
return Err(TreeError::TooLarge {
path: shown.to_owned(),
limit: max_bytes,
});
}
Ok(bytes)
}
fn text(bytes: Vec<u8>, path: &RelPath) -> Result<String, TreeError> {
String::from_utf8(bytes).map_err(|_| TreeError::NotUtf8 {
path: path.to_string(),
})
}
fn outside(shown: &str) -> TreeError {
TreeError::OutsideRoot {
path: shown.to_owned(),
}
}
fn not_regular(shown: &str) -> TreeError {
TreeError::NotRegular {
path: shown.to_owned(),
}
}
#[cfg(unix)]
fn device_identity(metadata: &Metadata) -> FileId {
use std::os::unix::fs::MetadataExt as _;
FileId::from_device(metadata.dev(), metadata.ino())
}
#[cfg(windows)]
fn refuse_windows_names(path: &RelPath, shown: &str) -> Result<(), TreeError> {
if path.segments().any(is_ambiguous_on_windows) {
Err(outside(shown))
} else {
Ok(())
}
}
#[cfg(not(windows))]
#[expect(
clippy::unnecessary_wraps,
reason = "the signature is shared with Windows, where the call can refuse"
)]
fn refuse_windows_names(_path: &RelPath, _shown: &str) -> Result<(), TreeError> {
Ok(())
}
#[cfg(windows)]
fn is_ambiguous_on_windows(segment: &str) -> bool {
if segment == ".." {
return false;
}
if segment.ends_with(['.', ' ']) || segment.contains(':') {
return true;
}
let stem = segment
.split('.')
.next()
.unwrap_or(segment)
.trim_end_matches(' ')
.to_ascii_uppercase();
let numbered = |prefix: &str| {
stem.strip_prefix(prefix).is_some_and(|digit| {
matches!(
digit,
"0" | "1" | "2" | "3" | "4" | "5" | "6" | "7" | "8" | "9" | "¹" | "²" | "³"
)
})
};
matches!(
stem.as_str(),
"CON" | "PRN" | "AUX" | "NUL" | "CONIN$" | "CONOUT$"
) || numbered("COM")
|| numbered("LPT")
}