feat: add repository locks and recovery journal
This commit is contained in:
parent
b73030a4fb
commit
881fc7265a
|
|
@ -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
|
||||
|
|
|
|||
|
|
@ -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;
|
||||
|
|
|
|||
|
|
@ -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(¤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<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 }
|
||||
}
|
||||
|
|
@ -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
|
||||
);
|
||||
}
|
||||
Loading…
Reference in New Issue