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");

    // 4. A failed post-commit check can keep the coherent new generation,
    // while remaining machine-readable as a failed check.
    let (base, plan) = build(b"new", Some(b"old"))?;
    let receipt = plan
        .prepare()?
        .verify_integrity()?
        .validate(&AllValidators::new())?
        .commit_with_post_commit(
            CommitOwnership::new(&ExistingAsOwnedVerifier, AbsentPolicy::AllowCreate),
            PostCommitFailurePolicy::KeepInstalled,
            || Err("example health check failed"),
        )?;
    assert_eq!(receipt.disposition(), TransactionDisposition::Committed);
    assert!(receipt.post_commit_failure().is_some());
    println!(
        "kept installed after failed check: {:?}",
        receipt.disposition()
    );
    let _ = fs::remove_dir_all(base);
    Ok(())
}

pub fn prepare_with_bound_sources( self, bound: BoundSources, ) -> Result<PreparedTransaction>

Copies every member into private owned stage state, sourcing bound members from their already-open objects without any pathname lookup.

Each member identity present in bound is staged by reading the moved open object from byte zero; its recorded source path is treated as advisory diagnostics only and is never opened, even if it now names foreign state. Members absent from bound stage from their recorded source paths exactly as in prepare.

Every bound identity must name a member of this plan: leftover handles fail closed and no staged byte is ever obtained by reopening a member name as fallback. A failed bound stage copy never falls back to the recorded path.

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