phoebus_os/installer-rs/crates/phoebus-core/src/effects.rs
Phoebus dedaa4bc48 fix: defects found by the VM install journey
- chooser: keep the plain Portage install atom and record the version
  separately. emerge rejects a bare versioned atom (app-misc/hello-2.12.3), so
  resolve/split now produce app-misc/hello + version 2.12.3.
- effects: parse emerge --unmerge --pretend output (it does not use the
  [ebuild] form), so sys remove has a concrete plan instead of being refused as
  unestablished.
- action: reject unknown fields on internally tagged unit variants
  (deny_unknown_fields does not cover them), closing a fail-closed gap.
- transaction: fsync the log so a completed outcome survives power loss and is
  not later read as an interrupted operation.
- serial-driver: import re at module level (do_boot used it unqualified).
2026-09-23 21:40:42 -07:00

445 lines
16 KiB
Rust

//! Resolved package effects and plan binding.
//!
//! A generic "install X" preview is not enough: an update can pull in package
//! upgrades, downgrades, rebuilds and removals, choose signed binaries or source
//! builds, and consume real bandwidth and disk. These types parse Portage's
//! `--pretend` output into a concrete effect list, compute a digest, and let the
//! caller bind an approval to exactly the reviewed plan. Before execution the
//! plan is resolved again and a material change aborts.
use serde::{Deserialize, Serialize};
use sha2::{Digest, Sha256};
/// What a package entry will do.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EffectKind {
New,
Upgrade,
Downgrade,
Rebuild,
Remove,
/// A package that Portage will not change, or an unclassified line.
Other,
}
/// Where the package comes from. Provenance is explicit so Portage authority is
/// visible in the preview.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)]
#[serde(rename_all = "snake_case")]
pub enum EffectSource {
/// A signed binary package from a configured binhost.
Binary,
/// A source build.
Source,
/// No artifact (removal).
None,
}
/// One resolved package effect.
#[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)]
pub struct PackageEffect {
/// The full atom Portage reported (e.g. `dev-lang/python-3.12.6:3.12`).
pub target: String,
/// The previous version for an upgrade/downgrade, when reported.
pub previous: Option<String>,
pub kind: EffectKind,
pub source: EffectSource,
}
/// A fully resolved, human-reviewable plan.
#[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)]
#[serde(default)]
pub struct ResolvedPlan {
pub effects: Vec<PackageEffect>,
pub download_bytes: Option<u64>,
/// A recovery point that will exist before the change (snapshot id).
pub recovery_point: Option<String>,
/// Material consequences shown to the human before approval.
pub consequences: Vec<String>,
/// Stable digest of the effect list, used to bind approval to the review.
pub digest: String,
/// Whether the effect set was actually established from the package
/// manager. A genuinely empty plan (`0 packages`) is `true` with no
/// effects; output that could not be recognised is `false`, and callers
/// must refuse to proceed rather than treat it as "nothing to do".
#[serde(default)]
pub established: bool,
}
impl ResolvedPlan {
pub fn additions(&self) -> usize {
self.effects
.iter()
.filter(|e| e.kind == EffectKind::New)
.count()
}
pub fn upgrades(&self) -> usize {
self.effects
.iter()
.filter(|e| e.kind == EffectKind::Upgrade)
.count()
}
pub fn downgrades(&self) -> usize {
self.effects
.iter()
.filter(|e| e.kind == EffectKind::Downgrade)
.count()
}
pub fn removals(&self) -> usize {
self.effects
.iter()
.filter(|e| e.kind == EffectKind::Remove)
.count()
}
pub fn source_builds(&self) -> usize {
self.effects
.iter()
.filter(|e| e.source == EffectSource::Source)
.count()
}
pub fn binary_packages(&self) -> usize {
self.effects
.iter()
.filter(|e| e.source == EffectSource::Binary)
.count()
}
/// Recompute the digest from the effect list. Always called after parsing so
/// the digest cannot drift from the effects.
pub fn recompute_digest(&mut self) {
let mut hasher = Sha256::new();
for effect in &self.effects {
hasher.update(effect.target.as_bytes());
hasher.update(b"\0");
hasher.update(format!("{:?}", effect.kind).as_bytes());
hasher.update(b"\0");
hasher.update(format!("{:?}", effect.source).as_bytes());
hasher.update(b"\0");
if let Some(prev) = &effect.previous {
hasher.update(prev.as_bytes());
}
hasher.update(b"\n");
}
self.digest = format!("{:x}", hasher.finalize());
}
/// A concrete, human-readable effect preview.
pub fn render(&self) -> String {
let mut out = String::new();
out.push_str("Resolved effects:\n");
if self.effects.is_empty() {
out.push_str(" (no package changes)\n");
}
for effect in &self.effects {
let source = match effect.source {
EffectSource::Binary => "binary",
EffectSource::Source => "source",
EffectSource::None => "remove",
};
match &effect.previous {
Some(prev) if effect.kind != EffectKind::New => {
out.push_str(&format!(
" [{:?}] {} ({} -> {}), {source}\n",
effect.kind, effect.target, prev, effect.target
));
}
_ => out.push_str(&format!(
" [{:?}] {}, {source}\n",
effect.kind, effect.target
)),
}
}
out.push_str(&format!(
" totals: {} new, {} upgrade, {} downgrade, {} remove; \
{} source / {} binary\n",
self.additions(),
self.upgrades(),
self.downgrades(),
self.removals(),
self.source_builds(),
self.binary_packages()
));
if let Some(bytes) = self.download_bytes {
out.push_str(&format!(" download: {} MiB\n", bytes / (1024 * 1024)));
}
for consequence in &self.consequences {
out.push_str(&format!(" ! {consequence}\n"));
}
if let Some(point) = &self.recovery_point {
out.push_str(&format!(" recovery point: {point}\n"));
}
out.push_str(&format!(" plan digest: {}\n", self.digest));
out
}
}
/// Parse the totals line's `Size of downloads` value.
fn parse_download_bytes(text: &str) -> Option<u64> {
for line in text.lines() {
if let Some(idx) = line.find("Size of downloads:") {
let rest = line[idx + "Size of downloads:".len()..].trim();
// e.g. "10,000 KiB" or "1.5 MiB"
let mut number = String::new();
for c in rest.chars() {
if c.is_ascii_digit() || c == '.' {
number.push(c);
} else if c == ',' {
// Portage uses commas as thousands separators.
continue;
} else if !number.is_empty() {
break;
}
}
let value: f64 = number.parse().ok()?;
let unit = rest.to_ascii_lowercase();
let multiplier = if unit.contains("gib") {
1024.0 * 1024.0 * 1024.0
} else if unit.contains("mib") {
1024.0 * 1024.0
} else {
1024.0
};
return Some((value * multiplier) as u64);
}
}
None
}
fn kind_and_source(bracket: &str) -> (EffectKind, EffectSource) {
let lower = bracket.to_ascii_lowercase();
let source = if lower.contains("binary") {
EffectSource::Binary
} else if lower.contains("uninstall") || lower.contains("clean") {
EffectSource::None
} else {
EffectSource::Source
};
// The action letter follows the program name: `ebuild U`, `binary N`.
// It is case-sensitive: U is an upgrade, D a downgrade, R a rebuild.
let action = bracket.split_whitespace().nth(1).unwrap_or("");
let kind = if lower.contains("uninstall") {
EffectKind::Remove
} else if action.contains('D') {
EffectKind::Downgrade
} else if action.contains('U') {
EffectKind::Upgrade
} else if action.contains('N') {
EffectKind::New
} else if action.contains('R') {
EffectKind::Rebuild
} else {
EffectKind::Other
};
(kind, source)
}
/// Parse real `emerge --pretend` output into a resolved plan.
pub fn parse_emerge_pretend(text: &str) -> ResolvedPlan {
let mut plan = ResolvedPlan::default();
for line in text.lines() {
let trimmed = line.trim_start();
if !trimmed.starts_with('[') {
continue;
}
let Some(close) = trimmed.find(']') else {
continue;
};
let bracket = &trimmed[1..close];
let rest = trimmed[close + 1..].trim();
if rest.is_empty() {
continue;
}
let (kind, source) = kind_and_source(bracket);
// For an upgrade, the new atom is the first token. The old version, if
// present, is in a following `[...]`.
let target = rest
.split_whitespace()
.next()
.unwrap_or("")
.trim_end_matches(',')
.to_string();
if target.is_empty() {
continue;
}
let previous = rest
.find('[')
.and_then(|start| rest.find(']').map(|end| (start, end)))
.and_then(|(start, end)| {
let inner = rest[start + 1..end].trim();
inner.split_whitespace().next().map(|s| s.to_string())
})
.filter(|_| matches!(kind, EffectKind::Upgrade | EffectKind::Downgrade));
plan.effects.push(PackageEffect {
target,
previous,
kind,
source,
});
}
// `emerge --unmerge --pretend` does not use the `[ebuild ...]` form; it
// lists the packages slated for removal. Parse them so a removal has a
// concrete, reviewable plan instead of being refused as unestablished.
for line in text.lines() {
if let Some(rest) = line.trim().strip_prefix("All selected packages:") {
for atom in rest.split_whitespace() {
plan.effects.push(PackageEffect {
target: atom.to_string(),
previous: None,
kind: EffectKind::Remove,
source: EffectSource::None,
});
}
}
}
// Distinguish a real "0 packages" plan from output we could not parse. A
// Portage pretend run always prints a recognisable header or totals line.
plan.established = !plan.effects.is_empty()
|| text.contains("These are the packages that would be merged")
|| text.contains("Calculating dependencies")
|| text.contains("would be unmerged")
|| text.contains("All selected packages:")
|| text.lines().any(|l| l.trim_start().starts_with("Total:"));
plan.download_bytes = parse_download_bytes(text);
if plan.removals() > 0 {
plan.consequences
.push(format!("{} package(s) will be removed", plan.removals()));
}
if plan.source_builds() > 0 {
plan.consequences.push(format!(
"{} package(s) compile from source; this can take a long time",
plan.source_builds()
));
}
if plan.downgrades() > 0 {
plan.consequences.push(format!(
"{} package(s) will be downgraded",
plan.downgrades()
));
}
plan.recompute_digest();
plan
}
/// Whether two plans differ materially (anything but the digest itself).
pub fn changed_materially(approved: &ResolvedPlan, current: &ResolvedPlan) -> bool {
let mut a = approved.clone();
let mut b = current.clone();
a.digest.clear();
b.digest.clear();
a.recovery_point = None;
b.recovery_point = None;
a != b
}
#[cfg(test)]
mod tests {
use super::*;
const PRETEND: &str = "\
These are the packages that would be merged, in order:
Calculating dependencies... done!
[ebuild N ] app-editors/vim-9.1.0 USE=\"-python\"
[ebuild U ] dev-lang/python-3.12.6:3.12::gentoo [3.12.5:3.12::gentoo]
[binary N ] net-misc/wget-1.24.5
[ebuild UD ] app-misc/foo-2.0 [1.0]
[uninstall ] app-misc/old-1.0
Total: 5 packages (2 upgrades, 2 new, 1 uninstall), Size of downloads: 10,240 KiB
";
#[test]
fn parses_effects_kinds_and_sources() {
let plan = parse_emerge_pretend(PRETEND);
assert_eq!(plan.effects.len(), 5);
assert_eq!(plan.additions(), 2);
assert_eq!(plan.upgrades(), 1);
assert_eq!(plan.downgrades(), 1);
assert_eq!(plan.removals(), 1);
assert_eq!(plan.binary_packages(), 1);
assert_eq!(plan.source_builds(), 3);
assert_eq!(plan.download_bytes, Some(10_240 * 1024));
let python = plan
.effects
.iter()
.find(|e| e.target.starts_with("dev-lang/python"))
.unwrap();
assert_eq!(python.kind, EffectKind::Upgrade);
assert_eq!(python.previous.as_deref(), Some("3.12.5:3.12::gentoo"));
let foo = plan
.effects
.iter()
.find(|e| e.target.starts_with("app-misc/foo"))
.unwrap();
assert_eq!(foo.kind, EffectKind::Downgrade);
}
#[test]
fn digest_is_stable_and_detects_material_change() {
let a = parse_emerge_pretend(PRETEND);
let b = parse_emerge_pretend(PRETEND);
assert_eq!(a.digest, b.digest);
assert!(!changed_materially(&a, &b));
let other = PRETEND.replace("app-misc/foo-2.0", "app-misc/foo-2.1");
let c = parse_emerge_pretend(&other);
assert_ne!(a.digest, c.digest);
assert!(changed_materially(&a, &c));
}
#[test]
fn empty_output_is_a_no_change_plan() {
let plan = parse_emerge_pretend("Calculating dependencies... done!\n\nTotal: 0 packages\n");
assert!(plan.effects.is_empty());
assert!(plan.established, "a real 0-package plan is established");
assert_eq!(plan.additions(), 0);
assert!(plan.render().contains("no package changes"));
// The digest is still defined.
assert_eq!(plan.digest.len(), 64);
}
#[test]
fn parses_unmerge_pretend_output() {
let text = "\n>>> These are the packages that would be unmerged:\n\n \
app-misc/hello\n selected: 2.12.3\n\n\
All selected packages: app-misc/hello-2.12.3\n\n\
>>> 'Selected' packages are slated for removal.\n";
let plan = parse_emerge_pretend(text);
assert!(plan.established, "unmerge output is an established plan");
assert_eq!(plan.removals(), 1);
assert_eq!(plan.effects[0].target, "app-misc/hello-2.12.3");
assert_eq!(plan.effects[0].kind, EffectKind::Remove);
}
#[test]
fn unparseable_output_is_not_an_empty_plan() {
// A genuinely empty plan and output we cannot parse must be
// distinguishable: the latter has `established == false`.
let garbage = parse_emerge_pretend("something went sideways\nno totals here\n");
assert!(garbage.effects.is_empty());
assert!(
!garbage.established,
"unrecognised output must not masquerade as 0 packages"
);
let real = parse_emerge_pretend(PRETEND);
assert!(real.established);
assert!(!real.effects.is_empty());
}
#[test]
fn render_states_source_binary_and_consequences() {
let plan = parse_emerge_pretend(PRETEND);
let text = plan.render();
assert!(text.contains("binary"));
assert!(text.contains("source"));
assert!(text.contains("will be removed"));
assert!(text.contains("download:"));
}
}