Skip to main content

ArtifactCacheSpec

ic_build::artifacts

Struct ArtifactCacheSpec 

Source 
pub struct ArtifactCacheSpec { /* private fields */ }
Expand description

Complete caller-owned description of one transactional artifact set.

Declared inputs and tools must not be located inside cache_root. Output destinations must remain outside it, resolve to distinct non-nested paths, and not overlap a declared input or tool. Cargo-derived cache/output paths must likewise remain outside resolved inputs unless covered by their exact generated-state exclusions.

Implementations§

Source§

impl ArtifactCacheSpec

Source

pub fn new(cache_root: &Path, namespace: &str, recipe_id: &str) -> Self

Describe one external artifact recipe using non-secret stable identifiers.

The namespace selects an independent content store. recipe_id must be bumped whenever undeclared pipeline semantics change. The default coordination scope is the namespace.

Examples found in repository?
examples/transactional_artifact_cache.rs (lines 53-57)
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 fn with_coordination_scope(self, coordination_scope: &str) -> Self

Serialize recipes that share caller-owned mutable external build state.

Source

pub fn with_input(self, label: &str, path: &Path) -> Self

Add one exact input file or directory outside the cache root under a stable label.

Examples found in repository?
examples/transactional_artifact_cache.rs (line 58)
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 fn with_tool(self, label: &str, path: &Path) -> Self

Add one exact executable or tool path outside the cache root under a stable label.

Examples found in repository?
examples/transactional_artifact_cache.rs (line 59)
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 fn with_arguments<I, S>(self, arguments: I) -> Self
where I: IntoIterator<Item = S>, S: AsRef<OsStr>,

Set OS-native ordered command arguments that contribute to the content key.

Examples found in repository?
examples/transactional_artifact_cache.rs (line 60)
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 fn with_environment<I, K, V>(self, environment: I) -> Self
where I: IntoIterator<Item = (K, V)>, K: Into<OsString>, V: Into<OsString>,

Set OS-native environment values that contribute to the content key.

This records identity only. The caller must apply these values to the external command executed on a cache miss.

Source

pub fn with_unset_environment<I, S>(self, names: I) -> Self
where I: IntoIterator<Item = S>, S: Into<OsString>,

Record OS-native environment names whose unset state contributes to the content key.

The caller must also remove these names from the external command’s environment on a cache miss.

Source

pub fn with_identity_bytes(self, label: &str, value: &[u8]) -> Self

Add opaque non-secret identity bytes under a stable logical label.

Labels are stored in canonical order; declaration order does not affect identity.

Source

pub fn with_cargo_build_inputs( self, label: &str, build_spec: &WasmBuildSpec, resolved: &ResolvedCargoBuildInputs, ) -> Self

Add one exact Cargo input snapshot as transactional cache identity and guard.

The semantic resolved fingerprint keys toolchain, arguments, environment and the selected dependency closure. Its conservative Cargo-aware validation paths and exclusions are rehashed automatically during preparation, cache-hit materialization and transaction commit. Labels are stored in canonical order; declaration order does not affect identity.

Source

pub fn with_output(self, name: &str, destination: &Path) -> Self

Declare one nonempty regular-file output and its nonoverlapping public destination.

Examples found in repository?
examples/transactional_artifact_cache.rs (line 61)
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 fn with_output_validation( self, name: &str, destination: &Path, validation: ArtifactOutputValidation, ) -> Self

Declare one output, nonoverlapping public destination, and validation policy.

Source

pub const fn with_prune_policy(self, policy: ArtifactCachePrunePolicy) -> Self

Apply best-effort retention while protecting the acquired entry.

Examples found in repository?
examples/transactional_artifact_cache.rs (lines 62-66)
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 with_prune_policy_at_most_every( self, policy: ArtifactCachePrunePolicy, minimum_interval: Duration, ) -> Self

Apply retention at most once per minimum_interval for this namespace.

The small due-marker check still occurs under the namespace lock. Successful acquisitions skip the directory scan until the interval has elapsed. The interval applies to attempted maintenance, including a nonfatal failed attempt. A zero interval is equivalent to Self::with_prune_policy.

Source

pub fn cache_root(&self) -> &Path

Caller-selected root containing cache data and coordination locks.

Source

pub fn namespace(&self) -> &str

Stable caller-owned content-store namespace.

Source

pub fn recipe_id(&self) -> &str

Stable caller-owned external recipe identity.

Trait Implementations§

Source§

impl Clone for ArtifactCacheSpec

Source§

fn clone(&self) -> Self

Returns a duplicate of the value. Read more
1.0.0 (const: unstable) · Source§

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

Performs copy-assignment from source. Read more
Source§

impl Debug for ArtifactCacheSpec

Source§

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

Formats the value using the given formatter. Read more
Source§

impl Eq for ArtifactCacheSpec

Source§

impl PartialEq for ArtifactCacheSpec

Source§

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

Equality operator ==. Read more
1.0.0 (const: unstable) · Source§

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

Inequality operator !=. Read more
Source§

impl StructuralPartialEq for ArtifactCacheSpec

Auto Trait Implementations§

Blanket Implementations§

Source§

impl<T> Any for T
where T: 'static + ?Sized,

Source§

fn type_id(&self) -> TypeId

Gets the TypeId of self. Read more
Source§

impl<T> Borrow<T> for T
where T: ?Sized,

Source§

fn borrow(&self) -> &T

Immutably borrows from an owned value. Read more
Source§

impl<T> BorrowMut<T> for T
where T: ?Sized,

Source§

fn borrow_mut(&mut self) -> &mut T

Mutably borrows from an owned value. Read more
Source§

impl<T> CloneToUninit for T
where T: Clone,

Source§

unsafe fn clone_to_uninit(&self, dest: *mut u8)

🔬This is a nightly-only experimental API. (clone_to_uninit)
Performs copy-assignment from self to dest. Read more
Source§

impl<T> From<T> for T

Source§

fn from(t: T) -> T

Returns the argument unchanged.

Source§

impl<T, U> Into<U> for T
where U: From<T>,

Source§

fn into(self) -> U

Calls U::from(self).

That is, this conversion is whatever the implementation of From<T> for U chooses to do.

Source§

impl<T> Same for T

Source§

type Output = T

Should always be Self
Source§

impl<T> ToOwned for T
where T: Clone,

Source§

type Owned = T

The resulting type after obtaining ownership.
Source§

fn to_owned(&self) -> T

Creates owned data from borrowed data, usually by cloning. Read more
Source§

fn clone_into(&self, target: &mut T)

Uses borrowed data to replace owned data, usually by cloning. Read more
Source§

impl<T, U> TryFrom<U> for T
where U: Into<T>,

Source§

type Error = !

The type returned in the event of a conversion error.
Source§

fn try_from(value: U) -> Result<T, !>

Performs the conversion.
Source§

impl<T, U> TryInto<U> for T
where U: TryFrom<T>,

Source§

type Error = <U as TryFrom<T>>::Error

The type returned in the event of a conversion error.
Source§

fn try_into(self) -> Result<U, <U as TryFrom<T>>::Error>

Performs the conversion.