Struct InstallPlan 

pub struct InstallPlan { /* private fields */ }

An explicit installation root and a coherent artifact set ready for private preparation.

Implementations

impl InstallPlan

pub fn new( product: ProductId, release: ReleaseId, installation_root: impl Into<PathBuf>, artifacts: ArtifactSet, ) -> Result<Self>

Validates an installation root, destination containment, sources, and member uniqueness.

Examples found in repository

examples/receipts.rs (lines 51-56)

fn build(
    new: &[u8],
    old: Option<&[u8]>,
) -> Result<(PathBuf, InstallPlan), Box<dyn std::error::Error>> {
    let base = temp_root("eggup-receipts");
    let inputs = base.join("inputs");
    let root = base.join("install");
    fs::create_dir_all(&inputs)?;
    fs::create_dir_all(root.join("bin"))?;
    fs::write(inputs.join("app"), new)?;
    if let Some(old) = old {
        fs::write(root.join("bin/app"), old)?;
    }
    let digest = eggup_core::hash_file(&inputs.join("app"))?;
    let member = ArtifactMember::new(MemberId::new("main")?, inputs.join("app"), "bin/app")?
        .with_integrity(IntegrityRequirement::Sha256(digest));
    let plan = InstallPlan::new(
        ProductId::new("demo")?,
        ReleaseId::new("5.0.0")?,
        &root,
        ArtifactSet::single(member)?,
    )?;
    // Leak the base via the plan's root; caller cleans `root.parent()`.
    Ok((base, plan))
}

examples/one_member.rs (lines 35-40)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = temp_root("eggup-one-member");
    let inputs = base.join("inputs");
    let root = base.join("install");
    fs::create_dir_all(inputs.join("bin"))?;
    fs::create_dir_all(root.join("bin"))?;
    fs::write(inputs.join("app"), b"new-app")?;
    let digest = eggup_core::hash_file(&inputs.join("app"))?;
    let member = ArtifactMember::new(MemberId::new("main")?, inputs.join("app"), "bin/app")?
        .with_integrity(IntegrityRequirement::Sha256(digest));
    let plan = InstallPlan::new(
        ProductId::new("demo")?,
        ReleaseId::new("1.0.0")?,
        &root,
        ArtifactSet::single(member)?,
    )?;
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&AllValidators::new())?
        .commit(CommitOwnership::new(
            &ExistingAsOwnedVerifier,
            AbsentPolicy::AllowCreate,
        ))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    assert_eq!(fs::read(root.join("bin/app"))?, b"new-app");
    let _ = fs::remove_dir_all(&base);
    println!("one-member commit: {:?}", receipt.disposition());
    Ok(())
}

examples/custom_validator.rs (lines 56-61)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = temp_root("eggup-custom-validator");
    let inputs = base.join("inputs");
    let root = base.join("install");
    fs::create_dir_all(&inputs)?;
    fs::create_dir_all(root.join("bin"))?;
    fs::write(inputs.join("app"), b"release-marker-42")?;
    let digest = eggup_core::hash_file(&inputs.join("app"))?;
    let member = ArtifactMember::new(MemberId::new("main")?, inputs.join("app"), "bin/app")?
        .with_integrity(IntegrityRequirement::Sha256(digest));
    let plan = InstallPlan::new(
        ProductId::new("demo")?,
        ReleaseId::new("3.0.0")?,
        &root,
        ArtifactSet::single(member)?,
    )?;
    let validator = ContainsMarker {
        member: MemberId::new("main")?,
        marker: b"marker-42".to_vec(),
    };
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&validator)?
        .commit(CommitOwnership::new(
            &ExistingAsOwnedVerifier,
            AbsentPolicy::AllowCreate,
        ))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    let _ = fs::remove_dir_all(&base);
    println!("custom validator commit: {:?}", receipt.disposition());
    Ok(())
}

examples/ownership.rs (lines 36-41)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = temp_root("eggup-ownership");
    let inputs = base.join("inputs");
    let root = base.join("install");
    fs::create_dir_all(&inputs)?;
    fs::create_dir_all(root.join("bin"))?;
    fs::write(inputs.join("app"), b"new-app")?;
    fs::write(root.join("bin/app"), b"old-app")?;
    let new_digest = eggup_core::hash_file(&inputs.join("app"))?;
    let old_digest = eggup_core::hash_file(&root.join("bin/app"))?;
    let member = ArtifactMember::new(MemberId::new("main")?, inputs.join("app"), "bin/app")?
        .with_integrity(IntegrityRequirement::Sha256(new_digest));
    let plan = InstallPlan::new(
        ProductId::new("demo")?,
        ReleaseId::new("4.0.0")?,
        &root,
        ArtifactSet::single(member)?,
    )?;
    // Prove the live file is the expected old deployment; deny creation of
    // absent destinations (replacement-only policy).
    let verifier = ExactDigestVerifier::new(vec![(MemberId::new("main")?, old_digest)]);
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&AllValidators::new())?
        .commit(CommitOwnership::new(&verifier, AbsentPolicy::DenyCreate))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    assert_eq!(fs::read(root.join("bin/app"))?, b"new-app");
    let _ = fs::remove_dir_all(&base);
    println!("ownership-verified commit: {:?}", receipt.disposition());
    Ok(())
}

examples/multi_member.rs (lines 46-51)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = temp_root("eggup-multi-member");
    let inputs = base.join("inputs");
    let root = base.join("install");
    fs::create_dir_all(&inputs)?;
    fs::create_dir_all(root.join("bin"))?;
    fs::write(inputs.join("main"), b"new-main")?;
    fs::write(inputs.join("helper"), b"new-helper")?;
    fs::write(root.join("bin/main"), b"old-main")?;
    fs::write(root.join("bin/helper"), b"old-helper")?;
    let main_digest = eggup_core::hash_file(&inputs.join("main"))?;
    let helper_digest = eggup_core::hash_file(&inputs.join("helper"))?;
    let members = ArtifactSet::new(vec![
        ArtifactMember::new(MemberId::new("main")?, inputs.join("main"), "bin/main")?
            .with_integrity(IntegrityRequirement::Sha256(main_digest)),
        ArtifactMember::new(
            MemberId::new("helper")?,
            inputs.join("helper"),
            "bin/helper",
        )?
        .with_integrity(IntegrityRequirement::Sha256(helper_digest)),
    ])?;
    let plan = InstallPlan::new(
        ProductId::new("bundle")?,
        ReleaseId::new("2.0.0")?,
        &root,
        members,
    )?;
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&AllValidators::new())?
        .commit(CommitOwnership::new(
            &ExistingAsOwnedVerifier,
            AbsentPolicy::AllowCreate,
        ))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    assert_eq!(fs::read(root.join("bin/main"))?, b"new-main");
    assert_eq!(fs::read(root.join("bin/helper"))?, b"new-helper");
    let _ = fs::remove_dir_all(&base);
    println!("multi-member commit: {:?}", receipt.disposition());
    Ok(())
}

pub fn product(&self) -> &ProductId

Returns the consumer-owned product identity.

pub fn release(&self) -> &ReleaseId

Returns the consumer-owned release identity.

pub fn installation_root(&self) -> &Path

Returns the exact installation root used for destination resolution.

pub fn artifacts(&self) -> &ArtifactSet

Returns the validated artifact set.

pub fn destination(&self, member: &MemberId) -> Result<PathBuf>

Resolves a member destination beneath the exact installation root.

pub fn prepare(self) -> Result<PreparedTransaction>

Copies every member into private owned stage state without mutating a destination.

Examples found in repository

examples/one_member.rs (line 42)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = temp_root("eggup-one-member");
    let inputs = base.join("inputs");
    let root = base.join("install");
    fs::create_dir_all(inputs.join("bin"))?;
    fs::create_dir_all(root.join("bin"))?;
    fs::write(inputs.join("app"), b"new-app")?;
    let digest = eggup_core::hash_file(&inputs.join("app"))?;
    let member = ArtifactMember::new(MemberId::new("main")?, inputs.join("app"), "bin/app")?
        .with_integrity(IntegrityRequirement::Sha256(digest));
    let plan = InstallPlan::new(
        ProductId::new("demo")?,
        ReleaseId::new("1.0.0")?,
        &root,
        ArtifactSet::single(member)?,
    )?;
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&AllValidators::new())?
        .commit(CommitOwnership::new(
            &ExistingAsOwnedVerifier,
            AbsentPolicy::AllowCreate,
        ))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    assert_eq!(fs::read(root.join("bin/app"))?, b"new-app");
    let _ = fs::remove_dir_all(&base);
    println!("one-member commit: {:?}", receipt.disposition());
    Ok(())
}

examples/custom_validator.rs (line 67)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = temp_root("eggup-custom-validator");
    let inputs = base.join("inputs");
    let root = base.join("install");
    fs::create_dir_all(&inputs)?;
    fs::create_dir_all(root.join("bin"))?;
    fs::write(inputs.join("app"), b"release-marker-42")?;
    let digest = eggup_core::hash_file(&inputs.join("app"))?;
    let member = ArtifactMember::new(MemberId::new("main")?, inputs.join("app"), "bin/app")?
        .with_integrity(IntegrityRequirement::Sha256(digest));
    let plan = InstallPlan::new(
        ProductId::new("demo")?,
        ReleaseId::new("3.0.0")?,
        &root,
        ArtifactSet::single(member)?,
    )?;
    let validator = ContainsMarker {
        member: MemberId::new("main")?,
        marker: b"marker-42".to_vec(),
    };
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&validator)?
        .commit(CommitOwnership::new(
            &ExistingAsOwnedVerifier,
            AbsentPolicy::AllowCreate,
        ))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    let _ = fs::remove_dir_all(&base);
    println!("custom validator commit: {:?}", receipt.disposition());
    Ok(())
}

examples/ownership.rs (line 46)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = temp_root("eggup-ownership");
    let inputs = base.join("inputs");
    let root = base.join("install");
    fs::create_dir_all(&inputs)?;
    fs::create_dir_all(root.join("bin"))?;
    fs::write(inputs.join("app"), b"new-app")?;
    fs::write(root.join("bin/app"), b"old-app")?;
    let new_digest = eggup_core::hash_file(&inputs.join("app"))?;
    let old_digest = eggup_core::hash_file(&root.join("bin/app"))?;
    let member = ArtifactMember::new(MemberId::new("main")?, inputs.join("app"), "bin/app")?
        .with_integrity(IntegrityRequirement::Sha256(new_digest));
    let plan = InstallPlan::new(
        ProductId::new("demo")?,
        ReleaseId::new("4.0.0")?,
        &root,
        ArtifactSet::single(member)?,
    )?;
    // Prove the live file is the expected old deployment; deny creation of
    // absent destinations (replacement-only policy).
    let verifier = ExactDigestVerifier::new(vec![(MemberId::new("main")?, old_digest)]);
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&AllValidators::new())?
        .commit(CommitOwnership::new(&verifier, AbsentPolicy::DenyCreate))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    assert_eq!(fs::read(root.join("bin/app"))?, b"new-app");
    let _ = fs::remove_dir_all(&base);
    println!("ownership-verified commit: {:?}", receipt.disposition());
    Ok(())
}

examples/multi_member.rs (line 53)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    let base = temp_root("eggup-multi-member");
    let inputs = base.join("inputs");
    let root = base.join("install");
    fs::create_dir_all(&inputs)?;
    fs::create_dir_all(root.join("bin"))?;
    fs::write(inputs.join("main"), b"new-main")?;
    fs::write(inputs.join("helper"), b"new-helper")?;
    fs::write(root.join("bin/main"), b"old-main")?;
    fs::write(root.join("bin/helper"), b"old-helper")?;
    let main_digest = eggup_core::hash_file(&inputs.join("main"))?;
    let helper_digest = eggup_core::hash_file(&inputs.join("helper"))?;
    let members = ArtifactSet::new(vec![
        ArtifactMember::new(MemberId::new("main")?, inputs.join("main"), "bin/main")?
            .with_integrity(IntegrityRequirement::Sha256(main_digest)),
        ArtifactMember::new(
            MemberId::new("helper")?,
            inputs.join("helper"),
            "bin/helper",
        )?
        .with_integrity(IntegrityRequirement::Sha256(helper_digest)),
    ])?;
    let plan = InstallPlan::new(
        ProductId::new("bundle")?,
        ReleaseId::new("2.0.0")?,
        &root,
        members,
    )?;
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&AllValidators::new())?
        .commit(CommitOwnership::new(
            &ExistingAsOwnedVerifier,
            AbsentPolicy::AllowCreate,
        ))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    assert_eq!(fs::read(root.join("bin/main"))?, b"new-main");
    assert_eq!(fs::read(root.join("bin/helper"))?, b"new-helper");
    let _ = fs::remove_dir_all(&base);
    println!("multi-member commit: {:?}", receipt.disposition());
    Ok(())
}

examples/receipts.rs (line 65)

fn main() -> Result<(), Box<dyn std::error::Error>> {
    // 1. Committed: success.
    let (base, plan) = build(b"new", Some(b"old"))?;
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&AllValidators::new())?
        .commit(CommitOwnership::new(
            &ExistingAsOwnedVerifier,
            AbsentPolicy::AllowCreate,
        ))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    assert!(receipt.failure().is_none());
    println!("committed: {:?}", receipt.disposition());
    let _ = fs::remove_dir_all(&base);

    // 2. RolledBack: ownership denied, live state unchanged, failure explains why.
    let (base, plan) = build(b"new", Some(b"old"))?;
    let root = base.join("install");
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&AllValidators::new())?
        .commit(CommitOwnership::new(&DenyAll, AbsentPolicy::AllowCreate))?;
    assert_eq!(receipt.disposition(), TransactionDisposition::RolledBack);
    assert!(receipt.rollback_verified());
    let failure = receipt.failure().expect("rolled back carries a cause");
    println!(
        "rolled back: phase={} category={} detail={}",
        failure.phase().as_str(),
        failure.category().as_str(),
        failure.detail()
    );
    assert_eq!(fs::read(root.join("bin/app"))?, b"old");
    assert_ne!(
        receipt.disposition(),
        TransactionDisposition::Committed,
        "rollback is not success"
    );
    let _ = fs::remove_dir_all(&base);

    // 3. RecoveryRequired is distinct and high severity: it means Eggup cannot
    // prove either generation is coherent. It is produced by rollback failure
    // or unclean finalization; operators must inspect `recovery_path` and the
    // preserved lock. See `docs/transaction.md` for the full contract.
    println!("recovery-required: inspect recovery_path + lock; do not retry blindly");
    Ok(())
}

Trait Implementations

impl Clone for InstallPlan

fn clone(&self) -> Self

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for InstallPlan

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Eq for InstallPlan

impl PartialEq for InstallPlan

fn eq(&self, other: &Self) -> bool

Equality operator ==.

fn ne(&self, other: &Rhs) -> bool

Inequality operator !=.

impl StructuralPartialEq for InstallPlan