phoebus_os/installer-rs/crates/phoebus-core/src/snapshot.rs
Phoebus 25f7381b4a
Some checks are pending
ci / test (push) Waiting to run
feat(desktop): add Mango + DankMaterialShell profile with rollback, assistant and release foundations
- Mango + DankMaterialShell desktop option (desktop.profile = "mango") through
  the GURU overlay with scoped ~amd64 keywords, a sealed session entry point and
  a dwl fallback session (ADR 0009).
- Coherent rollback/recovery: coordinated @ + @var snapshots, fstab and BLS
  root-subvolume rewriting, matching-kernel selection, snapshot recovery entry,
  retention/space gates and sys undo (ADR 0007).
- Installed assistant (sys ask) with an OS-level systemd sandbox boundary and
  fail-closed typed plans; resolved package effects bound to approval.
- Nix build isolation enforced (sandbox, no fallback) plus lifecycle/cleanup.
- Desktop helpers (menu/lock/idle), transaction log, release gates with atomic
  publish and signing helpers, and a Debian-Live appliance VM harness.
2026-09-21 03:46:52 -07:00

171 lines
5.6 KiB
Rust

//! Btrfs snapshot naming and transaction history.
//!
//! This is the real foundation for rollback: snapshots are named
//! deterministically, recorded in a machine-readable history, and only
//! committed once the operation that produced them succeeds. Rollback itself
//! is intentionally not claimed here; see the executor's snapshot module.
use std::path::Path;
use serde::{Deserialize, Serialize};
use crate::error::{CoreError, Result};
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum SnapshotStatus {
Created,
Committed,
RolledBack,
Failed,
}
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct SnapshotRecord {
pub id: String,
pub created_unix: u64,
pub operation: String,
pub source_subvol: String,
pub snapshot_subvol: String,
/// The paired `@var` snapshot. `/var` is a separate subvolume holding the
/// package database and Portage state, so it is captured with the root and
/// restored with it; otherwise a restored root would see inconsistent
/// package state.
#[serde(default)]
pub var_snapshot: Option<String>,
pub status: SnapshotStatus,
}
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct SnapshotHistory {
pub records: Vec<SnapshotRecord>,
}
impl SnapshotHistory {
/// Load the transaction history.
///
/// A missing or zero-length file is treated as empty. Any other read or
/// parse failure is returned, never silently discarded: hidden history
/// would let a caller believe no recovery point exists when one does.
pub fn load(path: &Path) -> Result<Self> {
if !path.exists() {
return Ok(Self::default());
}
let text = std::fs::read_to_string(path).map_err(|e| CoreError::io(path, e))?;
if text.trim().is_empty() {
return Ok(Self::default());
}
let history: SnapshotHistory = toml::from_str(&text)?;
Ok(history)
}
pub fn save(&self, path: &Path) -> Result<()> {
if let Some(parent) = path.parent() {
std::fs::create_dir_all(parent).map_err(|e| CoreError::io(parent, e))?;
}
std::fs::write(path, toml::to_string_pretty(self)?).map_err(|e| CoreError::io(path, e))?;
Ok(())
}
pub fn append(&mut self, record: SnapshotRecord) {
self.records.push(record);
}
pub fn latest(&self) -> Option<&SnapshotRecord> {
self.records.last()
}
}
/// A deterministic snapshot name: `<subvol>-<utc>-<operation>`.
pub fn snapshot_name(subvol: &str, unix_seconds: u64, operation: &str) -> String {
let slug: String = operation
.chars()
.map(|c| if c.is_ascii_alphanumeric() { c } else { '-' })
.collect();
let slug = slug.trim_matches('-').to_string();
format!("{subvol}-{}-{}", compact_utc(unix_seconds), slug)
}
/// `YYYYMMDDTHHMMSS` in UTC.
pub fn compact_utc(unix_seconds: u64) -> String {
let days = (unix_seconds / 86_400) as i64;
let rem = unix_seconds % 86_400;
let (y, m, d) = civil_from_days(days);
format!(
"{y:04}{m:02}{d:02}T{:02}{:02}{:02}",
rem / 3600,
(rem % 3600) / 60,
rem % 60
)
}
fn civil_from_days(z: i64) -> (i64, u32, u32) {
let z = z + 719_468;
let era = if z >= 0 { z } else { z - 146_096 } / 146_097;
let doe = z - era * 146_097;
let yoe = (doe - doe / 1460 + doe / 36_524 - doe / 146_096) / 365;
let y = yoe + era * 400;
let doy = doe - (365 * yoe + yoe / 4 - yoe / 100);
let mp = (5 * doy + 2) / 153;
let d = (doy - (153 * mp + 2) / 5 + 1) as u32;
let m = if mp < 10 { mp + 3 } else { mp - 9 } as u32;
(if m <= 2 { y + 1 } else { y }, m, d)
}
#[cfg(test)]
mod tests {
use super::*;
#[test]
fn names_are_deterministic_and_safe() {
let name = snapshot_name("@", 1_700_000_000, "sys update");
assert_eq!(name, "@-20231114T221320-sys-update");
assert!(!name.contains(' '));
assert!(!name.contains('/'));
}
#[test]
fn history_roundtrip() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("history.toml");
let mut history = SnapshotHistory::default();
history.append(SnapshotRecord {
id: "1".into(),
created_unix: 1_700_000_000,
operation: "sys update".into(),
source_subvol: "@".into(),
snapshot_subvol: "@-20231114T221320-sys-update".into(),
var_snapshot: None,
status: SnapshotStatus::Committed,
});
history.save(&path).unwrap();
let loaded = SnapshotHistory::load(&path).unwrap();
assert_eq!(loaded, history);
assert_eq!(loaded.latest().unwrap().status, SnapshotStatus::Committed);
}
#[test]
fn missing_history_is_empty() {
let dir = tempfile::tempdir().unwrap();
let history = SnapshotHistory::load(&dir.path().join("nope.toml")).unwrap();
assert!(history.records.is_empty());
}
#[test]
fn empty_history_file_is_empty() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("empty.toml");
std::fs::write(&path, " \n").unwrap();
let history = SnapshotHistory::load(&path).unwrap();
assert!(history.records.is_empty());
}
#[test]
fn corrupt_history_is_reported_not_hidden() {
let dir = tempfile::tempdir().unwrap();
let path = dir.path().join("corrupt.toml");
std::fs::write(&path, "this is not = = toml [[[").unwrap();
assert!(SnapshotHistory::load(&path).is_err());
}
}