Enum ArtifactCacheOutcome

Source

pub enum ArtifactCacheOutcome {
    Built(ArtifactCacheRecord),
    Reused(ArtifactCacheRecord),
}

Expand description

Whether an artifact transaction published or reused its exact output set.

Variants§

§

Built(ArtifactCacheRecord)

The caller populated staging and the complete result was published.

§

Reused(ArtifactCacheRecord)

A complete existing entry was verified and materialized.

Implementations§

Source §

impl ArtifactCacheOutcome

Source

pub const fn record(&self) -> &ArtifactCacheRecord

Read the common acquisition record.

Examples found in repository ?

examples/transactional_artifact_cache.rs (line 88)

15fn main() -> Result<(), Box<dyn std::error::Error>> {
16    let arguments = std::env::args_os().skip(1).collect::<Vec<_>>();
17    let [tool, sha256, version, input, output, cache_root] = arguments.as_slice() else {
18        eprintln!(
19            "usage: transactional_artifact_cache <tool-path> <sha256> <exact-version-stdout> <input> <public-output> <cache-root>"
20        );
21        return Ok(());
22    };
23    let current_dir = std::env::current_dir()?;
24    let tool = resolve_executable(&current_dir.join(tool), &current_dir, &[])?;
25    let context = ExecutionContext {
26        current_dir: &current_dir,
27        environment: &[],
28    };
29    let limits = OutputLimits {
30        stdout: OutputLimit::Terminate(64 * 1024),
31        stderr: OutputLimit::Terminate(64 * 1024),
32        timeout: Some(Duration::from_secs(60)),
33    };
34    // Admission uses caller authority, never a digest computed from untrusted
35    // selected bytes. Transform tools must work with this empty environment.
36    let admitted = AdmittedTool::admit(
37        &ToolSpec {
38            executable: &tool,
39            sha256: sha256
40                .to_str()
41                .ok_or("SHA-256 must be UTF-8")?
42                .parse::<Sha256Digest>()?,
43            executable_bytes: 256 * 1024 * 1024,
44            version_arguments: &["--version".into()],
45            version_identity: version.to_str().ok_or("version must be UTF-8")?,
46        },
47        &context,
48        limits,
49    )?;
50    let input = current_dir.join(input);
51    let output = current_dir.join(output);
52    let cache_root = current_dir.join(cache_root);
53    let spec = ArtifactCacheSpec::new(
54        &cache_root,
55        "example-transform",
56        "example/admitted-transform/v1",
57    )
58    .with_input("source", &input)
59    .with_tool("transformer", &tool)
60    .with_arguments(["<input>", "<output>"])
61    .with_output("result", &output)
62    .with_prune_policy(
63        ArtifactCachePrunePolicy::new()
64            .with_max_age(Duration::from_secs(7 * 24 * 60 * 60))
65            .with_max_size_bytes(2 * 1024 * 1024 * 1024),
66    );
67
68    let outcome = match prepare_artifact_cache(&spec)? {
69        ArtifactCachePreparation::Reused(record) => ArtifactCacheOutcome::Reused(record),
70        ArtifactCachePreparation::Build(transaction) => {
71            let staged_output = transaction.output_path("result")?;
72            admitted
73                .run(
74                    &[input.into_os_string(), staged_output.into_os_string()],
75                    &context,
76                    limits,
77                )?
78                .require_success()?;
79            transaction.commit()?
80        }
81    };
82
83    let disposition = if outcome.is_reused() {
84        "reused"
85    } else {
86        "built"
87    };
88    println!("{disposition} artifact set {}", outcome.record().key());
89    Ok(())
90}

Source

pub const fn is_reused(&self) -> bool

Report whether a complete matching artifact set was reused.

Examples found in repository ?

examples/transactional_artifact_cache.rs (line 83)

15fn main() -> Result<(), Box<dyn std::error::Error>> {
16    let arguments = std::env::args_os().skip(1).collect::<Vec<_>>();
17    let [tool, sha256, version, input, output, cache_root] = arguments.as_slice() else {
18        eprintln!(
19            "usage: transactional_artifact_cache <tool-path> <sha256> <exact-version-stdout> <input> <public-output> <cache-root>"
20        );
21        return Ok(());
22    };
23    let current_dir = std::env::current_dir()?;
24    let tool = resolve_executable(&current_dir.join(tool), &current_dir, &[])?;
25    let context = ExecutionContext {
26        current_dir: &current_dir,
27        environment: &[],
28    };
29    let limits = OutputLimits {
30        stdout: OutputLimit::Terminate(64 * 1024),
31        stderr: OutputLimit::Terminate(64 * 1024),
32        timeout: Some(Duration::from_secs(60)),
33    };
34    // Admission uses caller authority, never a digest computed from untrusted
35    // selected bytes. Transform tools must work with this empty environment.
36    let admitted = AdmittedTool::admit(
37        &ToolSpec {
38            executable: &tool,
39            sha256: sha256
40                .to_str()
41                .ok_or("SHA-256 must be UTF-8")?
42                .parse::<Sha256Digest>()?,
43            executable_bytes: 256 * 1024 * 1024,
44            version_arguments: &["--version".into()],
45            version_identity: version.to_str().ok_or("version must be UTF-8")?,
46        },
47        &context,
48        limits,
49    )?;
50    let input = current_dir.join(input);
51    let output = current_dir.join(output);
52    let cache_root = current_dir.join(cache_root);
53    let spec = ArtifactCacheSpec::new(
54        &cache_root,
55        "example-transform",
56        "example/admitted-transform/v1",
57    )
58    .with_input("source", &input)
59    .with_tool("transformer", &tool)
60    .with_arguments(["<input>", "<output>"])
61    .with_output("result", &output)
62    .with_prune_policy(
63        ArtifactCachePrunePolicy::new()
64            .with_max_age(Duration::from_secs(7 * 24 * 60 * 60))
65            .with_max_size_bytes(2 * 1024 * 1024 * 1024),
66    );
67
68    let outcome = match prepare_artifact_cache(&spec)? {
69        ArtifactCachePreparation::Reused(record) => ArtifactCacheOutcome::Reused(record),
70        ArtifactCachePreparation::Build(transaction) => {
71            let staged_output = transaction.output_path("result")?;
72            admitted
73                .run(
74                    &[input.into_os_string(), staged_output.into_os_string()],
75                    &context,
76                    limits,
77                )?
78                .require_success()?;
79            transaction.commit()?
80        }
81    };
82
83    let disposition = if outcome.is_reused() {
84        "reused"
85    } else {
86        "built"
87    };
88    println!("{disposition} artifact set {}", outcome.record().key());
89    Ok(())
90}