5a24289898fd
originals.rs
//! Never write over an original: exports, renders and other files LightCraft writes for the user
//! must not land on a catalogued photo's own file (or its XMP sidecar), whatever the conflict
//! setting or exact path asked for. [`OriginalGuard`] is a snapshot of the library's originals
//! that answers "would writing here replace one?" by file identity (the same file under another
//! spelling, through `..`, a link or a case-insensitive volume counts), not by comparing strings.
use std::collections::HashMap;
use std::path::{Path, PathBuf};
#[cfg(not(any(unix, windows)))]
use std::time::SystemTime;
use lightcraft_catalog::safe_file::{same_file, same_file_strict};
use lightcraft_catalog::{Catalog, Source};
/// The directory entry a screenshot is about to write, pinned at request admission.
///
/// A later write must not replace a path that was absent when the request was admitted (for
/// example a photo imported while the capture was waiting), nor a destination that was replaced by
/// another file in the meantime. [`Session::revalidate_write_target`] checks this immediately
/// before the write, and an absent destination is then published with create-new semantics.
#[derive(Clone, Debug)]
pub struct WriteTarget {
path: String,
state: WriteTargetState,
/// The canonical parent folder at admission, when it existed: a retargeted parent symlink is a
/// different destination even when the file name is unchanged.
parent: Option<PathBuf>,
}
#[derive(Clone, Debug)]
enum WriteTargetState {
/// The directory entry did not exist at admission.
Absent,
/// The directory entry existed; this is its identity (not its contents).
Existing(FileIdentity),
}
/// Stable identity of a directory entry, from `symlink_metadata` (so replacing a symlink or a
/// hard link is a different entry). Unix uses device + inode; Windows uses the canonical path,
/// length and creation time; other platforms use a canonical/len/mtime fallback.
#[derive(Clone, Debug, PartialEq, Eq)]
struct FileIdentity {
#[cfg(unix)]
dev: u64,
#[cfg(unix)]
ino: u64,
#[cfg(windows)]
canonical: PathBuf,
#[cfg(windows)]
len: u64,
#[cfg(windows)]
created: u64,
#[cfg(not(any(unix, windows)))]
canonical: PathBuf,
#[cfg(not(any(unix, windows)))]
len: u64,
#[cfg(not(any(unix, windows)))]
modified: Option<SystemTime>,
}
impl FileIdentity {
fn of(path: &Path, meta: &std::fs::Metadata) -> Self {
#[cfg(unix)]
{
use std::os::unix::fs::MetadataExt;
let _ = path;
Self { dev: meta.dev(), ino: meta.ino() }
}
#[cfg(windows)]
{
// The volume serial/file index metadata is still unstable; use stable metadata that
// changes when a different file replaces the entry, and keep the same in-place
// content edits (which do not change the creation time or length) overwritable.
use std::os::windows::fs::MetadataExt;
Self { canonical: std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf()), len: meta.len(), created: meta.creation_time() }
}
#[cfg(not(any(unix, windows)))]
{
Self { canonical: std::fs::canonicalize(path).unwrap_or_else(|_| path.to_path_buf()), len: meta.len(), modified: meta.modified().ok() }
}
}
}
impl WriteTarget {
/// The destination path as the request named it.
pub fn path(&self) -> &str {
&self.path
}
/// Was the directory entry absent at admission? Such a destination is published with
/// create-new semantics, never with the overwriting writer.
pub fn was_absent(&self) -> bool {
matches!(&self.state, WriteTargetState::Absent)
}
}
/// The library's originals and their sidecars, looked up by file name.
#[derive(Debug, Default)]
pub struct OriginalGuard {
/// lower-case file name → (path on disk, what it is: "the original of IMG_1.CR3", …)
by_name: HashMap<String, Vec<(PathBuf, String)>>,
/// Every indexed entry, built on the first check whose target name did not match: a hard
/// link or symlink may name an original differently from the catalogued path.
others: std::sync::OnceLock<Vec<(PathBuf, String)>>,
}
impl OriginalGuard {
/// The originals of every photo in `catalog`.
pub fn new(catalog: &Catalog) -> Self {
let mut g = Self::default();
for p in catalog.photos() {
if let Source::File { path } = &p.source {
g.add(Path::new(path), &p.file_name);
}
}
g
}
/// Protect `path` (an original named `label`) and its sidecars (`IMG_1.xmp`, `IMG_1.CR3.xmp`).
pub fn add(&mut self, path: &Path, label: &str) {
let Some(name) = path.file_name().map(|n| n.to_string_lossy().to_string()) else { return };
self.others = std::sync::OnceLock::new();
let mut put = |file: String, p: PathBuf, what: String| self.by_name.entry(file.to_lowercase()).or_default().push((p, what));
put(name.clone(), path.to_path_buf(), format!("the original of {label}"));
// every sidecar name the reader accepts (`.xmp`, `.XMP`, `.Xmp`, a recased photo extension), not only lowercase ones
let stem = path.file_stem().map(|s| s.to_string_lossy().to_string()).unwrap_or_default();
put(format!("{stem}.xmp"), path.with_extension("xmp"), format!("the XMP sidecar of {label}"));
put(format!("{name}.xmp"), PathBuf::from(format!("{}.xmp", path.to_string_lossy())), format!("the XMP sidecar of {label}"));
for c in crate::sidecar::sidecar_candidates(&path.to_string_lossy(), crate::sidecar::SidecarNaming::Stem) {
if let Some(file) = c.file_name().map(|n| n.to_string_lossy().to_string()) {
put(file, c, format!("the XMP sidecar of {label}"));
}
}
}
/// `Err` (a message for the user) when writing `target` would replace a protected file, or
/// create a protected sidecar that isn't there yet.
pub fn check(&self, target: &Path) -> Result<(), String> {
self.check_target(target, false)
}
/// [`Self::check`] plus hard links: a screenshot target must not replace an original reached
/// through a link with a different name. The per-entry identity scan is limited to this
/// long-lived, user-visible destination check, not every ordinary export overwrite.
pub fn check_identity(&self, target: &Path) -> Result<(), String> {
self.check_target(target, true)
}
fn check_target(&self, target: &Path, hard_links: bool) -> Result<(), String> {
if std::fs::symlink_metadata(target).is_err() {
return self.check_new(target); // nothing there to replace
}
let mut names: Vec<String> = target.file_name().map(|n| n.to_string_lossy().to_lowercase()).into_iter().collect();
if let Some(n) = std::fs::canonicalize(target).ok().and_then(|c| c.file_name().map(|n| n.to_string_lossy().to_lowercase())) {
names.push(n);
}
// The identity check refuses a target whose file identity cannot be read, so an unreadable
// hard link to an original is not taken for an ordinary file.
let refuse_if_same = |p: &Path, what: &str| -> Result<(), String> {
let same = if hard_links {
same_file_strict(p, target).map_err(|e| {
format!(
"{}: LightCraft cannot tell whether this is {what} in the library ({e}) and never writes over an original (choose another folder or file name)",
target.display()
)
})?
} else {
same_file(p, target)
};
if same {
return Err(format!(
"{} is {what} in the library: LightCraft never writes over an original (choose another folder or file name)",
target.display()
));
}
Ok(())
};
for n in &names {
for (p, what) in self.by_name.get(n).into_iter().flatten() {
refuse_if_same(p, what)?;
}
}
// An imported hard link or symlink can have a different name from its original. A write
// to that entry would change what the library reads. Only do this fallback for existing
// targets that the name index did not protect; the list is built once per guard, not once
// per target. Ordinary exports keep the cheaper symlink-only scan.
let others = self.others.get_or_init(|| self.by_name.values().flatten().cloned().collect());
for (p, what) in others {
if !hard_links && std::fs::read_link(p).is_err() {
continue;
}
refuse_if_same(p, what)?;
}
Ok(())
}
/// A new file with a sidecar's name in that sidecar's folder would be read back as the
/// photo's edits. The folders are compared by identity, so `sub/../` or a link counts.
fn check_new(&self, target: &Path) -> Result<(), String> {
if !is_xmp(target) {
return Ok(());
}
let Some(name) = target.file_name().map(|n| n.to_string_lossy().to_lowercase()) else { return Ok(()) };
for (p, what) in self.by_name.get(&name).into_iter().flatten() {
if same_file(folder_of(p), folder_of(target)) {
return Err(format!("{} would become {what} in the library (choose another folder or file name)", target.display()));
}
}
Ok(())
}
}
fn is_xmp(path: &Path) -> bool {
path.extension().is_some_and(|e| e.eq_ignore_ascii_case("xmp"))
}
/// The folder `path` is in (`.` for a bare file name).
fn folder_of(path: &Path) -> &Path {
path.parent().filter(|d| !d.as_os_str().is_empty()).unwrap_or(Path::new("."))
}
impl crate::Session {
/// A guard over this library's originals (see [`OriginalGuard`]).
pub fn original_guard(&self) -> OriginalGuard {
OriginalGuard::new(&self.catalog)
}
/// `Err` when writing `path` would replace a catalogued photo's original or sidecar, or
/// create one of its sidecars. A free path that isn't an `.xmp` (the usual case) is answered
/// without building the guard over the whole library.
pub fn check_write_target(&self, path: &str) -> Result<(), String> {
let path = Path::new(path);
if std::fs::symlink_metadata(path).is_err() {
// `missing/../IMG_1.jpg` names an existing file once the writer creates `missing`, so a
// `..` that cannot be resolved now cannot be checked: refuse it.
if path.components().any(|c| c == std::path::Component::ParentDir) && std::fs::canonicalize(folder_of(path)).is_err() {
return Err(format!("{}: the folder part has `..` components that cannot be resolved; use a path without them", path.display()));
}
if !is_xmp(path) {
return Ok(()); // nothing there to replace, and no sidecar to create
}
}
self.original_guard().check(path)
}
/// Pin the destination of a long-running write (a screenshot) now.
///
/// The returned [`WriteTarget`] records whether the directory entry existed and, if so, its
/// identity, plus the canonical parent folder. Pass it to [`Self::revalidate_write_target`]
/// immediately before writing.
pub fn pin_write_target(&self, path: &str) -> Result<WriteTarget, String> {
let p = Path::new(path);
let parent = p.parent().filter(|d| !d.as_os_str().is_empty()).and_then(|d| std::fs::canonicalize(d).ok());
match std::fs::symlink_metadata(p) {
Err(error) if error.kind() == std::io::ErrorKind::NotFound => {
// nothing there yet, but a new file with a photo's sidecar name would be read as its edits
if is_xmp(p) {
self.original_guard().check(p)?;
}
Ok(WriteTarget { path: path.to_string(), state: WriteTargetState::Absent, parent })
}
Err(error) => Err(format!("{path}: {error}")),
Ok(meta) => {
// Refuse a catalogued original or sidecar (including a differently named hard
// link) before the request is queued.
self.original_guard().check_identity(p)?;
Ok(WriteTarget { path: path.to_string(), state: WriteTargetState::Existing(FileIdentity::of(p, &meta)), parent })
}
}
}
/// Re-check a pinned target immediately before writing.
///
/// An absent target must still be absent; an existing target must still name the same
/// directory entry and must still pass the current catalog's original guard. A parent folder
/// whose canonical path changed (a retargeted symlink) is refused too.
pub fn revalidate_write_target(&self, target: &WriteTarget) -> Result<(), String> {
if let Some(parent) = &target.parent {
// Resolve the request's parent again: canonicalizing the saved resolved folder
// would miss a directory symlink in the original path being retargeted.
let now = Path::new(&target.path).parent().and_then(|path| std::fs::canonicalize(path).ok());
match now {
Some(now) if now == *parent => {}
_ => {
return Err(format!(
"{}: the destination folder changed while the screenshot was being captured; refusing to write",
target.path
));
}
}
}
match std::fs::symlink_metadata(&target.path) {
Err(error) if error.kind() == std::io::ErrorKind::NotFound => match &target.state {
WriteTargetState::Absent => Ok(()),
WriteTargetState::Existing(_) => {
Err(format!("{}: the file was removed while the screenshot was being captured; refusing to create it again", target.path))
}
},
Err(error) => Err(format!("{}: {error}", target.path)),
Ok(meta) => match &target.state {
WriteTargetState::Absent => Err(format!("{} appeared while the screenshot was being captured; refusing to replace it", target.path)),
WriteTargetState::Existing(identity) => {
if FileIdentity::of(Path::new(&target.path), &meta) != *identity {
return Err(format!("{} changed while the screenshot was being captured; refusing to replace the new file", target.path));
}
// The catalog may have gained this file as an original since admission.
self.original_guard().check_identity(Path::new(&target.path))
}
},
}
}
}
#[cfg(test)]
mod tests {
use super::*;
use lightcraft_catalog::{Op, Photo, PhotoId};
#[test]
fn originals_and_their_sidecars_are_protected_by_identity() {
let d = std::env::temp_dir().join(format!("lc-originals-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(d.join("sub")).unwrap();
let orig = d.join("IMG_1.jpg");
std::fs::write(&orig, b"original").unwrap();
std::fs::write(d.join("IMG_1.xmp"), b"<x/>").unwrap();
std::fs::write(d.join("other.jpg"), b"other").unwrap();
let mut c = Catalog::default();
let p = Photo::new(PhotoId(1), Source::File { path: orig.to_string_lossy().to_string() }, "IMG_1.jpg", "JPEG", 10, 10, "2026-01-01");
c.apply(Op::AddPhoto { photo: Box::new(p) }).unwrap();
let g = OriginalGuard::new(&c);
assert!(g.check(&orig).unwrap_err().contains("original of IMG_1.jpg"));
assert!(g.check(&d.join("sub/../IMG_1.jpg")).is_err(), "another spelling of the same file");
assert!(g.check(&d.join("IMG_1.xmp")).unwrap_err().contains("sidecar"));
assert!(g.check(&d.join("other.jpg")).is_ok(), "an ordinary existing file");
assert!(g.check(&d.join("new.jpg")).is_ok(), "a free name");
let _ = std::fs::remove_dir_all(&d);
}
#[test]
fn sidecars_the_reader_accepts_in_other_cases_are_protected() {
let d = std::env::temp_dir().join(format!("lc-originals-case-sidecar-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(&d).unwrap();
let orig = d.join("IMG_1.jpg");
std::fs::write(&orig, b"original").unwrap();
let mut c = Catalog::default();
let p = Photo::new(PhotoId(1), Source::File { path: orig.to_string_lossy().to_string() }, "IMG_1.jpg", "JPEG", 10, 10, "2026-01-01");
c.apply(Op::AddPhoto { photo: Box::new(p) }).unwrap();
let g = OriginalGuard::new(&c);
for name in ["IMG_1.XMP", "IMG_1.Xmp", "IMG_1.JPG.xmp", "IMG_1.jpg.XMP"] {
std::fs::write(d.join(name), b"<x/>").unwrap();
assert!(g.check(&d.join(name)).unwrap_err().contains("sidecar"), "{name}");
}
let _ = std::fs::remove_dir_all(&d);
}
#[test]
fn a_sidecar_that_isnt_there_yet_is_protected_too() {
let d = std::env::temp_dir().join(format!("lc-originals-new-sidecar-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(d.join("sub")).unwrap();
let orig = d.join("IMG_1.jpg");
std::fs::write(&orig, b"original").unwrap();
let mut c = Catalog::default();
let p = Photo::new(PhotoId(1), Source::File { path: orig.to_string_lossy().to_string() }, "IMG_1.jpg", "JPEG", 10, 10, "2026-01-01");
c.apply(Op::AddPhoto { photo: Box::new(p) }).unwrap();
let g = OriginalGuard::new(&c);
assert!(g.check(&d.join("IMG_1.xmp")).unwrap_err().contains("XMP sidecar of IMG_1.jpg"));
assert!(g.check(&d.join("IMG_1.jpg.xmp")).is_err(), "the appended spelling");
assert!(g.check(&d.join("sub/../IMG_1.xmp")).is_err(), "another spelling of the folder");
assert!(g.check(&d.join("sub/IMG_1.xmp")).is_ok(), "the same name in another folder");
assert!(g.check(&d.join("other.xmp")).is_ok(), "no photo of that name");
assert!(g.check(&d.join("missing/IMG_1.xmp")).is_ok(), "a folder that isn't there");
// a write pinned ahead of time (a queued screenshot) is refused the same way
let mut s = crate::Session::new();
s.catalog = c;
let pinned = s.pin_write_target(&d.join("IMG_1.xmp").to_string_lossy());
assert!(pinned.unwrap_err().contains("XMP sidecar of IMG_1.jpg"));
assert!(s.pin_write_target(&d.join("sub/IMG_1.xmp").to_string_lossy()).is_ok(), "the same name in another folder");
let _ = std::fs::remove_dir_all(&d);
}
#[test]
fn write_targets_pin_absent_paths_and_recheck_the_current_library() {
let d = std::env::temp_dir().join(format!("lc-write-targets-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(&d).unwrap();
let mut s = crate::Session::new();
let original = d.join("IMG_1.jpg");
std::fs::write(&original, b"original").unwrap();
let photo = Photo::new(PhotoId(1), Source::File { path: original.to_string_lossy().to_string() }, "IMG_1.jpg", "JPEG", 10, 10, "2026-01-01");
s.catalog.apply(Op::AddPhoto { photo: Box::new(photo) }).unwrap();
// A path that was absent at admission is refused when anything appears there.
let free = d.join("new-shot.png");
let absent = s.pin_write_target(&free.to_string_lossy()).expect("free path");
assert!(absent.was_absent());
std::fs::write(&free, b"appeared").unwrap();
assert!(s.revalidate_write_target(&absent).unwrap_err().contains("appeared"));
std::fs::remove_file(&free).unwrap();
// An ordinary existing path can still be overwritten in place (same entry).
let allowed = d.join("old-shot.png");
std::fs::write(&allowed, b"old").unwrap();
let existing = s.pin_write_target(&allowed.to_string_lossy()).expect("ordinary file");
assert!(!existing.was_absent());
std::fs::write(&allowed, b"new").unwrap();
assert!(s.revalidate_write_target(&existing).is_ok(), "an allowed screenshot refresh keeps working");
// A hard link to an original is refused at admission, and an absent path that becomes
// such a link is refused at write time.
let linked = d.join("linked.png");
std::fs::hard_link(&original, &linked).unwrap();
assert!(s.pin_write_target(&linked.to_string_lossy()).unwrap_err().contains("original"));
std::fs::remove_file(&linked).unwrap();
let appears_as_link = d.join("late-link.png");
let late = s.pin_write_target(&appears_as_link.to_string_lossy()).expect("free path");
std::fs::hard_link(&original, &appears_as_link).unwrap();
assert!(s.revalidate_write_target(&late).unwrap_err().contains("appeared"));
// A path pinned as an ordinary file becomes an original through a catalog import while
// the capture is queued: the current guard refuses the write.
let imported = d.join("imported.png");
std::fs::write(&imported, b"not yet imported").unwrap();
let queued = s.pin_write_target(&imported.to_string_lossy()).expect("ordinary file");
let p = Photo::new(PhotoId(2), Source::File { path: imported.to_string_lossy().to_string() }, "imported.png", "PNG", 10, 10, "2026-01-01");
s.catalog.apply(Op::AddPhoto { photo: Box::new(p) }).unwrap();
assert!(s.revalidate_write_target(&queued).unwrap_err().contains("original"));
#[cfg(unix)]
{
use std::os::unix::fs::symlink;
let link = d.join("link-shot.png");
symlink(&original, &link).unwrap();
assert!(s.pin_write_target(&link.to_string_lossy()).unwrap_err().contains("original"));
}
let _ = std::fs::remove_dir_all(&d);
}
#[cfg(windows)]
#[test]
fn a_hard_link_whose_identity_cannot_be_read_is_refused() {
use std::os::windows::fs::OpenOptionsExt;
let d = std::env::temp_dir().join(format!("lc-unreadable-link-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&d);
std::fs::create_dir_all(&d).unwrap();
let mut s = crate::Session::new();
let original = d.join("IMG_1.jpg");
std::fs::write(&original, b"original").unwrap();
let photo = Photo::new(PhotoId(1), Source::File { path: original.to_string_lossy().to_string() }, "IMG_1.jpg", "JPEG", 10, 10, "2026-01-01");
s.catalog.apply(Op::AddPhoto { photo: Box::new(photo) }).unwrap();
let linked = d.join("shot.png");
std::fs::hard_link(&original, &linked).unwrap();
// A handle that shares nothing makes every other open of the file fail, so the file
// identity of either name cannot be read while it is held.
let held = std::fs::OpenOptions::new().read(true).share_mode(0).open(&original).unwrap();
let refused = s.pin_write_target(&linked.to_string_lossy()).unwrap_err();
// Except with SeBackupPrivilege enabled (an admin's Git Bash, so every Windows CI gate leg):
// a backup-semantics open of both names, as the guard's identity read uses, gets past the
// held handle. The guard then sees the link and refuses it as the original instead (#3228).
const FILE_FLAG_BACKUP_SEMANTICS: u32 = 0x0200_0000;
let backup_open = |p: &std::path::Path| std::fs::OpenOptions::new().read(true).custom_flags(FILE_FLAG_BACKUP_SEMANTICS).open(p).is_ok();
if backup_open(&original) && backup_open(&linked) {
assert!(refused.contains("is the original"), "{refused}");
assert!(!refused.contains("cannot tell whether"), "{refused}");
lightcraft_testkit::skip!(
System,
"a backup-semantics open gets past share_mode(0) here (SeBackupPrivilege is enabled), so the \"cannot tell whether\" refusal can't be tested"
);
} else {
assert!(refused.contains("cannot tell whether"), "{refused}");
}
drop(held);
let refused = s.pin_write_target(&linked.to_string_lossy()).unwrap_err();
assert!(refused.contains("original"), "{refused}");
assert!(!refused.contains("cannot tell whether"), "{refused}");
let _ = std::fs::remove_dir_all(&d);
}
}
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.