//! 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, pub kind: EffectKind, pub source: EffectSource, } /// One destructive cache-cleanup intent, bound to approval. /// /// A cleaner is only ever run after its exact dry-run item list has been /// reviewed. `unavailable` distinguishes a missing tool from a tool that ran /// and reported nothing to remove, so an unavailable cleaner is never presented /// as a completed cleanup. #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] pub struct CleanupEffect { /// The cleaner (e.g. `eclean-dist`, `eclean-pkg`, `nix-store --gc`). pub cleaner: String, /// The exact items/paths the non-destructive dry run reported. pub items: Vec, /// The tool is not present in the target. pub unavailable: bool, } /// A non-Portage package source whose update is a single, reviewable /// transaction (Flatpak or Snap). Portage updates are represented as /// [`PackageEffect`]s from `emerge --pretend` instead. #[derive(Debug, Clone, Copy, PartialEq, Eq, Serialize, Deserialize)] #[serde(rename_all = "snake_case")] pub enum UpdateSource { Flatpak, Snap, } impl UpdateSource { pub fn as_str(self) -> &'static str { match self { UpdateSource::Flatpak => "flatpak", UpdateSource::Snap => "snap", } } } /// One exact, reviewable update transaction for a non-Portage lane. /// /// Execution consumes these transactions rather than re-discovering updates, /// so a changed revision, a newly appearing update, or a different installation /// cannot be smuggled in after review. `exact` records whether the backend can /// actually guarantee the reviewed identity and immutable revision; when it is /// false the source must be refused rather than executed approximately. #[derive(Debug, Clone, PartialEq, Eq, Serialize, Deserialize)] pub struct UpdateTransaction { pub source: UpdateSource, /// The immutable backend identity: a full Flatpak ref /// (`app/org.x/x86_64/stable`) or a snap name. pub identity: String, /// Human-readable version before the update, when the backend reports it. pub previous_version: Option, /// Human-readable version after the update. pub next_version: String, /// Immutable revision before the update (Flatpak commit / snap revision). pub previous_revision: Option, /// Immutable revision after the update. pub next_revision: Option, /// Installation scope (Flatpak `system`/`user`; Snap tracking channel). pub scope: Option, /// Material changes the update pulls in beyond the primary identity (for /// example an updated Flatpak runtime), or a confinement note. pub related: Vec, /// The backend can guarantee this exact identity and immutable revision. pub exact: bool, } /// A fully resolved, human-reviewable plan. #[derive(Debug, Clone, Default, PartialEq, Eq, Serialize, Deserialize)] #[serde(default)] pub struct ResolvedPlan { pub effects: Vec, /// Destructive cache-cleanup intents, each bound to its reviewed dry run. pub cleanup: Vec, /// Exact per-source update transactions (Flatpak/Snap), bound to approval /// and consumed by execution. Freshly discovered updates are never a /// substitute for these. pub updates: Vec, pub download_bytes: Option, /// A recovery point that will exist before the change (snapshot id). pub recovery_point: Option, /// Material consequences shown to the human before approval. pub consequences: Vec, /// 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"); } // Cleanup intents are part of the approved material change: a cleaner // that would now delete a different item set must invalidate approval. for cleanup in &self.cleanup { hasher.update(b"cleanup\0"); hasher.update(cleanup.cleaner.as_bytes()); hasher.update(b"\0"); hasher.update([cleanup.unavailable as u8]); hasher.update(b"\0"); for item in &cleanup.items { hasher.update(item.as_bytes()); hasher.update(b"\n"); } hasher.update(b"\0"); } // Exact update transactions (identity + immutable revision) are part of // the approved material change. for txn in &self.updates { hasher.update(b"update\0"); hasher.update(txn.source.as_str().as_bytes()); hasher.update(b"\0"); hasher.update(txn.identity.as_bytes()); hasher.update(b"\0"); hasher.update(txn.previous_version.as_deref().unwrap_or("").as_bytes()); hasher.update(b"\0"); hasher.update(txn.next_version.as_bytes()); hasher.update(b"\0"); hasher.update(txn.previous_revision.as_deref().unwrap_or("").as_bytes()); hasher.update(b"\0"); hasher.update(txn.next_revision.as_deref().unwrap_or("").as_bytes()); hasher.update(b"\0"); hasher.update(txn.scope.as_deref().unwrap_or("").as_bytes()); hasher.update(b"\0"); hasher.update([txn.exact as u8]); for related in &txn.related { hasher.update(related.as_bytes()); hasher.update(b"\n"); } hasher.update(b"\0"); } 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() )); for cleanup in &self.cleanup { if cleanup.unavailable { out.push_str(&format!( " [cleanup] {} is not available in the target\n", cleanup.cleaner )); } else { out.push_str(&format!( " [cleanup] {} would remove {} item(s)\n", cleanup.cleaner, cleanup.items.len() )); for item in &cleanup.items { out.push_str(&format!(" - {item}\n")); } } } for txn in &self.updates { let revisions = match (&txn.previous_revision, &txn.next_revision) { (Some(prev), Some(next)) => format!(" [{prev} -> {next}]"), (None, Some(next)) => format!(" [-> {next}]"), _ => String::new(), }; let scope = txn .scope .as_deref() .map(|s| format!(" ({s})")) .unwrap_or_default(); let exact_note = if txn.exact { "" } else { " — NOT EXACTLY BINDABLE" }; out.push_str(&format!( " [{}] {}{scope} {}{revisions} -> {}{exact_note}\n", txn.source.as_str(), txn.identity, txn.previous_version.as_deref().unwrap_or("?"), txn.next_version, )); for related in &txn.related { out.push_str(&format!(" ~ {related}\n")); } } 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 { 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`/`--depclean --pretend` do not use the // `[ebuild ...]` form; they list the packages slated for removal. Parse // them so a removal has a concrete, reviewable plan instead of being // refused as unestablished. Portage does not guarantee the order of this // list, so sort and dedupe it: otherwise two previews of the *same* // selection would produce different digests and falsely report drift. for line in text.lines() { if let Some(rest) = line.trim().strip_prefix("All selected packages:") { let mut atoms: Vec<&str> = rest.split_whitespace().collect(); atoms.sort_unstable(); atoms.dedup(); for atom in atoms { 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 } /// Whether a freshly resolved plan still matches what was approved, allowing /// for package changes that an *earlier approved step in the same plan* /// introduced (for example, a dependency a previous step just installed). /// /// Unrelated changes are never accepted: every residual difference between the /// reviewed and current effect list fails the check. Freshly resolved effects /// are therefore treated as evidence to compare against the approval, never as /// a replacement approval. pub fn approval_holds( approved: &ResolvedPlan, current: &ResolvedPlan, introduced_by_prior_steps: &[PackageEffect], ) -> bool { if !changed_materially(approved, current) { return true; } // Residual comparison: drop effects whose target was introduced by an // earlier, already-approved step, then compare everything else. let prior: std::collections::BTreeSet<&str> = introduced_by_prior_steps .iter() .map(|e| e.target.as_str()) .collect(); let mut a = approved.clone(); let mut b = current.clone(); a.effects.retain(|e| !prior.contains(e.target.as_str())); b.effects.retain(|e| !prior.contains(e.target.as_str())); // The download size and consequence text legitimately shift with the // package set; compare the effect identity, provenance and establishment. a.digest.clear(); b.digest.clear(); a.recovery_point = None; b.recovery_point = None; a.download_bytes = None; b.download_bytes = None; a.consequences.clear(); b.consequences.clear(); 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 approval_holds_allows_effects_explained_by_earlier_steps_only() { let approved = parse_emerge_pretend(PRETEND); // A later re-resolution that additionally reports a dependency an // earlier approved step installed is explained and allowed. let with_dep = parse_emerge_pretend(&format!( "{PRETEND}[ebuild N ] dev-libs/openssl-3.0.0\n" )); let dep = PackageEffect { target: "dev-libs/openssl-3.0.0".into(), previous: None, kind: EffectKind::New, source: EffectSource::Source, }; assert!(approval_holds(&approved, &with_dep, &[dep])); // The same unrelated change is NOT allowed when no earlier step // introduced it. assert!(!approval_holds(&approved, &with_dep, &[])); } #[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 depclean_selection_parsing_is_order_independent() { // Portage does not guarantee the order of `All selected packages`. let a = parse_emerge_pretend("All selected packages: app-misc/one-1.0 app-misc/two-2.0\n"); let b = parse_emerge_pretend("All selected packages: app-misc/two-2.0 app-misc/one-1.0\n"); assert_eq!(a.effects.len(), 2); assert_eq!(a.digest, b.digest); assert!(!changed_materially(&a, &b)); } #[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 cleanup_intents_are_part_of_the_digest_and_material_change() { let mut a = ResolvedPlan::default(); a.cleanup.push(CleanupEffect { cleaner: "eclean-dist".into(), items: vec!["app-misc/one".into()], unavailable: false, }); a.recompute_digest(); let mut b = a.clone(); b.cleanup[0].items = vec!["app-misc/two".into()]; b.recompute_digest(); assert_ne!(a.digest, b.digest); assert!(changed_materially(&a, &b)); assert!(!approval_holds(&a, &b, &[])); let mut unavailable = a.clone(); unavailable.cleanup[0].unavailable = true; unavailable.cleanup[0].items.clear(); unavailable.recompute_digest(); assert!(changed_materially(&a, &unavailable)); } #[test] fn update_transactions_are_part_of_the_digest_and_material_change() { let txn = UpdateTransaction { source: UpdateSource::Flatpak, identity: "app/org.mozilla.firefox/x86_64/stable".into(), previous_version: Some("128".into()), next_version: "129".into(), previous_revision: Some("OLD".into()), next_revision: Some("NEW".into()), scope: Some("system".into()), related: Vec::new(), exact: true, }; let mut a = ResolvedPlan::default(); a.updates.push(txn.clone()); a.recompute_digest(); // A different immutable revision with the *same* human version must be // a material change. let mut b = a.clone(); b.updates[0].next_revision = Some("OTHER".into()); b.recompute_digest(); assert_ne!(a.digest, b.digest); assert!(changed_materially(&a, &b)); assert!(!approval_holds(&a, &b, &[])); // A loss of exactness is also material. let mut c = a.clone(); c.updates[0].exact = false; c.recompute_digest(); assert!(changed_materially(&a, &c)); } #[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:")); } }