epoch_forge/lib_efo/src/migration.rs

372 lines
12 KiB
Rust

//! Planning and execution for explicit repository-format migrations.
use std::{
collections::{BTreeMap, BTreeSet},
fs::{self, File},
io::Write,
path::{Path, PathBuf},
time::{SystemTime, UNIX_EPOCH},
};
use serde::Serialize;
use uuid::Uuid;
use crate::{
epoch::{EpochId, EpochInfo},
repository_format::{
DetectedManifest, LegacyManifest, RepositoryManifest, RepositorySnapshot, detect_manifest,
},
stats::EntityType,
};
/// A validated, read-only description of a version-1 migration.
#[derive(Debug, Clone)]
pub struct MigrationPlan {
/// Canonical repository root.
root: PathBuf,
/// Fully decoded legacy manifest.
legacy: LegacyManifest,
/// Sorted legacy epoch identifiers.
epoch_ids: Vec<EpochId>,
/// Selected snapshot used to seed both transient layers.
current: EpochInfo,
/// Monotonic allocator value derived from all observed history.
next_epoch_id: EpochId,
}
impl MigrationPlan {
/// Repository root that will be migrated.
pub fn root(&self) -> &Path {
&self.root
}
/// Currently selected legacy epoch.
pub fn current_epoch(&self) -> EpochId {
self.legacy.epoch_id
}
/// Number of immutable snapshots validated by the plan.
pub fn epoch_count(&self) -> usize {
self.epoch_ids.len()
}
/// First epoch ID that a version-2 commit may allocate.
pub fn next_epoch_id(&self) -> EpochId {
self.next_epoch_id
}
/// Tags that will be retained unchanged.
pub fn tags(&self) -> &BTreeMap<String, EpochId> {
&self.legacy.tags
}
}
/// Result of a completed migration.
#[derive(Debug, Clone)]
pub struct MigrationOutcome {
/// Directory containing the byte-for-byte legacy manifest backup.
pub backup_directory: PathBuf,
/// Stable identity assigned to the migrated repository.
pub repository_id: Uuid,
}
/// A migration planning or execution failure.
#[derive(Debug, thiserror::Error)]
pub enum MigrationError {
/// A filesystem operation failed.
#[error("migration could not access `{path}`: {source}")]
Io {
/// Affected path.
path: PathBuf,
/// Underlying filesystem error.
#[source]
source: std::io::Error,
},
/// The manifest is malformed or uses an unsupported format.
#[error("cannot migrate repository manifest: {0}")]
Format(#[from] crate::repository_format::FormatError),
/// This repository is already on the requested format.
#[error("repository already uses format version 2; nothing was changed")]
AlreadyCurrent,
/// Legacy repository invariants do not hold.
#[error("legacy repository is inconsistent: {0}")]
Invalid(String),
/// Existing migration state may not be overwritten.
#[error("migration workspace `{0}` already exists; nothing was changed")]
WorkspaceExists(PathBuf),
/// JSON data could not be decoded or encoded.
#[error("migration data at `{path}` is invalid: {source}")]
Json {
/// Affected path.
path: PathBuf,
/// Serialization error.
#[source]
source: serde_json::Error,
},
}
/// Validate a version-1 repository without changing any bytes.
pub fn plan_migration(root: &Path) -> Result<MigrationPlan, MigrationError> {
let root = root.canonicalize().map_err(|source| MigrationError::Io {
path: root.to_path_buf(),
source,
})?;
let manifest_path = root.join(".epoch");
let manifest_bytes = read(&manifest_path)?;
let legacy = match detect_manifest(&manifest_bytes)? {
DetectedManifest::Legacy(manifest) => manifest,
DetectedManifest::Current(_) => return Err(MigrationError::AlreadyCurrent),
};
let epoch_root = root.join("epoch");
let entries = fs::read_dir(&epoch_root).map_err(|source| MigrationError::Io {
path: epoch_root.clone(),
source,
})?;
let mut epoch_ids = Vec::new();
let mut snapshots = BTreeMap::new();
for entry in entries {
let entry = entry.map_err(|source| MigrationError::Io {
path: epoch_root.clone(),
source,
})?;
if !entry
.file_type()
.map_err(|source| MigrationError::Io {
path: entry.path(),
source,
})?
.is_dir()
{
continue;
}
let name = entry.file_name().to_string_lossy().into_owned();
let numeric = name.parse::<u64>().map_err(|_| {
MigrationError::Invalid(format!("epoch directory `{name}` is not numeric"))
})?;
let id = EpochId::new(numeric);
let snapshot_path = entry.path().join("epochinfo.json");
let snapshot: EpochInfo =
serde_json::from_slice(&read(&snapshot_path)?).map_err(|source| {
MigrationError::Json {
path: snapshot_path.clone(),
source,
}
})?;
if snapshot.epoch_id != id {
return Err(MigrationError::Invalid(format!(
"epoch directory {id} contains snapshot {}",
snapshot.epoch_id
)));
}
validate_entities(id, &snapshot)?;
for tag in snapshot.tags.iter() {
if legacy.tags.get(tag) != Some(&id) {
return Err(MigrationError::Invalid(format!(
"tag `{tag}` in epoch {id} is inconsistent with .epoch"
)));
}
}
epoch_ids.push(id);
snapshots.insert(id, snapshot);
}
epoch_ids.sort_unstable();
if epoch_ids.is_empty() {
return Err(MigrationError::Invalid(
"no epoch snapshots were found".to_owned(),
));
}
let current = snapshots.get(&legacy.epoch_id).cloned().ok_or_else(|| {
MigrationError::Invalid(format!("selected epoch {} is missing", legacy.epoch_id))
})?;
for (tag, id) in &legacy.tags {
if !snapshots.contains_key(id) {
return Err(MigrationError::Invalid(format!(
"tag `{tag}` points to missing epoch {id}"
)));
}
}
let maximum = epoch_ids
.last()
.map(|id| id.id)
.ok_or_else(|| MigrationError::Invalid("no epoch snapshots were found".to_owned()))?;
let next = maximum
.checked_add(1)
.ok_or_else(|| MigrationError::Invalid("epoch ID allocator is exhausted".to_owned()))?;
Ok(MigrationPlan {
root,
legacy,
epoch_ids,
current,
next_epoch_id: EpochId::new(next),
})
}
/// Execute a previously validated migration, committing `.epoch` last.
pub fn execute_migration(plan: &MigrationPlan) -> Result<MigrationOutcome, MigrationError> {
let workspace = plan.root.join(".efo");
if workspace.exists() {
return Err(MigrationError::WorkspaceExists(workspace));
}
let repository_id = Uuid::new_v4();
let stamp = SystemTime::now()
.duration_since(UNIX_EPOCH)
.map_err(|_| MigrationError::Invalid("system clock is before Unix epoch".to_owned()))?
.as_secs();
let temporary = plan.root.join(format!(".efo-migration-{}", Uuid::new_v4()));
let backup_relative = PathBuf::from(format!("migrations/v1-{stamp}"));
let backup = temporary.join(&backup_relative);
fs::create_dir_all(&backup).map_err(|source| MigrationError::Io {
path: backup.clone(),
source,
})?;
let result = prepare_workspace(plan, repository_id, &temporary, &backup).and_then(|manifest| {
fs::rename(&temporary, &workspace).map_err(|source| MigrationError::Io {
path: workspace.clone(),
source,
})?;
atomic_json(&plan.root.join(".epoch"), &manifest)
});
if result.is_err() && temporary.exists() {
let _ = fs::remove_dir_all(&temporary);
}
result?;
Ok(MigrationOutcome {
backup_directory: workspace.join(backup_relative),
repository_id,
})
}
/// Write and flush the complete version-2 workspace before its final rename.
fn prepare_workspace(
plan: &MigrationPlan,
repository_id: Uuid,
temporary: &Path,
backup: &Path,
) -> Result<RepositoryManifest, MigrationError> {
let legacy_path = plan.root.join(".epoch");
let legacy_bytes = read(&legacy_path)?;
write_synced(&backup.join(".epoch"), &legacy_bytes)?;
let checksum = format!("{:016x} .epoch\n", fnv1a64(&legacy_bytes));
write_synced(&backup.join("checksums.fnv1a64"), checksum.as_bytes())?;
let snapshot =
RepositorySnapshot::new(repository_id, plan.legacy.epoch_id, plan.current.clone());
atomic_json(&temporary.join("index.json"), &snapshot)?;
atomic_json(&temporary.join("worktree.json"), &snapshot)?;
sync_directory(backup)?;
sync_directory(temporary)?;
Ok(RepositoryManifest::new(
repository_id,
plan.legacy.epoch_id,
plan.next_epoch_id,
env!("EFO_SHORT_VERSION").to_owned(),
plan.legacy.tags.clone(),
))
}
/// Check identity and collection invariants that migration must preserve.
fn validate_entities(epoch: EpochId, snapshot: &EpochInfo) -> Result<(), MigrationError> {
let mut ids = BTreeSet::new();
for (entities, expected) in [
(&snapshot.characters, EntityType::Character),
(&snapshot.towns, EntityType::Town),
(&snapshot.events, EntityType::Event),
(&snapshot.calamities, EntityType::Calamity),
(&snapshot.organizations, EntityType::Organization),
(&snapshot.blockers, EntityType::Blocker),
] {
for entity in entities {
if entity.id.is_nil() || !ids.insert(entity.id) {
return Err(MigrationError::Invalid(format!(
"epoch {epoch} has a missing or duplicate entity UUID"
)));
}
if entity.entity_type != expected {
return Err(MigrationError::Invalid(format!(
"entity `{}` in epoch {epoch} is stored as {:?}, expected {:?}",
entity.name, entity.entity_type, expected
)));
}
}
}
Ok(())
}
/// Read bytes while retaining the affected path in diagnostics.
fn read(path: &Path) -> Result<Vec<u8>, MigrationError> {
fs::read(path).map_err(|source| MigrationError::Io {
path: path.to_path_buf(),
source,
})
}
/// Serialize, flush, and atomically replace one JSON file.
fn atomic_json<T: Serialize>(path: &Path, value: &T) -> Result<(), MigrationError> {
let bytes = serde_json::to_vec_pretty(value).map_err(|source| MigrationError::Json {
path: path.to_path_buf(),
source,
})?;
let parent = path.parent().ok_or_else(|| {
MigrationError::Invalid(format!("path `{}` has no parent", path.display()))
})?;
fs::create_dir_all(parent).map_err(|source| MigrationError::Io {
path: parent.to_path_buf(),
source,
})?;
let mut temporary =
tempfile::NamedTempFile::new_in(parent).map_err(|source| MigrationError::Io {
path: parent.to_path_buf(),
source,
})?;
temporary
.write_all(&bytes)
.and_then(|_| temporary.as_file().sync_all())
.map_err(|source| MigrationError::Io {
path: path.to_path_buf(),
source,
})?;
temporary
.persist(path)
.map_err(|error| MigrationError::Io {
path: path.to_path_buf(),
source: error.error,
})?;
sync_directory(parent)
}
/// Create one backup file and flush its contents.
fn write_synced(path: &Path, bytes: &[u8]) -> Result<(), MigrationError> {
let mut file = File::create(path).map_err(|source| MigrationError::Io {
path: path.to_path_buf(),
source,
})?;
file.write_all(bytes)
.and_then(|_| file.sync_all())
.map_err(|source| MigrationError::Io {
path: path.to_path_buf(),
source,
})
}
/// Flush directory metadata after creating or renaming entries.
fn sync_directory(path: &Path) -> Result<(), MigrationError> {
File::open(path)
.and_then(|directory| directory.sync_all())
.map_err(|source| MigrationError::Io {
path: path.to_path_buf(),
source,
})
}
/// Compute the documented checksum used to verify migration backup bytes.
fn fnv1a64(bytes: &[u8]) -> u64 {
bytes.iter().fold(0xcbf2_9ce4_8422_2325, |hash, byte| {
(hash ^ u64::from(*byte)).wrapping_mul(0x0000_0100_0000_01b3)
})
}