use std::borrow::Cow;
use std::collections::BTreeMap;
use std::fs::File;
use std::path::{Path, PathBuf};
use std::sync::Arc;
use crate::image_source::ImageFile;
use crate::path::canonical_key;
use crate::time::Timestamp;
use crate::xattr::Xattr;
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum FileContent {
Owned(Vec<u8>),
Range(FileRange),
Image(ImageFile),
Declared {
len: u64,
key: u64,
},
}
#[cfg(any(
feature = "ext",
feature = "fat",
feature = "exfat",
feature = "btrfs",
feature = "apfs"
))]
pub(crate) const CONTENT_WINDOW: usize = 1 << 20;
impl FileContent {
#[must_use]
pub fn len(&self) -> u64 {
match self {
Self::Owned(bytes) => bytes.len() as u64,
Self::Range(range) => range.len(),
Self::Image(file) => file.len(),
Self::Declared { len, .. } => *len,
}
}
pub fn read_at(&self, at: u64, buf: &mut [u8]) -> std::io::Result<()> {
match self {
Self::Owned(bytes) => {
let within = usize::try_from(at).ok().filter(|from| {
from.checked_add(buf.len())
.is_some_and(|end| end <= bytes.len())
});
let Some(from) = within else {
return Err(past_the_end(at, buf.len(), bytes.len() as u64));
};
buf.copy_from_slice(&bytes[from..from + buf.len()]);
Ok(())
}
Self::Range(range) => range.read_at(at, buf),
Self::Image(file) => file.read_at(at, buf),
Self::Declared { key, .. } => Err(not_held(*key)),
}
}
#[cfg(any(feature = "ext", feature = "fat", feature = "exfat", feature = "apfs"))]
pub(crate) fn for_each_window<E: From<std::io::Error>>(
&self,
mut each: impl FnMut(u64, &[u8]) -> Result<(), E>,
) -> Result<(), E> {
match self {
Self::Owned(bytes) => {
for (n, window) in bytes.chunks(CONTENT_WINDOW).enumerate() {
each((n * CONTENT_WINDOW) as u64, window)?;
}
Ok(())
}
Self::Range(range) => range.for_each_window(each),
Self::Image(file) => windows(file.len(), |at, buf| file.read_at(at, buf), each),
Self::Declared { len: 0, .. } => Ok(()),
Self::Declared { key, .. } => Err(not_held(*key).into()),
}
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.len() == 0
}
pub fn read(&self) -> std::io::Result<Cow<'_, [u8]>> {
match self {
Self::Owned(bytes) => Ok(Cow::Borrowed(bytes)),
Self::Range(range) => Ok(Cow::Owned(range.read()?)),
Self::Image(file) => {
let mut bytes = vec![
0u8;
usize::try_from(file.len()).map_err(|_| {
std::io::Error::new(
std::io::ErrorKind::OutOfMemory,
"a file in an image is larger than this machine addresses",
)
})?
];
file.read_at(0, &mut bytes)?;
Ok(Cow::Owned(bytes))
}
Self::Declared { key, .. } => Err(not_held(*key)),
}
}
}
impl From<Vec<u8>> for FileContent {
fn from(bytes: Vec<u8>) -> Self {
Self::Owned(bytes)
}
}
impl From<FileRange> for FileContent {
fn from(range: FileRange) -> Self {
Self::Range(range)
}
}
impl From<ImageFile> for FileContent {
fn from(file: ImageFile) -> Self {
Self::Image(file)
}
}
impl From<&[u8]> for FileContent {
fn from(bytes: &[u8]) -> Self {
Self::Owned(bytes.to_vec())
}
}
impl<const N: usize> From<&[u8; N]> for FileContent {
fn from(bytes: &[u8; N]) -> Self {
Self::Owned(bytes.to_vec())
}
}
impl From<&str> for FileContent {
fn from(text: &str) -> Self {
Self::Owned(text.as_bytes().to_vec())
}
}
impl From<String> for FileContent {
fn from(text: String) -> Self {
Self::Owned(text.into_bytes())
}
}
#[derive(Clone)]
pub struct FileRange {
backing: Backing,
path: Arc<PathBuf>,
offset: u64,
len: u64,
}
#[derive(Clone)]
enum Backing {
Descriptor(Arc<File>),
Path,
#[cfg(all(feature = "dir", any(target_os = "linux", target_os = "android")))]
Walked(crate::host::Walked),
}
impl FileRange {
#[must_use]
pub fn new(file: Arc<File>, path: impl Into<PathBuf>, offset: u64, len: u64) -> Self {
Self {
backing: Backing::Descriptor(file),
path: Arc::new(path.into()),
offset,
len,
}
}
#[must_use]
pub fn at_path(path: impl Into<PathBuf>, offset: u64, len: u64) -> Self {
Self {
backing: Backing::Path,
path: Arc::new(path.into()),
offset,
len,
}
}
#[cfg(all(feature = "dir", any(target_os = "linux", target_os = "android")))]
pub(crate) fn walked(
walked: crate::host::Walked,
path: impl Into<PathBuf>,
offset: u64,
len: u64,
) -> Self {
Self {
backing: Backing::Walked(walked),
path: Arc::new(path.into()),
offset,
len,
}
}
#[must_use]
pub fn path(&self) -> &Path {
self.path.as_path()
}
#[must_use]
pub const fn offset(&self) -> u64 {
self.offset
}
#[must_use]
pub const fn len(&self) -> u64 {
self.len
}
#[must_use]
pub const fn is_empty(&self) -> bool {
self.len == 0
}
pub fn read(&self) -> std::io::Result<Vec<u8>> {
let len = usize::try_from(self.len).map_err(|_| {
std::io::Error::other(format!(
"{}: {} bytes at offset {} is more than this platform addresses",
crate::escape::printable_path(&self.path),
self.len,
self.offset
))
})?;
let mut buf = vec![0u8; len];
self.read_at(0, &mut buf)?;
Ok(buf)
}
pub fn read_at(&self, at: u64, buf: &mut [u8]) -> std::io::Result<()> {
let len = buf.len();
let context = |e: std::io::Error| {
std::io::Error::new(
e.kind(),
format!(
"{}: reading {len} bytes at offset {}: {e}",
crate::escape::printable_path(&self.path),
self.offset.saturating_add(at)
),
)
};
let start = at
.checked_add(len as u64)
.filter(|end| *end <= self.len)
.and_then(|_| self.offset.checked_add(at))
.ok_or_else(|| context(past_the_end(at, len, self.len)))?;
match &self.backing {
Backing::Descriptor(file) => read_exact_at(file, buf, start),
Backing::Path => open_no_follow(self.path.as_path())
.and_then(|file| read_exact_at(&file, buf, start)),
#[cfg(all(feature = "dir", any(target_os = "linux", target_os = "android")))]
Backing::Walked(walked) => walked
.open()
.and_then(|file| read_exact_at(&file, buf, start)),
}
.map_err(context)
}
#[cfg(any(feature = "ext", feature = "fat", feature = "exfat", feature = "apfs"))]
pub(crate) fn for_each_window<E: From<std::io::Error>>(
&self,
each: impl FnMut(u64, &[u8]) -> Result<(), E>,
) -> Result<(), E> {
windows(self.len, |at, buf| self.read_at(at, buf), each)
}
}
#[cfg(any(feature = "ext", feature = "fat", feature = "exfat", feature = "apfs"))]
fn windows<E: From<std::io::Error>>(
len: u64,
mut read: impl FnMut(u64, &mut [u8]) -> std::io::Result<()>,
mut each: impl FnMut(u64, &[u8]) -> Result<(), E>,
) -> Result<(), E> {
let mut buffer = vec![0u8; len.min(CONTENT_WINDOW as u64) as usize];
let mut at = 0u64;
while at < len {
let n = (len - at).min(CONTENT_WINDOW as u64) as usize;
read(at, &mut buffer[..n])?;
each(at, &buffer[..n])?;
at += n as u64;
}
Ok(())
}
fn not_held(key: u64) -> std::io::Error {
std::io::Error::new(
std::io::ErrorKind::Unsupported,
format!("a file declared by its length alone, under key {key}, holds no bytes to read"),
)
}
fn past_the_end(at: u64, len: usize, size: u64) -> std::io::Error {
std::io::Error::new(
std::io::ErrorKind::InvalidInput,
format!("{len} bytes at {at} run past the end of {size} bytes of contents"),
)
}
fn read_exact_at(file: &File, buf: &mut [u8], offset: u64) -> std::io::Result<()> {
#[cfg(unix)]
{
std::os::unix::fs::FileExt::read_exact_at(file, buf, offset)
}
#[cfg(windows)]
{
use std::os::windows::fs::FileExt as _;
let mut done = 0;
while done < buf.len() {
let at = offset
.checked_add(done as u64)
.ok_or_else(|| std::io::Error::other("the range ends past the 64-bit range"))?;
match file.seek_read(&mut buf[done..], at) {
Ok(0) => return Err(std::io::ErrorKind::UnexpectedEof.into()),
Ok(read) => done += read,
Err(e) if e.kind() == std::io::ErrorKind::Interrupted => {}
Err(e) => return Err(e),
}
}
Ok(())
}
#[cfg(not(any(unix, windows)))]
{
use std::io::{Read as _, Seek as _};
static CURSOR: std::sync::Mutex<()> = std::sync::Mutex::new(());
let _held = CURSOR
.lock()
.unwrap_or_else(std::sync::PoisonError::into_inner);
let mut file = file;
file.seek(std::io::SeekFrom::Start(offset))?;
file.read_exact(buf)
}
}
fn open_no_follow(path: &Path) -> std::io::Result<File> {
#[cfg(unix)]
{
use std::os::unix::fs::OpenOptionsExt as _;
std::fs::OpenOptions::new()
.read(true)
.custom_flags(o_nofollow())
.open(path)
}
#[cfg(not(unix))]
{
File::open(path)
}
}
#[cfg(unix)]
const fn o_nofollow() -> i32 {
#[cfg(any(target_os = "linux", target_os = "android"))]
{
if cfg!(any(
target_arch = "arm",
target_arch = "aarch64",
target_arch = "m68k",
target_arch = "powerpc",
target_arch = "powerpc64"
)) {
0o100_000
} else {
0o400_000
}
}
#[cfg(any(target_os = "solaris", target_os = "illumos"))]
{
0o400_000
}
#[cfg(any(
target_os = "macos",
target_os = "ios",
target_os = "tvos",
target_os = "watchos",
target_os = "visionos",
target_os = "freebsd",
target_os = "openbsd",
target_os = "netbsd",
target_os = "dragonfly"
))]
{
0x0100
}
#[cfg(not(any(
target_os = "linux",
target_os = "android",
target_os = "solaris",
target_os = "illumos",
target_os = "macos",
target_os = "ios",
target_os = "tvos",
target_os = "watchos",
target_os = "visionos",
target_os = "freebsd",
target_os = "openbsd",
target_os = "netbsd",
target_os = "dragonfly"
)))]
{
compile_error!(
"no O_NOFOLLOW value is known for this target, and an open that follows a \
symbolic link would read through a name recorded as a link"
);
0
}
}
impl PartialEq for FileRange {
fn eq(&self, other: &Self) -> bool {
self.path == other.path && self.offset == other.offset && self.len == other.len
}
}
impl Eq for FileRange {}
impl std::fmt::Debug for FileRange {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
f.debug_struct("FileRange")
.field("path", &self.path)
.field("offset", &self.offset)
.field("len", &self.len)
.finish()
}
}
#[derive(Clone, Copy, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct Metadata {
pub mode: u16,
pub uid: u32,
pub gid: u32,
pub atime: Timestamp,
pub ctime: Timestamp,
pub mtime: Timestamp,
pub btime: Option<Timestamp>,
}
#[cfg(any(feature = "ext", feature = "btrfs", feature = "apfs"))]
pub(crate) const MODE_TYPE_MASK: u16 = 0o170000;
impl Metadata {
#[must_use]
pub fn new(mode: u16, mtime: Timestamp) -> Self {
Self {
mode,
uid: 0,
gid: 0,
atime: mtime,
ctime: mtime,
mtime,
btime: None,
}
}
#[must_use]
pub fn owned_by(mut self, uid: u32, gid: u32) -> Self {
self.uid = uid;
self.gid = gid;
self
}
#[must_use]
pub fn with_times(mut self, atime: Timestamp, ctime: Timestamp, mtime: Timestamp) -> Self {
self.atime = atime;
self.ctime = ctime;
self.mtime = mtime;
self
}
#[must_use]
pub fn with_birth_time(mut self, btime: Timestamp) -> Self {
self.btime = Some(btime);
self
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub enum EntryKind {
Directory,
File(FileContent),
Symlink(Vec<u8>),
HardLink {
target: Vec<u8>,
},
CharDevice {
major: u32,
minor: u32,
},
BlockDevice {
major: u32,
minor: u32,
},
Fifo,
Socket,
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct SourceEntry {
pub path: Vec<u8>,
pub kind: EntryKind,
pub meta: Metadata,
pub xattrs: Vec<Xattr>,
pub darwin: Option<Darwin>,
}
#[derive(Clone, PartialEq, Eq, Debug, Default)]
#[non_exhaustive]
pub struct Darwin {
pub bsd_flags: u32,
pub compressed: Option<CompressedFile>,
}
impl Darwin {
pub const COMPRESSED: u32 = 0x20;
#[must_use]
pub const fn new(bsd_flags: u32) -> Self {
Self {
bsd_flags,
compressed: None,
}
}
#[must_use]
pub fn compressed(mut self, form: CompressedFile) -> Self {
self.bsd_flags |= Self::COMPRESSED;
self.compressed = Some(form);
self
}
#[must_use]
pub const fn stated_flags(&self) -> u32 {
self.bsd_flags & !Self::COMPRESSED
}
}
#[derive(Clone, PartialEq, Eq, Debug)]
#[non_exhaustive]
pub struct CompressedFile {
pub header: Vec<u8>,
pub fork: Option<Vec<u8>>,
}
impl CompressedFile {
#[must_use]
pub const fn new(header: Vec<u8>, fork: Option<Vec<u8>>) -> Self {
Self { header, fork }
}
}
impl SourceEntry {
#[must_use]
pub fn new(path: impl Into<Vec<u8>>, kind: EntryKind, meta: Metadata) -> Self {
Self {
path: path.into(),
kind,
meta,
xattrs: Vec::new(),
darwin: None,
}
}
#[must_use]
pub fn with_xattrs(mut self, xattrs: Vec<Xattr>) -> Self {
self.xattrs = xattrs;
self
}
#[must_use]
pub fn with_darwin(mut self, darwin: Darwin) -> Self {
self.darwin = Some(darwin);
self
}
}
pub trait Source {
fn into_entries(self) -> Vec<SourceEntry>;
}
impl Source for Vec<SourceEntry> {
fn into_entries(self) -> Vec<SourceEntry> {
self
}
}
#[derive(Clone, Default, Debug)]
pub struct TreeBuilder {
entries: Vec<SourceEntry>,
}
impl TreeBuilder {
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn directory(mut self, path: impl Into<Vec<u8>>, meta: Metadata) -> Self {
self.push(path, EntryKind::Directory, meta);
self
}
#[must_use]
pub fn root(mut self, meta: Metadata) -> Self {
self.push(b"/".to_vec(), EntryKind::Directory, meta);
self
}
#[must_use]
pub fn file(
mut self,
path: impl Into<Vec<u8>>,
contents: impl Into<FileContent>,
meta: Metadata,
) -> Self {
self.push(path, EntryKind::File(contents.into()), meta);
self
}
#[must_use]
pub fn symlink(
mut self,
path: impl Into<Vec<u8>>,
target: impl Into<Vec<u8>>,
meta: Metadata,
) -> Self {
self.push(path, EntryKind::Symlink(target.into()), meta);
self
}
#[must_use]
pub fn hardlink(
mut self,
path: impl Into<Vec<u8>>,
target: impl Into<Vec<u8>>,
meta: Metadata,
) -> Self {
self.push(
path,
EntryKind::HardLink {
target: target.into(),
},
meta,
);
self
}
#[must_use]
pub fn char_device(
mut self,
path: impl Into<Vec<u8>>,
major: u32,
minor: u32,
meta: Metadata,
) -> Self {
self.push(path, EntryKind::CharDevice { major, minor }, meta);
self
}
#[must_use]
pub fn block_device(
mut self,
path: impl Into<Vec<u8>>,
major: u32,
minor: u32,
meta: Metadata,
) -> Self {
self.push(path, EntryKind::BlockDevice { major, minor }, meta);
self
}
#[must_use]
pub fn fifo(mut self, path: impl Into<Vec<u8>>, meta: Metadata) -> Self {
self.push(path, EntryKind::Fifo, meta);
self
}
#[must_use]
pub fn socket(mut self, path: impl Into<Vec<u8>>, meta: Metadata) -> Self {
self.push(path, EntryKind::Socket, meta);
self
}
#[must_use]
pub fn xattr(mut self, name: impl Into<Vec<u8>>, value: impl Into<Vec<u8>>) -> Self {
if let Some(entry) = self.entries.last_mut() {
entry.xattrs.push(Xattr {
name: name.into(),
value: value.into(),
});
}
self
}
fn push(&mut self, path: impl Into<Vec<u8>>, kind: EntryKind, meta: Metadata) {
self.entries.push(SourceEntry::new(path, kind, meta));
}
}
impl Source for TreeBuilder {
fn into_entries(self) -> Vec<SourceEntry> {
self.entries
}
}
#[derive(Clone, Default, Debug)]
pub struct LayeredSource {
entries: BTreeMap<Vec<u8>, SourceEntry>,
}
impl LayeredSource {
#[must_use]
pub fn new() -> Self {
Self::default()
}
#[must_use]
pub fn layer(mut self, source: impl Source) -> Self {
for entry in source.into_entries() {
let key = canonical_key(&entry.path);
if !matches!(entry.kind, EntryKind::Directory) {
let beneath = self.beneath(&key);
self.drop_names(&beneath);
}
if self
.entries
.get(&key)
.is_some_and(|old| !matches!(old.kind, EntryKind::Directory))
{
self.drop_names(std::slice::from_ref(&key));
}
self.entries.insert(key, entry);
}
self
}
pub fn remove(mut self, path: impl AsRef<[u8]>) -> Result<Self, RemovalError> {
let path = path.as_ref();
let key = canonical_key(path);
if key.is_empty() {
return Err(RemovalError::Root);
}
let mut doomed = self.beneath(&key);
if self.entries.contains_key(&key) {
doomed.push(key);
}
if doomed.is_empty() {
return Err(RemovalError::NotHeld {
path: path.to_vec(),
});
}
self.drop_names(&doomed);
Ok(self)
}
fn beneath(&self, key: &[u8]) -> Vec<Vec<u8>> {
let mut prefix = key.to_vec();
if !prefix.is_empty() {
prefix.push(b'/');
}
self.entries
.range(prefix.clone()..)
.take_while(|(k, _)| k.starts_with(&prefix))
.filter(|(k, _)| k.as_slice() != key)
.map(|(k, _)| k.clone())
.collect()
}
fn drop_names(&mut self, doomed: &[Vec<u8>]) {
if doomed.is_empty() {
return;
}
let doomed: std::collections::BTreeSet<&[u8]> = doomed.iter().map(Vec::as_slice).collect();
let mut reached: BTreeMap<Vec<u8>, Vec<Vec<u8>>> = BTreeMap::new();
for (key, entry) in &self.entries {
let EntryKind::HardLink { target } = &entry.kind else {
continue;
};
if doomed.contains(key.as_slice()) {
continue;
}
let through = std::cell::Cell::new(false);
let end = follow_hard_link(target, self.entries.len(), |at| {
if doomed.contains(at) {
through.set(true);
}
match self.entries.get(at).map(|e| &e.kind) {
None => LinkStep::Missing,
Some(EntryKind::Directory) => LinkStep::Directory,
Some(EntryKind::HardLink { target }) => LinkStep::Link(canonical_key(target)),
Some(_) => LinkStep::File(at.to_vec()),
}
});
if let LinkEnd::File(file) = end
&& through.get()
{
reached.entry(file).or_default().push(key.clone());
}
}
for (file, links) in reached {
let target = if doomed.contains(file.as_slice()) {
let held = self.entries[&file].clone();
let holder = self
.entries
.get_mut(&links[0])
.expect("a surviving link is composed");
holder.kind = held.kind;
holder.meta = held.meta;
holder.xattrs = held.xattrs;
holder.darwin = held.darwin;
holder.path.clone()
} else {
self.entries[&file].path.clone()
};
for link in &links {
let entry = self
.entries
.get_mut(link)
.expect("a surviving link is composed");
if let EntryKind::HardLink { target: named } = &mut entry.kind {
named.clone_from(&target);
}
}
}
for key in doomed {
self.entries.remove(key);
}
}
#[must_use]
pub fn len(&self) -> usize {
self.entries.len()
}
#[must_use]
pub fn is_empty(&self) -> bool {
self.entries.is_empty()
}
}
impl Source for LayeredSource {
fn into_entries(self) -> Vec<SourceEntry> {
self.entries.into_values().collect()
}
}
#[derive(Clone, PartialEq, Eq, Debug, thiserror::Error)]
#[non_exhaustive]
pub enum RemovalError {
#[error("nothing is at {} or beneath it to remove", crate::escape::printable(.path))]
#[non_exhaustive]
NotHeld {
path: Vec<u8>,
},
#[error("the root directory is part of every filesystem and is not removed")]
Root,
}
#[cfg(any(
feature = "fat",
feature = "exfat",
feature = "btrfs",
feature = "apfs"
))]
pub(crate) enum PathFault {
Traversal,
Duplicate,
RootNotDirectory,
}
#[cfg(any(
feature = "fat",
feature = "exfat",
feature = "btrfs",
feature = "apfs"
))]
pub(crate) enum ClassifyError<E> {
Path(PathFault, Vec<u8>),
Class(E),
}
#[cfg(any(
feature = "fat",
feature = "exfat",
feature = "btrfs",
feature = "apfs"
))]
pub(crate) fn classify_paths<C, E>(
entries: &[SourceEntry],
mut class_of: impl FnMut(&SourceEntry, &[&[u8]]) -> Result<C, E>,
is_directory: impl Fn(&C) -> bool,
) -> Result<BTreeMap<Vec<u8>, C>, ClassifyError<E>> {
let mut classes = BTreeMap::new();
for entry in entries {
let parts = crate::path::canonical_parts(&entry.path);
if parts.iter().any(|part| *part == b"..") {
return Err(ClassifyError::Path(
PathFault::Traversal,
entry.path.clone(),
));
}
let key = parts.join(&b'/');
if classes.contains_key(&key) {
return Err(ClassifyError::Path(
PathFault::Duplicate,
entry.path.clone(),
));
}
let class = class_of(entry, &parts).map_err(ClassifyError::Class)?;
if key.is_empty() && !is_directory(&class) {
return Err(ClassifyError::Path(
PathFault::RootNotDirectory,
entry.path.clone(),
));
}
classes.insert(key, class);
}
Ok(classes)
}
pub(crate) enum LinkStep<T> {
File(T),
Directory,
#[cfg_attr(not(any(feature = "fat", feature = "exfat")), allow(dead_code))]
Unrepresentable,
Link(Vec<u8>),
Missing,
}
pub(crate) enum LinkEnd<T> {
File(T),
Unrepresentable,
Directory,
Missing,
Cycle,
}
pub(crate) fn follow_hard_link<T>(
target: &[u8],
declared: usize,
step: impl Fn(&[u8]) -> LinkStep<T>,
) -> LinkEnd<T> {
let mut at = canonical_key(target);
let mut seen = 0usize;
loop {
match step(&at) {
LinkStep::File(found) => return LinkEnd::File(found),
LinkStep::Directory => return LinkEnd::Directory,
LinkStep::Unrepresentable => return LinkEnd::Unrepresentable,
LinkStep::Missing => return LinkEnd::Missing,
LinkStep::Link(next) => {
seen += 1;
if seen > declared {
return LinkEnd::Cycle;
}
at = next;
}
}
}
}
#[cfg(test)]
mod tests {
use super::*;
fn meta() -> Metadata {
Metadata::new(0o644, Timestamp::from_secs(1_700_000_000))
}
#[test]
fn builder_collects_entries_in_addition_order() {
let src = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o755, meta().mtime))
.file(b"/etc/hostname".to_vec(), b"host\n".to_vec(), meta())
.symlink(b"/etc/mtab".to_vec(), b"/proc/mounts".to_vec(), meta());
let entries = src.into_entries();
assert_eq!(entries.len(), 3);
assert_eq!(entries[0].path, b"/etc");
assert!(matches!(entries[1].kind, EntryKind::File(_)));
assert!(matches!(entries[2].kind, EntryKind::Symlink(_)));
}
#[test]
fn an_entry_built_by_its_constructor_is_the_one_the_builder_adds() {
let built = SourceEntry::new(b"/etc/hostname".to_vec(), EntryKind::Fifo, meta());
assert!(built.xattrs.is_empty());
let added = TreeBuilder::new()
.fifo(b"/etc/hostname".to_vec(), meta())
.into_entries();
assert_eq!(added, vec![built.clone()]);
let attribute = Xattr {
name: b"user.a".to_vec(),
value: b"1".to_vec(),
};
let carried = built.with_xattrs(vec![attribute.clone()]);
assert_eq!(carried.xattrs, vec![attribute.clone()]);
let replaced = carried.with_xattrs(Vec::new());
assert!(replaced.xattrs.is_empty());
}
fn paths(source: LayeredSource) -> Vec<String> {
source
.into_entries()
.into_iter()
.map(|e| String::from_utf8_lossy(&e.path).into_owned())
.collect()
}
fn contents_at(entries: &[SourceEntry], path: &[u8]) -> Vec<u8> {
let entry = entries
.iter()
.find(|e| e.path == path)
.expect("path is present");
match &entry.kind {
EntryKind::File(c) => c.read().expect("read").into_owned(),
other => panic!("expected a file, got {other:?}"),
}
}
#[test]
fn a_later_layer_replaces_an_earlier_entry_whole() {
let base = TreeBuilder::new()
.file(b"/etc/hostname".to_vec(), b"base\n".to_vec(), meta())
.xattr(b"user.from".to_vec(), b"base".to_vec());
let over = TreeBuilder::new()
.file(
b"/etc/hostname".to_vec(),
b"over\n".to_vec(),
Metadata::new(0o600, meta().mtime),
)
.xattr(b"user.other".to_vec(), b"over".to_vec());
let entries = LayeredSource::new().layer(base).layer(over).into_entries();
assert_eq!(entries.len(), 1);
assert_eq!(contents_at(&entries, b"/etc/hostname"), b"over\n");
assert_eq!(entries[0].meta.mode, 0o600);
assert_eq!(entries[0].xattrs.len(), 1);
assert_eq!(entries[0].xattrs[0].name, b"user.other");
}
#[test]
fn naming_a_directory_again_does_not_empty_it() {
let base = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o755, meta().mtime))
.file(b"/etc/hostname".to_vec(), b"base\n".to_vec(), meta());
let over = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o700, meta().mtime))
.file(b"/etc/issue".to_vec(), b"over\n".to_vec(), meta());
let composed = LayeredSource::new().layer(base).layer(over);
assert_eq!(
paths(composed.clone()),
["/etc", "/etc/hostname", "/etc/issue"]
);
let entries = composed.into_entries();
assert_eq!(entries[0].meta.mode, 0o700, "the later layer's mode");
}
#[test]
fn replacing_a_directory_with_a_file_drops_what_was_beneath_it() {
let base = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o755, meta().mtime))
.file(b"/etc/hostname".to_vec(), b"base\n".to_vec(), meta())
.directory(b"/etc/ssl".to_vec(), Metadata::new(0o755, meta().mtime))
.file(b"/etc/ssl/cert".to_vec(), b"pem\n".to_vec(), meta())
.file(b"/etcetera".to_vec(), b"kept\n".to_vec(), meta());
let over = TreeBuilder::new().file(b"/etc".to_vec(), b"now a file\n".to_vec(), meta());
assert_eq!(
paths(LayeredSource::new().layer(base).layer(over)),
["/etc", "/etcetera"]
);
}
#[test]
fn a_directory_over_a_file_keeps_the_directory() {
let base = TreeBuilder::new().file(b"/etc".to_vec(), b"a file\n".to_vec(), meta());
let over = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o755, meta().mtime))
.file(b"/etc/hostname".to_vec(), b"over\n".to_vec(), meta());
let entries = LayeredSource::new().layer(base).layer(over).into_entries();
assert_eq!(entries.len(), 2);
assert!(matches!(entries[0].kind, EntryKind::Directory));
}
#[test]
fn paths_that_spell_one_path_are_one_path() {
let base = TreeBuilder::new().file(b"/etc/hostname".to_vec(), b"base\n".to_vec(), meta());
let over = TreeBuilder::new().file(b"//etc//hostname".to_vec(), b"over\n".to_vec(), meta());
let last = TreeBuilder::new().file(b"etc/./hostname".to_vec(), b"last\n".to_vec(), meta());
let entries = LayeredSource::new()
.layer(base)
.layer(over)
.layer(last)
.into_entries();
assert_eq!(entries.len(), 1, "three spellings of one path");
assert_eq!(entries[0].path, b"etc/./hostname");
assert_eq!(contents_at(&entries, b"etc/./hostname"), b"last\n");
}
#[test]
fn the_root_is_a_path_like_any_other() {
let base = TreeBuilder::new()
.root(Metadata::new(0o755, meta().mtime))
.file(b"/etc/hostname".to_vec(), b"base\n".to_vec(), meta());
let over = TreeBuilder::new().root(Metadata::new(0o700, meta().mtime));
let composed = LayeredSource::new().layer(base).layer(over);
assert_eq!(paths(composed.clone()), ["/", "/etc/hostname"]);
assert_eq!(
composed.into_entries()[0].meta.mode,
0o700,
"the later root's mode, and the tree beneath it kept"
);
}
#[test]
fn a_removal_takes_the_path_and_everything_beneath_it() {
let base = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o755, meta().mtime))
.file(b"/etc/hostname".to_vec(), b"base\n".to_vec(), meta())
.directory(b"/etc/ssl".to_vec(), Metadata::new(0o755, meta().mtime))
.file(b"/etc/ssl/cert".to_vec(), b"pem\n".to_vec(), meta())
.file(b"/etc/ssl-old".to_vec(), b"kept\n".to_vec(), meta())
.file(b"/etcetera".to_vec(), b"kept\n".to_vec(), meta());
let composed = LayeredSource::new()
.layer(base)
.remove(b"//etc//ssl/.")
.expect("held");
assert_eq!(
paths(composed.clone()),
["/etc", "/etc/hostname", "/etc/ssl-old", "/etcetera"],
"a spelling of the path the model takes as it"
);
assert_eq!(paths(composed.remove("/etc").expect("held")), ["/etcetera"]);
}
#[test]
fn a_removal_of_nothing_is_refused_naming_the_path_written() {
let base = TreeBuilder::new().file(b"/etc/hostname".to_vec(), b"base\n".to_vec(), meta());
let composed = LayeredSource::new().layer(base);
assert_eq!(
composed.clone().remove("/etc/hostnmae").err(),
Some(RemovalError::NotHeld {
path: b"/etc/hostnmae".to_vec()
})
);
let once = composed.clone().remove("/etc/hostname").expect("held");
assert!(matches!(
once.remove("/etc/hostname"),
Err(RemovalError::NotHeld { .. })
));
assert!(composed.clone().remove("/etc").expect("held").is_empty());
for root in ["/", "", "//.", "."] {
assert_eq!(
composed.clone().remove(root).err(),
Some(RemovalError::Root),
"{root:?}"
);
}
let message = LayeredSource::new()
.remove(b"/a\x1b[2J")
.expect_err("nothing")
.to_string();
assert!(
!message.contains('\x1b'),
"the path is escaped: {message:?}"
);
}
#[test]
fn a_later_layer_replacing_one_name_of_a_linked_file_leaves_the_other_its_file() {
let time = meta().mtime;
let base = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o755, time))
.file(
b"/etc/a".to_vec(),
b"OLD".to_vec(),
Metadata::new(0o644, time),
)
.hardlink(
b"/etc/b".to_vec(),
b"/etc/a".to_vec(),
Metadata::new(0o644, time),
);
let over = TreeBuilder::new().file(
b"/etc/a".to_vec(),
b"NEW".to_vec(),
Metadata::new(0o600, time),
);
let entries = LayeredSource::new().layer(base).layer(over).into_entries();
let content = |path: &[u8]| {
let entry = entries.iter().find(|e| e.path == path).expect("the entry");
match &entry.kind {
EntryKind::File(c) => (c.read().unwrap().as_ref().to_vec(), entry.meta.mode),
other => panic!("{} is {other:?}", String::from_utf8_lossy(path)),
}
};
assert_eq!(content(b"/etc/a"), (b"NEW".to_vec(), 0o600));
assert_eq!(content(b"/etc/b"), (b"OLD".to_vec(), 0o644));
}
#[test]
fn a_later_layer_places_a_removed_path_again() {
let base = TreeBuilder::new().file(b"/motd".to_vec(), b"base\n".to_vec(), meta());
let over = TreeBuilder::new().file(b"/motd".to_vec(), b"over\n".to_vec(), meta());
let entries = LayeredSource::new()
.layer(base)
.remove("/motd")
.expect("held")
.layer(over)
.into_entries();
assert_eq!(contents_at(&entries, b"/motd"), b"over\n");
}
fn kind_at<'a>(entries: &'a [SourceEntry], path: &[u8]) -> &'a EntryKind {
&entries
.iter()
.find(|e| e.path == path)
.unwrap_or_else(|| panic!("{} is present", String::from_utf8_lossy(path)))
.kind
}
#[test]
fn a_file_whose_name_is_removed_keeps_its_other_names() {
let held = meta().owned_by(501, 20);
let base = TreeBuilder::new()
.file(b"/a".to_vec(), b"x".to_vec(), held)
.xattr(b"user.k".to_vec(), b"v".to_vec())
.hardlink(b"/c".to_vec(), b"/a".to_vec(), meta())
.hardlink(b"/b".to_vec(), b"/a".to_vec(), meta())
.into_entries();
let mut base = base;
base[0].darwin = Some(Darwin::new(0x8000));
let entries = LayeredSource::new()
.layer(base)
.remove("/a")
.expect("held")
.into_entries();
let b = entries.iter().find(|e| e.path == b"/b").expect("kept");
assert_eq!(contents_at(&entries, b"/b"), b"x");
assert_eq!(b.meta, held);
assert_eq!(b.xattrs.len(), 1);
assert_eq!(b.darwin, Some(Darwin::new(0x8000)));
assert_eq!(
kind_at(&entries, b"/c"),
&EntryKind::HardLink {
target: b"/b".to_vec()
}
);
assert_eq!(entries.len(), 2);
}
#[test]
fn a_link_past_a_removed_link_names_the_file() {
let base = TreeBuilder::new()
.file(b"/a".to_vec(), b"x".to_vec(), meta())
.hardlink(b"/b".to_vec(), b"/a".to_vec(), meta())
.hardlink(b"/c".to_vec(), b"//b".to_vec(), meta())
.hardlink(b"/d".to_vec(), b"/nowhere".to_vec(), meta());
let entries = LayeredSource::new()
.layer(base)
.remove("/b")
.expect("held")
.into_entries();
assert_eq!(
kind_at(&entries, b"/c"),
&EntryKind::HardLink {
target: b"/a".to_vec()
}
);
assert_eq!(
kind_at(&entries, b"/d"),
&EntryKind::HardLink {
target: b"/nowhere".to_vec()
}
);
}
#[test]
fn a_file_beneath_a_replaced_directory_keeps_its_name_outside_it() {
let base = TreeBuilder::new()
.directory(b"/etc".to_vec(), Metadata::new(0o755, meta().mtime))
.file(b"/etc/hostname".to_vec(), b"base\n".to_vec(), meta())
.hardlink(b"/hostname".to_vec(), b"/etc/hostname".to_vec(), meta());
let removed = LayeredSource::new()
.layer(base.clone())
.remove("/etc")
.expect("held")
.into_entries();
assert_eq!(contents_at(&removed, b"/hostname"), b"base\n");
let over = TreeBuilder::new().file(b"/etc".to_vec(), b"a file\n".to_vec(), meta());
let replaced = LayeredSource::new().layer(base).layer(over).into_entries();
assert_eq!(contents_at(&replaced, b"/hostname"), b"base\n");
assert_eq!(contents_at(&replaced, b"/etc"), b"a file\n");
}
#[test]
fn a_layer_over_nothing_is_that_layer() {
let one = TreeBuilder::new().file(b"/a".to_vec(), b"x".to_vec(), meta());
assert_eq!(paths(LayeredSource::new().layer(one)), ["/a"]);
assert!(LayeredSource::new().is_empty());
assert_eq!(LayeredSource::new().len(), 0);
}
#[test]
fn metadata_ownership_builder() {
let m = Metadata::new(0o600, Timestamp::from_secs(0)).owned_by(1000, 1000);
assert_eq!(m.uid, 1000);
assert_eq!(m.gid, 1000);
assert_eq!(m.mode, 0o600);
}
#[test]
fn hardlink_records_its_target() {
let src = TreeBuilder::new()
.file(b"/a".to_vec(), b"x".to_vec(), meta())
.hardlink(b"/b".to_vec(), b"/a".to_vec(), meta());
let entries = src.into_entries();
match &entries[1].kind {
EntryKind::HardLink { target } => assert_eq!(target, b"/a"),
other => panic!("expected hardlink, got {other:?}"),
}
}
#[test]
fn device_fifo_and_socket_kinds_are_recorded() {
let entries = TreeBuilder::new()
.char_device(b"/dev/null".to_vec(), 1, 3, meta())
.block_device(b"/dev/sda".to_vec(), 8, 0, meta())
.fifo(b"/run/pipe".to_vec(), meta())
.socket(b"/run/sock".to_vec(), meta())
.into_entries();
assert!(matches!(
entries[0].kind,
EntryKind::CharDevice { major: 1, minor: 3 }
));
assert!(matches!(
entries[1].kind,
EntryKind::BlockDevice { major: 8, minor: 0 }
));
assert!(matches!(entries[2].kind, EntryKind::Fifo));
assert!(matches!(entries[3].kind, EntryKind::Socket));
}
#[test]
fn xattr_attaches_to_the_most_recent_entry() {
let entries = TreeBuilder::new()
.file(b"/bin/ping".to_vec(), b"elf".to_vec(), meta())
.xattr(b"security.capability".to_vec(), vec![1, 2, 3, 4])
.xattr(b"user.note".to_vec(), b"hi".to_vec())
.file(b"/plain".to_vec(), b"x".to_vec(), meta())
.into_entries();
assert_eq!(entries[0].xattrs.len(), 2);
assert_eq!(entries[0].xattrs[0].name, b"security.capability");
assert!(entries[1].xattrs.is_empty());
}
#[test]
fn xattr_without_a_preceding_entry_is_a_no_op() {
let entries = TreeBuilder::new()
.xattr(b"user.orphan".to_vec(), b"v".to_vec())
.into_entries();
assert!(entries.is_empty());
}
#[test]
fn every_borrowed_form_of_a_files_bytes_converts() {
let want = EntryKind::File(FileContent::Owned(b"hi".to_vec()));
let entries = TreeBuilder::new()
.file(b"/vec".to_vec(), b"hi".to_vec(), meta())
.file(b"/array".to_vec(), b"hi", meta())
.file(b"/slice".to_vec(), &b"hi"[..], meta())
.file(b"/str".to_vec(), "hi", meta())
.file(b"/string".to_vec(), String::from("hi"), meta())
.into_entries();
assert_eq!(entries.len(), 5);
for entry in &entries {
assert_eq!(
entry.kind,
want,
"{} converted to something else",
String::from_utf8_lossy(&entry.path)
);
}
}
#[test]
fn reading_owned_contents_borrows_rather_than_copies() {
let content = FileContent::Owned(vec![9u8; 64]);
let FileContent::Owned(held) = &content else {
unreachable!("the content is owned")
};
let read = content.read().expect("an owned read cannot fail");
assert!(matches!(read, std::borrow::Cow::Borrowed(_)));
assert!(std::ptr::eq(read.as_ptr(), held.as_ptr()));
}
#[test]
fn a_short_backing_file_names_itself_and_the_range() {
let dir = tempfile::tempdir().expect("temp dir");
let path = dir.path().join("shrunk.tar");
std::fs::write(&path, b"only eight").expect("write the backing file");
let file = Arc::new(File::open(&path).expect("open the backing file"));
let range = FileRange::new(Arc::clone(&file), &path, 4, 4096);
let err = range
.read()
.expect_err("a range past the end cannot be read");
let text = err.to_string();
assert!(text.contains("shrunk.tar"), "{text}");
assert!(text.contains("4096"), "{text}");
assert!(text.contains("offset 4"), "{text}");
assert_eq!(err.kind(), std::io::ErrorKind::UnexpectedEof);
let content = FileContent::Range(FileRange::new(file, &path, 5, 5));
let read = content.read().expect("read the range");
assert!(matches!(read, std::borrow::Cow::Owned(_)));
assert_eq!(read.as_ref(), b"eight");
}
#[test]
fn a_positional_read_counts_from_the_start_of_the_range_and_stops_at_its_end() {
let dir = tempfile::tempdir().expect("temp dir");
let path = dir.path().join("archive");
std::fs::write(&path, b"leadXYZABCtrail").expect("write the backing file");
let range = FileContent::Range(FileRange::at_path(&path, 4, 6));
let owned = FileContent::Owned(b"XYZABC".to_vec());
for content in [&range, &owned] {
let mut buf = [0u8; 3];
content.read_at(2, &mut buf).expect("inside the contents");
assert_eq!(&buf, b"ZAB", "{content:?}");
content
.read_at(3, &mut buf)
.expect("ending at the last byte");
assert_eq!(&buf, b"ABC", "{content:?}");
let err = content.read_at(4, &mut buf).expect_err("past the end");
assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput, "{content:?}");
let err = content
.read_at(u64::MAX, &mut buf)
.expect_err("an offset that wraps");
assert_eq!(err.kind(), std::io::ErrorKind::InvalidInput, "{content:?}");
}
}
#[test]
fn a_declared_file_has_a_length_and_no_bytes_to_read() {
let content = FileContent::Declared { len: 300, key: 42 };
assert_eq!(content.len(), 300);
let err = content.read().expect_err("no bytes");
assert_eq!(err.kind(), std::io::ErrorKind::Unsupported);
assert!(err.to_string().contains("42"), "{err}");
let err = content.read_at(0, &mut [0u8; 4]).expect_err("no bytes");
assert_eq!(err.kind(), std::io::ErrorKind::Unsupported);
}
#[cfg(any(feature = "ext", feature = "fat"))]
#[test]
fn contents_come_in_windows_that_tile_the_file_in_order() {
let len = 2 * CONTENT_WINDOW + 5;
let bytes: Vec<u8> = (0..len).map(|i| (i % 251) as u8).collect();
let dir = tempfile::tempdir().expect("temp dir");
let path = dir.path().join("big");
std::fs::write(&path, &bytes).expect("write the backing file");
let owned = FileContent::Owned(bytes.clone());
let range = FileContent::Range(FileRange::at_path(&path, 0, len as u64));
for content in [&owned, &range] {
let mut seen: Vec<(u64, usize)> = Vec::new();
let mut joined = Vec::new();
content
.for_each_window(|at, window| {
seen.push((at, window.len()));
joined.extend_from_slice(window);
Ok::<(), std::io::Error>(())
})
.expect("the contents read");
let window = CONTENT_WINDOW as u64;
assert_eq!(
seen,
[
(0, CONTENT_WINDOW),
(window, CONTENT_WINDOW),
(2 * window, 5)
]
);
assert!(joined == bytes, "the windows did not rejoin as the file");
}
let mut calls = 0;
FileContent::Owned(Vec::new())
.for_each_window(|_, _| {
calls += 1;
Ok::<(), std::io::Error>(())
})
.expect("nothing to read");
assert_eq!(calls, 0);
}
#[test]
fn ranges_sharing_one_descriptor_read_their_own_bytes_concurrently() {
const REGION: usize = 256 * 1024;
const RANGES: usize = 8;
let dir = tempfile::tempdir().expect("temp dir");
let path = dir.path().join("archive");
let bytes: Vec<u8> = (0..RANGES)
.flat_map(|i| std::iter::repeat_n(i as u8 + 1, REGION))
.collect();
std::fs::write(&path, &bytes).expect("write the backing file");
let file = Arc::new(File::open(&path).expect("open the backing file"));
let start = Arc::new(std::sync::Barrier::new(RANGES));
let readers: Vec<_> = (0..RANGES)
.map(|i| {
let range =
FileRange::new(Arc::clone(&file), &path, (i * REGION) as u64, REGION as u64);
let start = Arc::clone(&start);
std::thread::spawn(move || {
let mut wrong = 0;
for _ in 0..20 {
start.wait();
match range.read() {
Ok(read) if read.iter().all(|&b| b == i as u8 + 1) => {}
_ => wrong += 1,
}
}
wrong
})
})
.collect();
let wrong: usize = readers
.into_iter()
.map(|reader| reader.join().expect("the reader thread runs to its end"))
.sum();
assert_eq!(wrong, 0, "reads that failed or held another range's bytes");
}
#[cfg(unix)]
#[test]
fn a_link_is_refused_by_the_flag_this_target_defines() {
let dir = tempfile::tempdir().expect("temp dir");
let target = dir.path().join("target");
std::fs::write(&target, b"pointed at\n").expect("write the target");
let link = dir.path().join("link");
std::os::unix::fs::symlink(&target, &link).expect("symlink");
let err = FileRange::at_path(&link, 0, 11)
.read()
.expect_err("a range naming a link reads nothing");
let text = err.to_string();
assert!(text.contains("link"), "{text}");
assert_eq!(
FileRange::at_path(&target, 0, 11).read().expect("read"),
b"pointed at\n"
);
}
#[test]
fn distinct_times_are_preserved() {
let m = Metadata::new(0o644, Timestamp::from_secs(100)).with_times(
Timestamp::from_secs(1),
Timestamp::from_secs(2),
Timestamp::from_secs(3),
);
assert_eq!(m.atime, Timestamp::from_secs(1));
assert_eq!(m.ctime, Timestamp::from_secs(2));
assert_eq!(m.mtime, Timestamp::from_secs(3));
}
}