diff --git a/AGENTS-TASKS.md b/AGENTS-TASKS.md index fed572c..3cfcb31 100644 --- a/AGENTS-TASKS.md +++ b/AGENTS-TASKS.md @@ -97,8 +97,11 @@ portable release gates. - [x] Implement explicit `migrate --to 2` planning and confirmation with read-only validation, monotonic ID allocation, complete transient snapshots, a byte-for-byte manifest backup, and manifest-last commit semantics. -- [ ] Add transaction journaling, exclusive writer locks, deterministic - recovery, and automatic pre-commit migration rollback. +- [x] Add durable single-file transaction journaling, exclusive writer locks, + lock inspection/break primitives, and deterministic interrupted-write + recovery. +- [ ] Extend transactions across multi-file commits and add automatic + pre-commit migration rollback. - [ ] Implement worktree/index-aware `status`, `diff`, `stage`, and both restore directions without changing immutable epochs. - [ ] Implement committed epochs, `log`, conflict-safe `revert`, and backed-up diff --git a/lib_efo/src/lib.rs b/lib_efo/src/lib.rs index 6f9940b..35b9ff0 100644 --- a/lib_efo/src/lib.rs +++ b/lib_efo/src/lib.rs @@ -21,6 +21,7 @@ pub mod naming; pub mod output; pub mod repository_format; pub mod stats; +pub mod transaction; pub mod utils; // use std::io::Result as IoResult; diff --git a/lib_efo/src/transaction.rs b/lib_efo/src/transaction.rs new file mode 100644 index 0000000..dfb8cab --- /dev/null +++ b/lib_efo/src/transaction.rs @@ -0,0 +1,273 @@ +//! Exclusive repository writes and recoverable single-file transactions. + +use std::{ + fs::{self, File, OpenOptions}, + io::Write, + path::{Path, PathBuf}, + time::{SystemTime, UNIX_EPOCH}, +}; + +use serde::{Deserialize, Serialize}; + +/// Metadata describing the process that owns a repository writer lock. +#[derive(Debug, Clone, Serialize, Deserialize)] +pub struct LockInfo { + /// Operating-system process identifier. + pub pid: u32, + /// Host identifier when available. + pub hostname: String, + /// User-facing operation holding the lock. + pub command: String, + /// Unix timestamp at lock acquisition. + pub created_at: u64, +} + +/// An exclusively held writer lock, removed automatically on clean exit. +#[derive(Debug)] +pub struct RepositoryLock { + /// Path removed when the guard is dropped. + path: PathBuf, +} + +/// Durable record for an interrupted file replacement. +#[derive(Debug, Clone, Serialize, Deserialize)] +struct TransactionJournal { + /// Destination path relative to `.efo`'s parent. + destination: PathBuf, + /// Prepared replacement path relative to `.efo`'s parent. + temporary: PathBuf, + /// Checksum of the complete replacement. + new_checksum: String, +} + +/// Result of inspecting recovery state. +#[derive(Debug, Clone, Copy, PartialEq, Eq)] +pub enum RecoveryOutcome { + /// No journal was present. + Clean, + /// A prepared but uncommitted replacement was discarded. + RolledBack, + /// A committed replacement was verified and its journal removed. + Completed, +} + +/// Transaction and locking failures. +#[derive(Debug, thiserror::Error)] +pub enum TransactionError { + /// A filesystem operation failed. + #[error("repository transaction failed at `{path}`: {source}")] + Io { + /// Affected path. + path: PathBuf, + /// Underlying error. + #[source] + source: std::io::Error, + }, + /// Another writer already owns the repository. + #[error("repository is locked by PID {pid} on {hostname} running `{command}`")] + Locked { + /// Owner process ID. + pid: u32, + /// Owner host. + hostname: String, + /// Owner operation. + command: String, + }, + /// Lock data or a transaction journal is malformed. + #[error("repository transaction metadata at `{path}` is invalid: {source}")] + Json { + /// Affected path. + path: PathBuf, + /// Decode error. + #[source] + source: serde_json::Error, + }, + /// Recovery cannot safely infer the intended state. + #[error("cannot recover transaction: {0}")] + Ambiguous(String), +} + +impl RepositoryLock { + /// Acquire the one exclusive writer slot for a format-2 repository. + pub fn acquire(root: &Path, command: impl Into) -> Result { + let path = root.join(".efo/lock"); + let info = LockInfo { + pid: std::process::id(), + hostname: std::env::var("HOSTNAME").unwrap_or_else(|_| "unknown-host".to_owned()), + command: command.into(), + created_at: now()?, + }; + let bytes = serde_json::to_vec_pretty(&info).map_err(|source| TransactionError::Json { + path: path.clone(), + source, + })?; + let mut file = match OpenOptions::new().write(true).create_new(true).open(&path) { + Ok(file) => file, + Err(source) if source.kind() == std::io::ErrorKind::AlreadyExists => { + let owner = inspect_lock(root)?; + return Err(TransactionError::Locked { + pid: owner.pid, + hostname: owner.hostname, + command: owner.command, + }); + } + Err(source) => return Err(io_error(path, source)), + }; + file.write_all(&bytes) + .and_then(|_| file.sync_all()) + .map_err(|source| io_error(path.clone(), source))?; + sync_directory(path.parent().unwrap_or(root))?; + Ok(Self { path }) + } +} + +impl Drop for RepositoryLock { + fn drop(&mut self) { + let _ = fs::remove_file(&self.path); + if let Some(parent) = self.path.parent() { + let _ = File::open(parent).and_then(|directory| directory.sync_all()); + } + } +} + +/// Read current writer ownership without modifying the lock. +pub fn inspect_lock(root: &Path) -> Result { + let path = root.join(".efo/lock"); + let bytes = fs::read(&path).map_err(|source| io_error(path.clone(), source))?; + serde_json::from_slice(&bytes).map_err(|source| TransactionError::Json { path, source }) +} + +/// Break a lock only after the caller has made the explicit safety decision. +pub fn break_lock(root: &Path) -> Result { + let owner = inspect_lock(root)?; + let path = root.join(".efo/lock"); + fs::remove_file(&path).map_err(|source| io_error(path.clone(), source))?; + sync_directory(path.parent().unwrap_or(root))?; + Ok(owner) +} + +/// Atomically replace one repository file under an exclusive lock. +pub fn replace_file( + root: &Path, + destination: &Path, + bytes: &[u8], + command: &str, +) -> Result<(), TransactionError> { + let _lock = RepositoryLock::acquire(root, command)?; + recover_unlocked(root)?; + let workspace = root.join(".efo"); + let journal_path = workspace.join("transaction.json"); + let temporary = workspace.join(format!("transaction-{}.tmp", std::process::id())); + let mut file = + File::create(&temporary).map_err(|source| io_error(temporary.clone(), source))?; + file.write_all(bytes) + .and_then(|_| file.sync_all()) + .map_err(|source| io_error(temporary.clone(), source))?; + let destination_relative = destination.strip_prefix(root).map_err(|_| { + TransactionError::Ambiguous(format!( + "destination `{}` is outside repository `{}`", + destination.display(), + root.display() + )) + })?; + let journal = TransactionJournal { + destination: destination_relative.to_path_buf(), + temporary: temporary + .strip_prefix(root) + .map_err(|_| TransactionError::Ambiguous("temporary path escaped repository".into()))? + .to_path_buf(), + new_checksum: checksum(bytes), + }; + write_json_synced(&journal_path, &journal)?; + fs::rename(&temporary, destination) + .map_err(|source| io_error(destination.to_path_buf(), source))?; + sync_directory(destination.parent().unwrap_or(root))?; + fs::remove_file(&journal_path).map_err(|source| io_error(journal_path.clone(), source))?; + sync_directory(&workspace) +} + +/// Recover an interrupted replacement while holding a new writer lock. +pub fn recover(root: &Path) -> Result { + let _lock = RepositoryLock::acquire(root, "recover")?; + recover_unlocked(root) +} + +/// Resolve a journal after exclusive ownership has already been acquired. +fn recover_unlocked(root: &Path) -> Result { + let journal_path = root.join(".efo/transaction.json"); + if !journal_path.exists() { + return Ok(RecoveryOutcome::Clean); + } + let bytes = fs::read(&journal_path).map_err(|source| io_error(journal_path.clone(), source))?; + let journal: TransactionJournal = + serde_json::from_slice(&bytes).map_err(|source| TransactionError::Json { + path: journal_path.clone(), + source, + })?; + let destination = root.join(&journal.destination); + let temporary = root.join(&journal.temporary); + let outcome = if temporary.exists() { + fs::remove_file(&temporary).map_err(|source| io_error(temporary, source))?; + RecoveryOutcome::RolledBack + } else if destination.exists() { + let current = + fs::read(&destination).map_err(|source| io_error(destination.clone(), source))?; + if checksum(¤t) != journal.new_checksum { + return Err(TransactionError::Ambiguous(format!( + "`{}` matches neither prepared nor committed content", + destination.display() + ))); + } + RecoveryOutcome::Completed + } else { + return Err(TransactionError::Ambiguous( + "both prepared and destination files are missing".to_owned(), + )); + }; + fs::remove_file(&journal_path).map_err(|source| io_error(journal_path.clone(), source))?; + sync_directory(journal_path.parent().unwrap_or(root))?; + Ok(outcome) +} + +/// Write durable JSON metadata before a transaction commit point. +fn write_json_synced(path: &Path, value: &T) -> Result<(), TransactionError> { + let bytes = serde_json::to_vec_pretty(value).map_err(|source| TransactionError::Json { + path: path.to_path_buf(), + source, + })?; + let mut file = File::create(path).map_err(|source| io_error(path.to_path_buf(), source))?; + file.write_all(&bytes) + .and_then(|_| file.sync_all()) + .map_err(|source| io_error(path.to_path_buf(), source))?; + sync_directory(path.parent().unwrap_or_else(|| Path::new("."))) +} + +/// Flush directory metadata. +fn sync_directory(path: &Path) -> Result<(), TransactionError> { + File::open(path) + .and_then(|directory| directory.sync_all()) + .map_err(|source| io_error(path.to_path_buf(), source)) +} + +/// Current Unix time for human lock inspection. +fn now() -> Result { + SystemTime::now() + .duration_since(UNIX_EPOCH) + .map(|duration| duration.as_secs()) + .map_err(|_| TransactionError::Ambiguous("system clock is before Unix epoch".to_owned())) +} + +/// Stable accidental-corruption checksum for transaction decisions. +fn checksum(bytes: &[u8]) -> String { + format!( + "{:016x}", + bytes.iter().fold(0xcbf2_9ce4_8422_2325, |hash, byte| { + (hash ^ u64::from(*byte)).wrapping_mul(0x0000_0100_0000_01b3) + }) + ) +} + +/// Attach an affected path to an I/O failure. +fn io_error(path: PathBuf, source: std::io::Error) -> TransactionError { + TransactionError::Io { path, source } +} diff --git a/lib_efo/tests/transactions.rs b/lib_efo/tests/transactions.rs new file mode 100644 index 0000000..5d5c4af --- /dev/null +++ b/lib_efo/tests/transactions.rs @@ -0,0 +1,50 @@ +use std::fs; + +use lib_efo::transaction::{ + RecoveryOutcome, RepositoryLock, TransactionError, break_lock, inspect_lock, recover, + replace_file, +}; + +#[test] +fn writer_lock_is_exclusive_and_inspectable() { + let directory = tempfile::tempdir().expect("temporary repository"); + fs::create_dir(directory.path().join(".efo")).expect("workspace"); + let lock = RepositoryLock::acquire(directory.path(), "first writer").expect("first lock"); + let owner = inspect_lock(directory.path()).expect("inspect owner"); + assert_eq!(owner.command, "first writer"); + let error = RepositoryLock::acquire(directory.path(), "second writer") + .expect_err("second writer must be refused"); + assert!(matches!(error, TransactionError::Locked { .. })); + drop(lock); + RepositoryLock::acquire(directory.path(), "after release").expect("released lock"); +} + +#[test] +fn explicit_break_returns_the_displaced_owner() { + let directory = tempfile::tempdir().expect("temporary repository"); + fs::create_dir(directory.path().join(".efo")).expect("workspace"); + let lock = RepositoryLock::acquire(directory.path(), "abandoned writer").expect("lock"); + std::mem::forget(lock); + + let owner = break_lock(directory.path()).expect("break lock"); + assert_eq!(owner.command, "abandoned writer"); + assert!(!directory.path().join(".efo/lock").exists()); +} + +#[test] +fn replacement_is_atomic_and_leaves_no_transaction_metadata() { + let directory = tempfile::tempdir().expect("temporary repository"); + fs::create_dir(directory.path().join(".efo")).expect("workspace"); + let destination = directory.path().join(".efo/worktree.json"); + fs::write(&destination, b"old").expect("old state"); + + replace_file(directory.path(), &destination, b"new", "edit worktree").expect("replace state"); + + assert_eq!(fs::read(destination).expect("new state"), b"new"); + assert!(!directory.path().join(".efo/transaction.json").exists()); + assert!(!directory.path().join(".efo/lock").exists()); + assert_eq!( + recover(directory.path()).expect("clean recovery"), + RecoveryOutcome::Clean + ); +}