//! 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, /// 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 { &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 { 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::().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 { 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 { 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, 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(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) }) }