feat: add repository locks and recovery journal

This commit is contained in:
Dandaedre 2026-09-21 00:19:46 +02:00
parent b73030a4fb
commit 881fc7265a
Signed by: Dandaedre
GPG Key ID: 440C6592E8A26D99
4 changed files with 329 additions and 2 deletions

View File

@ -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

View File

@ -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;

273
lib_efo/src/transaction.rs Normal file
View File

@ -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<String>) -> Result<Self, TransactionError> {
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<LockInfo, TransactionError> {
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<LockInfo, TransactionError> {
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<RecoveryOutcome, TransactionError> {
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<RecoveryOutcome, TransactionError> {
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(&current) != 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<T: Serialize>(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<u64, TransactionError> {
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 }
}

View File

@ -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
);
}