Handle FreeBSD rename capabilities and CI expectations safely
Beffroi/beffroi-tools/pipeline/head This commit looks good Details

This commit is contained in:
Dandaedre 2026-11-13 07:26:08 +01:00
parent bb045ec527
commit 00a43e815e
9 changed files with 350 additions and 31 deletions

View File

@ -42,7 +42,9 @@ with quick-start examples and links to detailed documentation in `docs/`.
- `tests/test_exporter.py` covers exporter validation, no-op behavior, conversion
failures, and overwrite behavior.
- `Jenkinsfile` runs Python/Rust tests, lint, docs and coverage on
`rust_no_docker`. The explicitly requested badge workflow archives exactly
`rust_no_docker` in a FreeBSD jail. ASCII cleaner tests must verify safe refusal
when the jail lacks the native no-overwrite API; exercise successful renames
on supported hosts as well. The explicitly requested badge workflow archives exactly
three SVGs and publishes them only from main during cleanup. CI never creates
releases or uploads release binaries. Cross and `rust_realease` are separate,
manually invoked build/release preparation tools.

1
Cargo.lock generated
View File

@ -207,6 +207,7 @@ version = "0.3.0"
dependencies = [
"clap",
"eframe",
"libc",
"rfd",
"rustix 1.1.5",
"tempfile",

1
Jenkinsfile vendored
View File

@ -30,6 +30,7 @@ pipeline {
set -eu
python3 -c 'import sys; assert sys.version_info >= (3, 11), "Python 3.11+ required for CI"'
test -n "${BRANCH_NAME:?Configure this job as a Multibranch Pipeline}"
uname -sr
rustc --version
if ! cargo llvm-cov --version | grep -Fx 'cargo-llvm-cov 0.9.1'; then
cargo install cargo-llvm-cov --version 0.9.1 --locked

View File

@ -20,7 +20,11 @@ rfd = { version = "0.15", optional = true }
rustix = { version = "1", features = ["fs"] }
[dev-dependencies]
libc = "0.2.191"
tempfile = "3"
[target.'cfg(windows)'.dependencies]
windows-sys = { version = "0.61", features = ["Win32_Storage_FileSystem"] }
[target.'cfg(target_os = "freebsd")'.dependencies]
libc = "0.2.191"

View File

@ -0,0 +1,113 @@
//! Resolve the newer FreeBSD API at runtime so older jails can still start/preview.
use std::{ffi::CString, io, os::unix::ffi::OsStrExt, path::Path, sync::OnceLock};
type RenameAt2 = unsafe extern "C" fn(
libc::c_int,
*const libc::c_char,
libc::c_int,
*const libc::c_char,
libc::c_uint,
) -> libc::c_int;
fn unsupported(detail: impl std::fmt::Display) -> io::Error {
io::Error::new(
io::ErrorKind::Unsupported,
format!(
"FreeBSD no-overwrite rename unavailable ({detail}); use a host, jail userland and filesystem supporting renameat2 with AT_RENAME_NOREPLACE, or run cleanup on Linux/macOS/Windows"
),
)
}
pub(super) fn rename_no_replace(from: &Path, to: &Path) -> io::Result<()> {
static RENAME: OnceLock<Option<RenameAt2>> = OnceLock::new();
let rename = RENAME.get_or_init(|| {
// SAFETY: static NUL-terminated symbol name; RTLD_DEFAULT searches loaded libraries.
let symbol = unsafe { libc::dlsym(libc::RTLD_DEFAULT, c"renameat2".as_ptr()) };
if symbol.is_null() {
None
} else {
// SAFETY: the FreeBSD renameat2 ABI has precisely the signature above.
Some(unsafe { std::mem::transmute::<*mut libc::c_void, RenameAt2>(symbol) })
}
});
rename_with(*rename, from, to)
}
fn rename_with(rename: Option<RenameAt2>, from: &Path, to: &Path) -> io::Result<()> {
let rename = rename.ok_or_else(|| unsupported("renameat2 is missing from the jail's libc"))?;
let from = CString::new(from.as_os_str().as_bytes())?;
let to = CString::new(to.as_os_str().as_bytes())?;
// SAFETY: both paths remain valid NUL-terminated strings throughout the call.
let status = unsafe {
rename(
libc::AT_FDCWD,
from.as_ptr(),
libc::AT_FDCWD,
to.as_ptr(),
libc::RENAME_NOREPLACE,
)
};
if status == 0 {
return Ok(());
}
let error = io::Error::last_os_error();
if matches!(error.raw_os_error(), Some(libc::ENOSYS | libc::EOPNOTSUPP)) {
Err(unsupported(error))
} else {
Err(error)
}
}
#[cfg(test)]
mod tests {
use super::*;
use std::fs;
#[test]
fn missing_api_preserves_files_and_directories() {
let tmp = tempfile::tempdir().unwrap();
let from = tmp.path().join("source");
let to = tmp.path().join("target");
fs::write(&from, "source bytes").unwrap();
fs::write(&to, "existing bytes").unwrap();
let error = rename_with(None, &from, &to).unwrap_err();
assert_eq!(error.kind(), io::ErrorKind::Unsupported);
assert!(error.to_string().contains("renameat2 is missing"));
assert_eq!(fs::read_to_string(&from).unwrap(), "source bytes");
assert_eq!(fs::read_to_string(&to).unwrap(), "existing bytes");
fs::remove_file(&to).unwrap();
assert!(rename_with(None, &from, &to).is_err());
assert!(!to.exists());
fs::remove_file(&from).unwrap();
fs::create_dir(&from).unwrap();
assert!(rename_with(None, &from, &to).is_err());
assert!(from.is_dir());
assert!(!to.exists());
}
// Linux exposes the same function signature and no-replace flag, allowing
// this dynamic-lookup adapter to be exercised without a FreeBSD runtime.
#[cfg(target_os = "linux")]
#[test]
fn dynamic_api_moves_and_refuses_collisions() {
let tmp = tempfile::tempdir().unwrap();
let from = tmp.path().join("source");
let to = tmp.path().join("target");
fs::write(&from, "source bytes").unwrap();
fs::write(&to, "existing bytes").unwrap();
assert_eq!(
rename_no_replace(&from, &to).unwrap_err().kind(),
io::ErrorKind::AlreadyExists
);
assert_eq!(fs::read_to_string(&to).unwrap(), "existing bytes");
fs::remove_file(&to).unwrap();
rename_no_replace(&from, &to).unwrap();
assert_eq!(fs::read_to_string(&to).unwrap(), "source bytes");
assert!(!from.exists());
fs::remove_file(&to).unwrap();
fs::create_dir(&from).unwrap();
rename_no_replace(&from, &to).unwrap();
assert!(to.is_dir());
assert!(!from.exists());
}
}

View File

@ -12,6 +12,9 @@ use unicode_normalization::{UnicodeNormalization, char::is_combining_mark};
#[cfg(feature = "desktop")]
pub mod gui;
#[cfg(any(target_os = "freebsd", all(test, target_os = "linux")))]
mod freebsd;
/// ASCII equivalents for accented Latin text and common punctuation; unknowns become `_`.
/// Also removes names that are unsafe on common removable-drive filesystems.
pub fn ascii_name(name: &str) -> String {
@ -296,6 +299,10 @@ fn rename_no_replace(from: &Path, to: &Path) -> io::Result<()> {
)
.map_err(Into::into)
}
#[cfg(target_os = "freebsd")]
{
freebsd::rename_no_replace(from, to)
}
#[cfg(target_os = "windows")]
{
use std::os::windows::ffi::OsStrExt;
@ -311,7 +318,12 @@ fn rename_no_replace(from: &Path, to: &Path) -> io::Result<()> {
Ok(())
}
}
#[cfg(not(any(target_os = "linux", target_vendor = "apple", target_os = "windows")))]
#[cfg(not(any(
target_os = "linux",
target_vendor = "apple",
target_os = "windows",
target_os = "freebsd"
)))]
{
let _ = (from, to);
Err(io::Error::new(
@ -332,15 +344,58 @@ mod tests {
let dest = tmp.path().join("dest");
fs::write(&source, "new").unwrap();
fs::write(&dest, "original").unwrap();
assert!(rename_no_replace(&source, &dest).is_err());
#[cfg(target_os = "freebsd")]
{
// SAFETY: static C symbol name and the default loaded-library handle.
let symbol = unsafe { libc::dlsym(libc::RTLD_DEFAULT, c"renameat2".as_ptr()) };
if symbol.is_null() {
let error = rename_no_replace(&source, &dest).unwrap_err();
assert_eq!(error.kind(), io::ErrorKind::Unsupported);
assert_eq!(fs::read_to_string(&source).unwrap(), "new");
assert_eq!(fs::read_to_string(&dest).unwrap(), "original");
return;
}
}
let error = rename_no_replace(&source, &dest).unwrap_err();
assert_eq!(
error.kind(),
io::ErrorKind::AlreadyExists,
"Expected a destination collision in {}, got: {error}",
tmp.path().display()
);
assert_eq!(fs::read_to_string(&dest).unwrap(), "original");
assert_eq!(fs::read_to_string(&source).unwrap(), "new");
fs::remove_file(&source).unwrap();
fs::remove_file(&dest).unwrap();
fs::create_dir(&source).unwrap();
fs::create_dir(&dest).unwrap();
assert!(rename_no_replace(&source, &dest).is_err());
let error = rename_no_replace(&source, &dest).unwrap_err();
assert_eq!(
error.kind(),
io::ErrorKind::AlreadyExists,
"Expected a destination collision in {}, got: {error}",
tmp.path().display()
);
assert!(source.is_dir());
assert!(dest.is_dir());
let fresh = tmp.path().join("fresh");
rename_no_replace(&source, &fresh).unwrap_or_else(|error| {
panic!(
"No-replace directory rename failed in {}: {error}",
tmp.path().display()
)
});
assert!(fresh.is_dir());
assert!(!source.exists());
fs::write(&source, "new").unwrap();
let fresh_file = tmp.path().join("fresh-file");
rename_no_replace(&source, &fresh_file).unwrap_or_else(|error| {
panic!(
"No-replace file rename failed in {}: {error}",
tmp.path().display()
)
});
assert_eq!(fs::read_to_string(fresh_file).unwrap(), "new");
assert!(!source.exists());
}
}

View File

@ -12,6 +12,66 @@ fn options() -> Options {
}
}
// Older FreeBSD jails have no atomic no-replace API. Exercise their documented
// refusal rather than expecting successful renames or accepting other OS errors.
fn rename_test_dir() -> Option<tempfile::TempDir> {
let tmp = tempfile::tempdir().unwrap();
#[cfg(target_os = "freebsd")]
{
// SAFETY: a static C string and the default loaded-library search handle.
let symbol = unsafe { libc::dlsym(libc::RTLD_DEFAULT, c"renameat2".as_ptr()) };
if symbol.is_null() {
let file = tmp.path().join("été.txt");
let directory = tmp.path().join("été");
fs::write(&file, "unchanged").unwrap();
fs::create_dir(&directory).unwrap();
let mut messages = Vec::new();
let summary = clean(
tmp.path(),
options(),
&AtomicBool::new(false),
|_, message| messages.push(message),
)
.unwrap();
assert_eq!(summary.errors, 2, "{messages:?}");
assert_eq!(summary.renamed, 0);
assert_eq!(fs::read_to_string(file).unwrap(), "unchanged");
assert!(directory.is_dir());
assert!(!tmp.path().join("ete.txt").exists());
assert!(!tmp.path().join("ete").exists());
assert!(
messages
.iter()
.all(|m| m.contains("renameat2 is missing from the jail's libc")),
"{messages:?}"
);
let output = std::process::Command::new(env!("CARGO_BIN_EXE_ascii-names"))
.arg(tmp.path())
.args(["--delay-ms", "0"])
.output()
.unwrap();
assert!(!output.status.success());
assert!(
String::from_utf8_lossy(&output.stdout)
.contains("renameat2 is missing from the jail's libc")
);
assert_eq!(
fs::read_to_string(tmp.path().join("été.txt")).unwrap(),
"unchanged"
);
assert!(tmp.path().join("été").is_dir());
// Direct stderr keeps this platform limitation visible in successful CI output.
use std::io::Write;
let _ = writeln!(
std::io::stderr(),
"FreeBSD libc lacks renameat2: verified safe refusal; successful-rename assertions require a supported host."
);
return None;
}
}
Some(tmp)
}
#[test]
fn accents_punctuation_unknowns_and_portable_names() {
for (input, expected) in [
@ -42,7 +102,9 @@ fn accents_punctuation_unknowns_and_portable_names() {
#[test]
fn nested_cleanup_preserves_all_contents_and_is_idempotent() {
let tmp = tempfile::tempdir().unwrap();
let Some(tmp) = rename_test_dir() else {
return;
};
let root = tmp.path().join("Sélection");
fs::create_dir_all(root.join("Étage/été")).unwrap();
fs::write(root.join("Étage/été/vidéo.mov"), b"video bytes").unwrap();
@ -50,7 +112,10 @@ fn nested_cleanup_preserves_all_contents_and_is_idempotent() {
fs::write(root.join("résumé.txt"), b"accented").unwrap();
fs::write(root.join("résume.txt"), b"another").unwrap();
let cancel = AtomicBool::new(false);
let summary = clean(&root, options(), &cancel, |_, _| {}).unwrap();
let summary = clean(&root, options(), &cancel, |_, message| {
eprintln!("{message}")
})
.unwrap();
assert_eq!(summary.errors, 0);
assert_eq!(summary.renamed, 5);
assert_eq!(
@ -65,7 +130,11 @@ fn nested_cleanup_preserves_all_contents_and_is_idempotent() {
contents.sort();
assert_eq!(contents, [b"accented".to_vec(), b"another".to_vec()]);
assert_eq!(
clean(&root, options(), &cancel, |_, _| {}).unwrap().renamed,
clean(&root, options(), &cancel, |_, message| eprintln!(
"{message}"
))
.unwrap()
.renamed,
0
);
}
@ -96,13 +165,21 @@ fn preview_reserves_targets_and_changes_nothing() {
#[test]
fn directory_and_file_collisions_never_merge() {
let tmp = tempfile::tempdir().unwrap();
let Some(tmp) = rename_test_dir() else {
return;
};
fs::create_dir(tmp.path().join("Ete")).unwrap();
fs::create_dir(tmp.path().join("Été")).unwrap();
fs::write(tmp.path().join("Ete/original"), "keep").unwrap();
fs::write(tmp.path().join("Été/new"), "new").unwrap();
fs::write(tmp.path().join("été"), "file").unwrap();
let result = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap();
let result = clean(
tmp.path(),
options(),
&AtomicBool::new(false),
|_, message| eprintln!("{message}"),
)
.unwrap();
assert_eq!(result.errors, 0);
assert_eq!(
fs::read_to_string(tmp.path().join("Ete/original")).unwrap(),
@ -113,7 +190,9 @@ fn directory_and_file_collisions_never_merge() {
#[test]
fn cancellation_stops_between_renames_and_delay_is_applied() {
let tmp = tempfile::tempdir().unwrap();
let Some(tmp) = rename_test_dir() else {
return;
};
fs::write(tmp.path().join("é"), "a").unwrap();
fs::write(tmp.path().join("à"), "b").unwrap();
let cancel = AtomicBool::new(false);
@ -125,16 +204,21 @@ fn cancellation_stops_between_renames_and_delay_is_applied() {
dry_run: false,
},
&cancel,
|_, _| cancel.store(true, std::sync::atomic::Ordering::Relaxed),
|_, message| {
eprintln!("{message}");
cancel.store(true, std::sync::atomic::Ordering::Relaxed);
},
)
.unwrap();
assert!(result.cancelled);
assert_eq!(result.renamed, 1);
assert!(start.elapsed() >= Duration::from_millis(30));
assert!(
clean(tmp.path(), options(), &cancel, |_, _| {})
.unwrap()
.cancelled
clean(tmp.path(), options(), &cancel, |_, message| eprintln!(
"{message}"
))
.unwrap()
.cancelled
);
}
@ -143,9 +227,19 @@ fn missing_root_and_file_root_are_errors() {
let tmp = tempfile::tempdir().unwrap();
let file = tmp.path().join("file");
let cancel = AtomicBool::new(false);
assert!(clean(&file, options(), &cancel, |_, _| {}).is_err());
assert!(
clean(&file, options(), &cancel, |_, message| eprintln!(
"{message}"
))
.is_err()
);
fs::write(&file, "x").unwrap();
assert!(clean(&file, options(), &cancel, |_, _| {}).is_err());
assert!(
clean(&file, options(), &cancel, |_, message| eprintln!(
"{message}"
))
.is_err()
);
}
#[cfg(unix)]
@ -155,7 +249,9 @@ fn links_are_not_followed_and_invalid_utf8_is_cleaned() {
ffi::OsString,
os::unix::{ffi::OsStringExt, fs::symlink},
};
let tmp = tempfile::tempdir().unwrap();
let Some(tmp) = rename_test_dir() else {
return;
};
let outside = tempfile::tempdir().unwrap();
fs::write(outside.path().join("é.txt"), "outside").unwrap();
symlink(outside.path(), tmp.path().join("lïnk")).unwrap();
@ -166,7 +262,13 @@ fn links_are_not_followed_and_invalid_utf8_is_cleaned() {
"bytes",
)
.unwrap();
let result = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap();
let result = clean(
tmp.path(),
options(),
&AtomicBool::new(false),
|_, message| eprintln!("{message}"),
)
.unwrap();
assert_eq!(result.skipped, 2);
assert_eq!(result.errors, 0);
assert!(outside.path().join("é.txt").exists());
@ -183,7 +285,7 @@ fn links_are_not_followed_and_invalid_utf8_is_cleaned() {
&tmp.path().join("lïnk"),
options(),
&AtomicBool::new(false),
|_, _| {}
|_, message| eprintln!("{message}")
)
.is_err()
);
@ -191,7 +293,9 @@ fn links_are_not_followed_and_invalid_utf8_is_cleaned() {
#[test]
fn cli_preview_and_apply() {
let tmp = tempfile::tempdir().unwrap();
let Some(tmp) = rename_test_dir() else {
return;
};
fs::write(tmp.path().join("été.txt"), "content").unwrap();
let bin = env!("CARGO_BIN_EXE_ascii-names");
let output = std::process::Command::new(bin)
@ -199,16 +303,25 @@ fn cli_preview_and_apply() {
.arg("--dry-run")
.output()
.unwrap();
assert!(output.status.success());
assert!(tmp.path().join("été.txt").exists());
assert!(
std::process::Command::new(bin)
.arg(tmp.path())
.args(["--delay-ms", "0"])
.output()
.unwrap()
.status
.success()
output.status.success(),
"status: {}; stdout: {}; stderr: {}",
output.status,
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
assert!(tmp.path().join("été.txt").exists());
let output = std::process::Command::new(bin)
.arg(tmp.path())
.args(["--delay-ms", "0"])
.output()
.unwrap();
assert!(
output.status.success(),
"status: {}; stdout: {}; stderr: {}",
output.status,
String::from_utf8_lossy(&output.stdout),
String::from_utf8_lossy(&output.stderr)
);
assert_eq!(
fs::read_to_string(tmp.path().join("ete.txt")).unwrap(),
@ -226,7 +339,9 @@ fn cli_preview_and_apply() {
#[test]
fn many_names_with_same_fallback_keep_every_file() {
let tmp = tempfile::tempdir().unwrap();
let Some(tmp) = rename_test_dir() else {
return;
};
for (index, character) in (0x4e00..0x4e80).filter_map(char::from_u32).enumerate() {
fs::write(
tmp.path().join(format!("{character}.txt")),
@ -234,7 +349,13 @@ fn many_names_with_same_fallback_keep_every_file() {
)
.unwrap();
}
let summary = clean(tmp.path(), options(), &AtomicBool::new(false), |_, _| {}).unwrap();
let summary = clean(
tmp.path(),
options(),
&AtomicBool::new(false),
|_, message| eprintln!("{message}"),
)
.unwrap();
assert_eq!(summary.renamed, 128);
assert_eq!(summary.errors, 0);
let values: std::collections::HashSet<_> = fs::read_dir(tmp.path())

View File

@ -70,3 +70,21 @@ renames produce an error; the tool never falls back to an overwriting rename.
The crate is included in workspace tests, Clippy, Rustdoc and coverage. Regression
tests cover collisions, nested directories, previews, cancellation, pacing,
symlinks, invalid UTF-8 filenames on Unix, and content preservation.
### FreeBSD CI hosts
FreeBSD uses `renameat2` with `AT_RENAME_NOREPLACE` when available. The symbol is
resolved at runtime, so older jail userlands (including FreeBSD 12) can still
build, launch and preview. Actual cleanup on those systems returns an actionable
unsupported-operation error without renaming anything. No overwriting fallback
is used. The kernel, jail userland and filesystem must all support the operation.
See the [FreeBSD API documentation change](https://lists.freebsd.org/archives/dev-commits-src-branches/2026-March/028297.html).
On a FreeBSD jail whose libc lacks `renameat2`, the rename integration tests
verify safe refusal and unchanged sources instead of executing their successful
rename assertions; this limitation is printed in CI output. Preview and name
conversion tests still run normally. Hosts exposing the API run the full rename
tests; unexpected filesystem/permission/kernel errors still fail them. Successful
renames and collision protection must also be tested on a supported host (Linux,
macOS, Windows, or a FreeBSD installation with the API). Jenkins prints its OS
version, and failing tests retain the underlying rename errors and CLI output.

View File

@ -2,6 +2,10 @@
Jenkins must use a Multibranch Pipeline supplying `BRANCH_NAME`, with the
`rust_no_docker` worker, Python 3.11+ and Rust.
The current worker runs in a FreeBSD jail; the Tools stage logs `uname -sr`.
Older jails without `renameat2` verify the ASCII cleaner's safe refusal instead
of its successful-rename paths. Those paths must also run on a supported host;
see [FreeBSD test coverage](ascii-names.md#freebsd-ci-hosts).
SCM credentials, webhooks and the publication mount are administrator setup.
CI checks formatting, Clippy, rustdoc, Python/Rust tests and
whole-workspace Rust coverage. It never creates tags or release artifacts.