Struct VerifiedTransaction 

pub struct VerifiedTransaction { /* private fields */ }

A prepared transaction whose declared integrity requirements have passed.

Implementations

impl VerifiedTransaction

pub fn validate( self, validator: &dyn CandidateValidator, ) -> Result<ValidatedTransaction>

Runs a consumer-supplied validator before exposing the commit operation.

Examples found in repository

examples/one_member.rs (line 44)

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 69)

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 48)

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 55)

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 67)

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(())
}

impl VerifiedTransaction

pub fn artifacts(&self) -> &ArtifactSet

Returns the validated artifact set.

pub fn product(&self) -> &ProductId

Returns the product identity.

pub fn release(&self) -> &ReleaseId

Returns the release identity.

pub fn stage_root(&self) -> &Path

Returns the private stage root for bounded candidate execution.

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

Returns a verified member’s private staged path.

Examples found in repository

examples/custom_validator.rs (line 24)

    fn validate(&self, transaction: &VerifiedTransaction) -> eggup_core::Result<()> {
        let path = transaction.staged_path(&self.member)?;
        let bytes = fs::read(&path).map_err(|e| {
            eggup_core::Error::CandidateExecution(format!("reading candidate: {e}"))
        })?;
        if bytes.windows(self.marker.len()).any(|w| w == self.marker) {
            Ok(())
        } else {
            Err(eggup_core::Error::CandidateExecution(
                "marker not found in candidate".into(),
            ))
        }
    }

pub fn integrity(&self, member: &MemberId) -> Option<&IntegrityResult>

Returns the integrity result for one member.

Trait Implementations

impl Debug for VerifiedTransaction

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

Formats the value using the given formatter.