5a24289898fd
opened_folder.rs
//! The folder a library was opened from, and whether its path still leads to it (issue #3240).
//!
//! A library's files are written by path (`<library>/catalog.snap`, …), and a path can come to lead
//! somewhere else while the library is open: a share mounted over the folder, or the folder moved
//! away and another one put at its path. A session that went on writing then replaced the catalog
//! of the library on the share with its own.
//!
//! [`OpenedFolder`] remembers which folder the path named when the library was opened;
//! [`OpenedFolder::check`] asks, with one `stat`, whether it still does. Every write of a library
//! file asks first ([`crate::FsStore`], its log thread, [`crate::LibraryLock`]) and is refused,
//! writing nothing, when the answer is no. The refusal is an ordinary write error, so the changes
//! stay queued and the app says why they aren't saved. The next write asks again: with the folder
//! that was opened back at the path, saving goes on.
//!
//! - **Unix:** a folder is its device and inode number. A volume that is mounted again (a drive
//! plugged in again, a share reconnected) gets another device number: its folder counts as the
//! same when its inode number and its creation time agree (without one: the note below), so
//! saving goes on there as it did before this check. A clone of the volume, with the same inode
//! numbers and creation times, counts as that volume mounted again: nothing the check can see
//! tells them apart. A folder moved away keeps its own inode number; one deleted and made again
//! may be given the same inode number back, so on the same device two creation times that are
//! both known must agree too.
//! - **The note of the lock:** some file systems number a folder anew each time they are mounted
//! (FAT and exFAT on Linux, sshfs, cifs without server inode numbers) and some keep no creation
//! time to go by (NFS). A folder that holds exactly the owner note this session's lock wrote
//! ([`OpenedFolder::vouch`]) is the opened folder whatever its numbers say: the note holds a
//! value found in no other lock's note, so no other library has it. A copy of this library's
//! folder made while it was open does, and counts as the library (the log in it is checked when
//! it is written to: [`crate::FsStore`]); a share mounted over the folder, with a library of its
//! own or none, never does.
//! - **Windows:** `std` offers the volume serial number and the file index only on nightly
//! (`windows_by_handle`, rust-lang/rust#63010), so there is no identity to compare yet. The check
//! only asks that the path is still a folder, and a share mounted over a folder isn't noticed.
//! - A check is not a lock: a folder replaced between the `stat` and the write that follows it is
//! still written to. Closing that window takes I/O relative to an open directory handle
//! (`openat`, `renameat`), which the library doesn't use.
use std::io;
use std::path::{Path, PathBuf};
use std::sync::atomic::{AtomicBool, Ordering};
use std::sync::{Arc, OnceLock};
use std::time::SystemTime;
/// Which folder a path named: the device and the inode number the system reports for it, and when
/// the folder was made where the file system keeps that.
#[derive(Clone, Copy, Debug)]
#[cfg_attr(not(unix), allow(dead_code))]
struct FolderId {
dev: u64,
ino: u64,
born: Option<SystemTime>,
}
impl FolderId {
#[cfg(unix)]
fn of(folder: &std::fs::Metadata) -> Option<FolderId> {
use std::os::unix::fs::MetadataExt;
Some(FolderId { dev: folder.dev(), ino: folder.ino(), born: made_at(folder.created()) })
}
#[cfg(not(unix))]
fn of(_: &std::fs::Metadata) -> Option<FolderId> {
None
}
/// Whether `other` is the same folder: the same inode number, and then, where both creation
/// times are known, the same creation time, else the same device number. A volume that is mounted
/// again gets another device number, and saving went on there before there was a check; two
/// creation times that differ are two folders, also on one device (an inode number is given
/// again to a folder made later). Without both times another device is another folder: a
/// refused save is better than a write into another volume's folder with that inode number.
fn is(&self, other: &FolderId) -> bool {
self.ino == other.ino
&& match (self.born, other.born) {
(Some(was), Some(now)) => was == now,
_ => self.dev == other.dev,
}
}
}
/// When a folder was made, where the file system says. macOS reports 0 (the Unix epoch) for a file
/// system that keeps no creation time (NFS, macFUSE): the same for every folder there, so no folder
/// is told from another by it.
#[cfg(unix)]
fn made_at(created: io::Result<SystemTime>) -> Option<SystemTime> {
created.ok().filter(|t| *t != SystemTime::UNIX_EPOCH)
}
/// The folder a library was opened from (see the module docs). Clones share one record, so the
/// stores, the log's thread and the lock of a library all ask about the same folder.
#[derive(Clone, Debug)]
pub struct OpenedFolder {
inner: Arc<Inner>,
}
#[derive(Debug)]
struct Inner {
path: PathBuf,
/// `None` where the system gives a folder no identity (Windows, for now).
id: Option<FolderId>,
/// The last check refused: a change is logged when it starts and when it ends, not at every write.
refused: AtomicBool,
/// The owner note this session's lock wrote into the folder (see [`OpenedFolder::vouch`]); set once.
note: OnceLock<Vec<u8>>,
}
impl OpenedFolder {
/// The folder `path` names now (a link is followed). Fails when it names no folder.
pub fn at(path: &Path) -> io::Result<OpenedFolder> {
let folder = std::fs::metadata(path)?;
if !folder.is_dir() {
return Err(io::Error::other(format!("{} is not a folder", path.display())));
}
Ok(OpenedFolder::new(path, FolderId::of(&folder)))
}
fn new(path: &Path, id: Option<FolderId>) -> OpenedFolder {
OpenedFolder { inner: Arc::new(Inner { path: path.to_path_buf(), id, refused: AtomicBool::new(false), note: OnceLock::new() }) }
}
/// The path the folder was opened by.
pub fn path(&self) -> &Path {
&self.inner.path
}
/// `other` was recorded for the same folder (always, where folders have no identity). A folder
/// that holds the note this session's lock wrote is the same whatever its numbers say
/// ([`OpenedFolder::vouch`]): the library opened again after a drive was mounted again keeps its lock.
pub fn same_folder(&self, other: &OpenedFolder) -> bool {
match (self.inner.id, other.inner.id) {
(Some(a), Some(b)) => a.is(&b) || self.holds_note(other.path()),
(a, b) => a.is_none() && b.is_none(),
}
}
/// Record the owner note this session's lock wrote into the folder ([`crate::LibraryLock`]); the
/// first one is kept. From then on a folder at the path that holds exactly these bytes is the
/// opened folder even when its numbers say otherwise: some file systems number a folder anew at
/// every mount (FAT and exFAT on Linux, sshfs), so a drive plugged in again would be refused for
/// the rest of the session. The bytes are this lock's alone (the process, the program, the time
/// it was taken and a value found in no other note): another library's folder doesn't have them
/// (issue #3240), only a copy of this one made while it was open, which counts as it.
pub fn vouch(&self, note: &[u8]) {
let _ = self.inner.note.set(note.to_vec());
}
/// The note [`OpenedFolder::vouch`] recorded (`None`: none was, the numbers decide alone).
pub fn note(&self) -> Option<&[u8]> {
self.inner.note.get().map(Vec::as_slice)
}
/// `Ok` while the path leads to the folder that was opened (or to one that holds this session's
/// note: [`OpenedFolder::vouch`]); else an error that says what is there now and what to do.
pub fn check(&self) -> io::Result<()> {
let inner = &*self.inner;
let now = match std::fs::metadata(&inner.path) {
Ok(now) => now,
Err(e) if e.kind() == io::ErrorKind::NotFound => return Err(self.refuse("nothing is there now")),
// The drive doesn't answer: the write would fail the same way, with less to go on.
Err(e) => {
let what = format!("can't tell whether {} is still the folder this library was opened from: {e}", inner.path.display());
return Err(io::Error::new(e.kind(), what));
}
};
if !now.is_dir() {
return Err(self.refuse("it isn't a folder now"));
}
if let (Some(was), Some(is)) = (inner.id, FolderId::of(&now))
&& !was.is(&is)
&& !self.holds_note(&inner.path)
{
// (the same device number is the same volume's: another folder on it was put at the path)
return Err(self.refuse(if was.dev == is.dev { "it was moved or replaced" } else { "a different drive or share is there now" }));
}
if inner.refused.swap(false, Ordering::Relaxed) {
log::info!("library folder {}: the folder this library was opened from is back", inner.path.display());
}
Ok(())
}
/// The error for a path that doesn't lead to the opened folder, `what` being what is there.
fn refuse(&self, what: &str) -> io::Error {
let path = self.inner.path.display();
let why = format!(
"{path} is no longer the folder this library was opened from ({what}), so nothing is written to it: put the original folder back"
);
if !self.inner.refused.swap(true, Ordering::Relaxed) {
log::warn!("library folder {why}");
}
io::Error::other(why)
}
/// Whether the folder at `dir` holds the note this session's lock wrote ([`OpenedFolder::vouch`]).
fn holds_note(&self, dir: &Path) -> bool {
self.note().is_some_and(|ours| holds_exactly(&dir.join(crate::lock::OWNER), ours))
}
}
/// Whether `path` is a plain file that holds exactly `bytes`. A link, a folder or a file of another
/// size is no match and is not read (a pipe would block, a large file would be read for nothing).
pub(crate) fn holds_exactly(path: &Path, bytes: &[u8]) -> bool {
let plain = std::fs::symlink_metadata(path).is_ok_and(|m| m.is_file() && m.len() == bytes.len() as u64);
plain && std::fs::read(path).is_ok_and(|now| now == bytes)
}
#[cfg(all(test, unix))]
impl OpenedFolder {
/// `path` as a volume that numbers its folders anew at every mount would have recorded it: other
/// device and inode numbers than the folder has now, and no creation time (a mount can't be
/// faked in a test).
pub(crate) fn recorded_under_other_numbers(path: &Path) -> OpenedFolder {
let now = std::fs::metadata(path).ok().and_then(|m| FolderId::of(&m));
OpenedFolder::new(path, now.map(|n| FolderId { dev: n.dev.wrapping_add(1), ino: n.ino.wrapping_add(1), born: None }))
}
}
#[cfg(test)]
mod tests {
use super::*;
#[cfg(unix)]
fn scratch(tag: &str) -> PathBuf {
let dir = std::env::temp_dir().join(format!("lc-opened-folder-unit-{tag}-{}", std::process::id()));
let _ = std::fs::remove_dir_all(&dir);
std::fs::create_dir_all(&dir).unwrap();
dir
}
fn id(dev: u64, ino: u64, born: Option<u64>) -> FolderId {
FolderId { dev, ino, born: born.map(|s| SystemTime::UNIX_EPOCH + std::time::Duration::from_secs(s)) }
}
/// A folder is the same one when its inode number agrees and then its device number does or, where
/// both creation times are known, its creation time: a volume that is mounted again has another
/// device number, and an inode number is given again to a folder made later. Anything less sure
/// is another folder.
#[test]
fn a_folder_on_a_volume_mounted_again_is_the_same_folder_only_when_it_was_made_at_the_same_time() {
let was = id(7, 100, Some(1_000));
assert!(was.is(&id(7, 100, Some(1_000))), "the same");
assert!(!was.is(&id(7, 100, Some(2_000))), "the inode number of a folder that is gone, given to one made later");
assert!(was.is(&id(9, 100, Some(1_000))), "mounted again under another device number");
assert!(!was.is(&id(9, 100, Some(2_000))), "another volume's folder that has that inode number");
assert!(!was.is(&id(9, 100, None)), "no creation time to tell by");
assert!(!id(7, 100, None).is(&id(9, 100, None)), "none known at all");
assert!(id(7, 100, None).is(&id(7, 100, None)), "the same device, and none to tell by");
assert!(id(7, 100, None).is(&id(7, 100, Some(1_000))), "a creation time known for one folder only is no reason to refuse");
assert!(!was.is(&id(7, 101, Some(1_000))), "another folder on the volume");
assert!(!was.is(&id(9, 101, Some(1_000))), "another folder on another volume");
}
/// The same rule in a check, with the device number recorded at open made different from the
/// one reported now (a mount can't be faked in a test).
#[cfg(unix)]
#[test]
fn a_check_accepts_a_remounted_volume_and_refuses_another_volumes_folder() {
let dir = scratch("remount");
let real = FolderId::of(&std::fs::metadata(&dir).unwrap()).unwrap();
let recorded = |id: FolderId| OpenedFolder::new(&dir, Some(id));
let remounted = recorded(FolderId { dev: real.dev.wrapping_add(1), ..real });
match real.born {
Some(_) => remounted.check().expect("the same inode number and creation time: the same folder, mounted again"),
None => assert!(remounted.check().is_err(), "no creation time to tell by: refused"),
}
let other = recorded(FolderId { dev: real.dev.wrapping_add(1), ino: real.ino.wrapping_add(1), ..real });
let msg = other.check().expect_err("another volume's folder").to_string();
assert!(msg.contains("a different drive or share is there now"), "{msg}");
let _ = std::fs::remove_dir_all(&dir);
}
/// The same rule in a check, with the creation time recorded at open made different from the one
/// reported now (a folder made again under the inode number of one that was deleted can't be
/// arranged in a test): the same device and inode number with another creation time is another
/// folder, unless it holds the note this session's lock wrote.
#[cfg(unix)]
#[test]
fn a_folder_made_again_under_the_same_inode_number_is_another_folder_unless_it_holds_the_note() {
let dir = scratch("made-again");
let real = FolderId::of(&std::fs::metadata(&dir).unwrap()).unwrap();
let Some(born) = real.born else {
OpenedFolder::new(&dir, Some(real)).check().expect("no creation time to tell by: the numbers decide");
return;
};
let earlier = OpenedFolder::new(&dir, Some(FolderId { born: Some(born + std::time::Duration::from_secs(3600)), ..real }));
let msg = earlier.check().expect_err("the same numbers, made at another time").to_string();
assert!(msg.contains("it was moved or replaced"), "{msg}");
assert!(!earlier.same_folder(&OpenedFolder::at(&dir).unwrap()), "not the folder that lock was taken in");
let note = b"the note of the lock";
earlier.vouch(note);
std::fs::write(dir.join(crate::lock::OWNER), note).unwrap();
earlier.check().expect("this session's note: the folder it locked, whatever its numbers say");
assert!(earlier.same_folder(&OpenedFolder::at(&dir).unwrap()));
let _ = std::fs::remove_dir_all(&dir);
}
/// macOS reports a creation time of 0 for a file system that keeps none (NFS, macFUSE), the same
/// for every folder on it: that is no creation time, or any two such folders that have an inode
/// number in common would be taken for one folder mounted again.
#[cfg(unix)]
#[test]
fn a_creation_time_of_zero_is_no_creation_time() {
let made = SystemTime::UNIX_EPOCH + std::time::Duration::from_secs(1_700_000_000);
assert_eq!(made_at(Ok(made)), Some(made));
assert_eq!(made_at(Ok(SystemTime::UNIX_EPOCH)), None);
assert_eq!(made_at(Err(io::Error::other("this file system keeps none"))), None);
}
/// A file system that numbers its folders anew at every mount (FAT and exFAT on Linux, sshfs)
/// gives a folder that was opened other numbers: it is that folder when it holds the note this
/// session's lock wrote, and no other folder is. (A mount can't be faked in a test: the numbers
/// recorded at open are made different from the folder's.)
#[cfg(unix)]
#[test]
fn a_folder_with_other_numbers_is_the_opened_one_only_while_it_holds_the_note_the_lock_wrote() {
let dir = scratch("note");
let note = br#"{"pid":4242,"host":"here","program":"LightCraft","version":"0.2.0","since":1}"#;
let renumbered = OpenedFolder::recorded_under_other_numbers(&dir);
let msg = renumbered.check().expect_err("other numbers, and no note vouched for").to_string();
assert!(msg.contains("a different drive or share is there now"), "{msg}");
renumbered.vouch(note);
assert_eq!(renumbered.note(), Some(note.as_slice()));
let path = dir.join(crate::lock::OWNER);
assert!(renumbered.check().is_err(), "the note is vouched for, the folder holds none");
let longer = [note.as_slice(), b" ".as_slice()].concat();
for other in [note.to_ascii_uppercase(), longer, note[1..].to_vec(), Vec::new()] {
std::fs::write(&path, &other).unwrap();
assert!(renumbered.check().is_err(), "another note: {}", String::from_utf8_lossy(&other));
}
std::fs::write(&path, note).unwrap();
renumbered.check().expect("this session's note: the folder it locked, whatever its numbers say");
// what is no note: a link to one, a folder
let elsewhere = dir.join("elsewhere");
std::fs::rename(&path, &elsewhere).unwrap();
std::os::unix::fs::symlink(&elsewhere, &path).unwrap();
assert!(renumbered.check().is_err(), "a link to the bytes is no note");
std::fs::remove_file(&path).unwrap();
std::fs::create_dir(&path).unwrap();
assert!(renumbered.check().is_err(), "a folder is no note");
// the first note is the one that counts
renumbered.vouch(b"another");
assert_eq!(renumbered.note(), Some(note.as_slice()));
let _ = std::fs::remove_dir_all(&dir);
}
/// The lock is handed over to a library opened again from the same folder, and a folder that
/// holds the note this session's lock wrote is that folder whatever its numbers say (a drive
/// that was mounted again): not one with no such note.
#[cfg(unix)]
#[test]
fn a_folder_that_holds_the_locks_note_is_the_same_folder_for_the_hand_over() {
let dir = scratch("hand-over");
let other = scratch("hand-over-other");
let note = b"the note of the lock";
let at_open = OpenedFolder::recorded_under_other_numbers(&dir);
let now = OpenedFolder::at(&dir).unwrap();
assert!(!at_open.same_folder(&now), "other numbers, no note");
at_open.vouch(note);
assert!(!at_open.same_folder(&now), "the note is vouched for, the folder holds none");
std::fs::write(dir.join(crate::lock::OWNER), note).unwrap();
assert!(at_open.same_folder(&now));
assert!(!at_open.same_folder(&OpenedFolder::at(&other).unwrap()), "another folder holds no such note");
let _ = std::fs::remove_dir_all(&dir);
let _ = std::fs::remove_dir_all(&other);
}
}
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.