#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum Refusal {
Symlink,
ReparsePoint,
Protected,
EscapesRoot,
FilesystemBoundary,
Vanished,
Tracked,
}
impl Refusal {
#[must_use]
pub fn code(self) -> &'static str {
match self {
Self::Symlink => "symlink",
Self::ReparsePoint => "reparse_point",
Self::Protected => "protected_path",
Self::EscapesRoot => "escapes_root",
Self::FilesystemBoundary => "filesystem_boundary",
Self::Vanished => "vanished",
Self::Tracked => "tracked_by_git",
}
}
}
impl std::fmt::Display for Refusal {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::Symlink => write!(f, "is a symlink"),
Self::ReparsePoint => write!(
f,
"is a reparse point — a junction, or a placeholder for a file kept elsewhere"
),
Self::Protected => write!(f, "on the protected-path denylist"),
Self::EscapesRoot => write!(f, "resolves outside the scan root"),
Self::FilesystemBoundary => write!(f, "on a different filesystem than its scan root"),
Self::Vanished => write!(f, "no longer exists"),
Self::Tracked => write!(f, "holds files git tracks"),
}
}
}
#[derive(Debug, Clone, Copy, PartialEq, Eq)]
#[non_exhaustive]
pub enum FailureKind {
NotEmpty,
Denied,
ReadOnly,
Exhausted,
Other,
}
impl FailureKind {
fn of(kind: std::io::ErrorKind) -> Self {
match kind {
std::io::ErrorKind::DirectoryNotEmpty => Self::NotEmpty,
std::io::ErrorKind::PermissionDenied => Self::Denied,
std::io::ErrorKind::ReadOnlyFilesystem => Self::ReadOnly,
_ => Self::Other,
}
}
fn of_error(error: &std::io::Error) -> Self {
let kind = Self::of(error.kind());
if kind != Self::Other {
return kind;
}
if error.raw_os_error().is_some_and(is_exhaustion) {
return Self::Exhausted;
}
kind
}
#[must_use]
pub fn code(self) -> &'static str {
match self {
Self::NotEmpty => "not_empty",
Self::Denied => "permission_denied",
Self::ReadOnly => "read_only_filesystem",
Self::Exhausted => "descriptors_exhausted",
Self::Other => "removal_failed",
}
}
#[must_use]
pub fn hint(self) -> Option<&'static str> {
match self {
Self::NotEmpty => Some("re-run to finish"),
Self::Denied => Some("--force repairs permissions inside the artifact and retries"),
Self::Exhausted => Some("--force waits and retries; -j lowers how many run at once"),
Self::ReadOnly | Self::Other => None,
}
}
}
const fn is_exhaustion(raw: i32) -> bool {
#[cfg(unix)]
{
matches!(raw, 24 | 23)
}
#[cfg(windows)]
{
raw == 4
}
#[cfg(not(any(unix, windows)))]
{
let _ = raw;
false
}
}
impl std::fmt::Display for FailureKind {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self {
Self::NotEmpty => write!(
f,
"a directory was not empty when voom unlinked it, most likely because something \
wrote into it during the removal"
),
Self::Denied => write!(f, "permission denied unlinking something inside it"),
Self::ReadOnly => write!(f, "the filesystem is mounted read-only"),
Self::Exhausted => write!(
f,
"no file descriptors were available — this process or the machine ran out while \
the removal was in flight"
),
Self::Other => write!(f, "the removal did not succeed"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
pub struct RemovalFailure {
kind: FailureKind,
os_error: Option<i32>,
os_message: String,
}
impl RemovalFailure {
pub(crate) fn from_io(error: &std::io::Error) -> Self {
Self {
kind: FailureKind::of_error(error),
os_error: error.raw_os_error(),
os_message: error.to_string(),
}
}
#[must_use]
pub fn kind(&self) -> FailureKind {
self.kind
}
#[must_use]
pub fn os_error(&self) -> Option<i32> {
self.os_error
}
#[must_use]
pub fn os_message(&self) -> &str {
&self.os_message
}
}
impl std::fmt::Display for RemovalFailure {
fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
match self.kind {
FailureKind::Other => write!(f, "{}", self.os_message),
kind => write!(f, "{kind}"),
}
}
}
#[derive(Debug, Clone, PartialEq, Eq)]
#[non_exhaustive]
pub enum Outcome {
Removed,
Detached,
WouldRemove,
Refused(Refusal),
PartiallyRemoved {
freed: u64,
remaining: u64,
failure: RemovalFailure,
},
Failed(RemovalFailure),
}
impl Outcome {
#[must_use]
pub fn is_failure(&self) -> bool {
matches!(self, Self::Failed(_) | Self::PartiallyRemoved { .. })
}
#[must_use]
pub fn is_reclaimed(&self) -> bool {
matches!(self, Self::Removed | Self::Detached | Self::WouldRemove)
}
}
#[cfg(test)]
mod tests {
#[test]
fn should_recognise_descriptor_exhaustion() {
for raw in exhaustion_errnos() {
let failure = RemovalFailure::from_io(&std::io::Error::from_raw_os_error(*raw));
assert_eq!(
failure.kind(),
FailureKind::Exhausted,
"os error {raw} must be recognised as descriptor exhaustion, not `Other`"
);
assert!(
failure.kind().hint().is_some(),
"and must suggest something the user can do"
);
}
}
#[test]
fn should_not_mistake_another_error_for_descriptor_exhaustion() {
for raw in [1, 5, 13, 22] {
assert_ne!(
RemovalFailure::from_io(&std::io::Error::from_raw_os_error(raw)).kind(),
FailureKind::Exhausted,
"os error {raw} is not descriptor exhaustion on any platform"
);
}
}
const fn exhaustion_errnos() -> &'static [i32] {
if cfg!(windows) { &[4] } else { &[24, 23] }
}
use super::*;
#[test]
fn every_refusal_has_its_own_code_and_its_own_words() {
let refusals = [
Refusal::Symlink,
Refusal::ReparsePoint,
Refusal::Protected,
Refusal::EscapesRoot,
Refusal::FilesystemBoundary,
Refusal::Vanished,
];
let mut codes = std::collections::HashSet::new();
let mut words = std::collections::HashSet::new();
for refusal in refusals {
assert!(codes.insert(refusal.code()), "duplicate code: {}", refusal.code());
assert!(words.insert(refusal.to_string()), "duplicate wording: {refusal}");
assert!(
!refusal.code().contains(' '),
"a code is machine-readable: {}",
refusal.code()
);
}
}
#[test]
fn outcomes_classify_failures_and_reclaims() {
assert!(
Outcome::Failed(RemovalFailure::from_io(&std::io::Error::from(
std::io::ErrorKind::Other
)))
.is_failure()
);
assert!(!Outcome::Refused(Refusal::Symlink).is_failure());
assert!(Outcome::Removed.is_reclaimed());
assert!(Outcome::WouldRemove.is_reclaimed());
assert!(!Outcome::Refused(Refusal::Protected).is_reclaimed());
}
#[test]
fn refusal_codes_are_stable() {
assert_eq!(Refusal::Symlink.code(), "symlink");
assert_eq!(Refusal::Protected.code(), "protected_path");
assert_eq!(Refusal::EscapesRoot.code(), "escapes_root");
assert_eq!(Refusal::FilesystemBoundary.code(), "filesystem_boundary");
assert_eq!(Refusal::Vanished.code(), "vanished");
}
#[test]
fn every_failure_kind_has_its_own_code_and_its_own_words() {
let kinds = [
FailureKind::NotEmpty,
FailureKind::Denied,
FailureKind::ReadOnly,
FailureKind::Other,
];
let mut seen = std::collections::HashSet::new();
for kind in kinds {
assert!(seen.insert(kind.code()), "`{}` is used twice", kind.code());
assert!(!kind.to_string().is_empty(), "{kind:?} has no words");
}
}
#[test]
fn a_failure_is_classified_by_kind_and_still_carries_the_os_number() {
for (kind, expected, code) in [
(
std::io::ErrorKind::DirectoryNotEmpty,
FailureKind::NotEmpty,
"not_empty",
),
(
std::io::ErrorKind::PermissionDenied,
FailureKind::Denied,
"permission_denied",
),
(
std::io::ErrorKind::ReadOnlyFilesystem,
FailureKind::ReadOnly,
"read_only_filesystem",
),
] {
let failure = RemovalFailure::from_io(&std::io::Error::from(kind));
assert_eq!(failure.kind(), expected, "{kind:?}");
assert_eq!(failure.kind().code(), code);
}
let real = RemovalFailure::from_io(&std::io::Error::from_raw_os_error(if cfg!(target_os = "linux") {
39
} else {
66
}));
assert_eq!(real.os_error(), Some(if cfg!(target_os = "linux") { 39 } else { 66 }));
assert!(!real.os_message().is_empty(), "the OS's own words are kept whole");
}
#[test]
fn a_partial_removal_is_a_failure_but_is_not_reclaimed() {
let partial = Outcome::PartiallyRemoved {
freed: 4096,
remaining: 512,
failure: RemovalFailure::from_io(&std::io::Error::from(std::io::ErrorKind::DirectoryNotEmpty)),
};
assert!(partial.is_failure(), "it is something that did not finish");
assert!(!partial.is_reclaimed(), "the artifact is still on disk");
}
}