ic_testkit/artifacts/
mod.rs

1//! Host-side artifact discovery, freshness, and Wasm build helpers.
2//!
3//! These functions keep integration-test artifacts in caller-selected target
4//! directories and contain no application-specific package or profile policy.
5//! Independent Wasm batches remain sequential; [`WasmBuildSession`] adds
6//! explicit cross-call resolution reuse, while [`WasmBuildInputSnapshot`]
7//! prepares a fixed specification set for concurrent readers. Both require a
8//! caller-held source lease.
9//!
10//! Successful Wasm and generic artifact records retain their read-only exact
11//! paths against cache replacement and pruning. Retain the record (or a clone)
12//! through consumption; paths and artifact descriptors alone carry no ownership.
13//! Batch reports own their successful records even when later entries fail.
14//!
15//! ```no_run
16//! use ic_testkit::artifacts::{
17//!     ArtifactCacheOutcome, ArtifactCachePreparation, ArtifactCacheSpec,
18//!     WasmBuildSpec, build_wasm_canisters_cached, prepare_artifact_cache,
19//! };
20//! use std::path::Path;
21//!
22//! fn build_deployable(spec: &WasmBuildSpec, post_cache: &Path, destination: &Path)
23//!     -> Result<Vec<u8>, Box<dyn std::error::Error>>
24//! {
25//!     let wasm = build_wasm_canisters_cached(spec)?;
26//!     let input = &wasm.record().artifacts()[0];
27//!     let post_spec = ArtifactCacheSpec::new(post_cache, "deploy", "copy/v1")
28//!         .with_input("wasm", input)
29//!         .with_output("deploy", destination);
30//!     let deploy = match prepare_artifact_cache(&post_spec)? {
31//!         ArtifactCachePreparation::Reused(record) => ArtifactCacheOutcome::Reused(record),
32//!         ArtifactCachePreparation::Build(transaction) => {
33//!             // A real post-link recipe can write transformed bytes to
34//!             // transaction.output_path("deploy") instead of copying.
35//!             transaction.import_output("deploy", input)?;
36//!             transaction.commit()?
37//!         }
38//!     };
39//!     drop(wasm); // The post-link transaction has finished consuming the input.
40//!     let bytes = std::fs::read(deploy.record().artifacts()[0].path())?;
41//!     drop(deploy); // Reading is complete; maintenance may now reclaim it.
42//!     Ok(bytes)
43//! }
44//! ```
45
46mod cache_fs;
47mod digest;
48mod icp;
49mod transaction;
50mod transaction_batch;
51mod wasm;
52mod wasm_batch;
53mod wasm_cache;
54mod workspace;
55
56#[cfg(test)]
57mod test_support;
58
59#[cfg(all(test, unix))]
60mod host_tests;
61
62pub use cache_fs::{ArtifactCacheMaintenance, ArtifactCachePrunePolicy, ArtifactCachePruneReport};
63pub use digest::InputDigest;
64pub use icp::{
65    WatchedInputSnapshot, icp_artifact_ready_for_build, icp_artifact_ready_with_snapshot,
66};
67pub use transaction::{
68    ArtifactBuildTransaction, ArtifactCacheArtifact, ArtifactCacheError, ArtifactCacheOutcome,
69    ArtifactCachePreparation, ArtifactCacheRecord, ArtifactCacheSpec, ArtifactCacheTimings,
70    ArtifactOutputValidation, prepare_artifact_cache, prune_artifact_cache,
71};
72pub use transaction_batch::{
73    ArtifactCacheBatchContractError, ArtifactCacheBatchEntry, ArtifactCacheBatchFailedEntry,
74    ArtifactCacheBatchFailure, ArtifactCacheBatchFailurePhase, ArtifactCacheBatchFailureTimings,
75    ArtifactCacheBatchMetrics, ArtifactCacheBatchOutcomeEntry, ArtifactCacheBatchReport,
76    LabeledArtifactCacheSpec, build_artifact_caches_batch,
77};
78pub use wasm::{read_wasm, wasm_artifacts_ready, wasm_path};
79pub use wasm_batch::{
80    LabeledWasmBuildSpec, WasmBuildBatchConfig, WasmBuildBatchContractError, WasmBuildBatchEntry,
81    WasmBuildBatchFailure, WasmBuildBatchMaintenanceEntry, WasmBuildBatchMetrics,
82    WasmBuildBatchOutcomeEntry, WasmBuildBatchProgressEvent, WasmBuildBatchReport,
83    WasmBuildInputSnapshot, WasmBuildInputSnapshotMetrics, WasmBuildSession,
84    WasmBuildSessionMetrics, build_wasm_canisters_cached_batch,
85    build_wasm_canisters_cached_batch_with_config,
86    build_wasm_canisters_cached_batch_with_config_and_progress,
87    build_wasm_canisters_cached_batch_with_progress,
88};
89pub use wasm_cache::{
90    CargoBuildInput, ResolvedCargoBuildInputs, SharedIncrementalTargetInspection,
91    SharedIncrementalTargetMaintenance, SharedIncrementalTargetMaintenanceConfig,
92    SharedIncrementalTargetMaintenanceFailureMode, SharedIncrementalTargetMaintenanceOutcome,
93    SharedIncrementalTargetPrunePolicy, WasmBuildCacheMode, WasmBuildError,
94    WasmBuildFailureDetails, WasmBuildFailurePhase, WasmBuildFailureTimings, WasmBuildOutcome,
95    WasmBuildOutputStream, WasmBuildPhase, WasmBuildProgressConfig, WasmBuildProgressEvent,
96    WasmBuildProgressOutcome, WasmBuildProgressPhase, WasmBuildRecord, WasmBuildSpec,
97    WasmBuildTimings, WasmInputResolutionTimings, build_wasm_canisters_cached,
98    build_wasm_canisters_cached_with_progress, inspect_shared_incremental_target,
99    maintain_shared_incremental_target, maintain_shared_incremental_target_at_most_every,
100    prune_wasm_build_cache, resolve_cargo_build_inputs,
101};
102pub use workspace::{test_target_dir, workspace_root_for};
ic_testkit/artifacts/mod.rs

ic_testkit/artifacts/
mod.rs
