Module artifacts

Expand description

Host-side artifact discovery, freshness, and Wasm build helpers.

These functions keep integration-test artifacts in caller-selected target directories and contain no application-specific package or profile policy. Independent Wasm batches remain sequential; WasmBuildSession adds explicit cross-call resolution reuse, while WasmBuildInputSnapshot prepares a fixed specification set for concurrent readers. Both require a caller-held source lease.

Successful Wasm and generic artifact records retain their read-only exact paths against cache replacement and pruning. Retain the record (or a clone) through consumption; paths and artifact descriptors alone carry no ownership. Batch reports own their successful records even when later entries fail.

use ic_build::artifacts::{
    ArtifactCacheOutcome, ArtifactCachePreparation, ArtifactCacheSpec,
    WasmBuildSpec, build_wasm_canisters_cached, prepare_artifact_cache,
    resolve_cargo_build_inputs,
};
use ic_host_artifacts::artifact::hash_reader;
use ic_host_process::tool::{AdmittedTool, ExecutionContext, OutputLimits};
use std::path::Path;

// The caller holds its source lease and configures the Cargo shim and actual
// compiler identity on spec. The admitted optimizer accepts INPUT -o OUTPUT.
fn build_deployable(
    spec: &WasmBuildSpec, post_cache: &Path, destination: &Path,
    optimizer: &AdmittedTool, context: &ExecutionContext<'_>, limits: OutputLimits,
    max_output_bytes: usize,
) -> Result<Vec<u8>, Box<dyn std::error::Error>>
{
    let resolved = resolve_cargo_build_inputs(spec)?;
    let wasm = build_wasm_canisters_cached(spec)?;
    let input = &wasm.record().artifacts()[0];
    let post_spec = ArtifactCacheSpec::new(post_cache, "deploy", "optimizer/v1")
        .with_cargo_build_inputs("cargo", spec, &resolved)
        .with_input("wasm", input)
        .with_tool("optimizer", optimizer.path())
        .with_arguments(["<input>", "-o", "<output>"])
        .with_environment(context.environment.iter().cloned())
        .with_identity_bytes("optimizer-cwd", context.current_dir.as_os_str().as_encoded_bytes())
        .with_output("deploy", destination);
    let deploy = match prepare_artifact_cache(&post_spec)? {
        ArtifactCachePreparation::Reused(record) => ArtifactCacheOutcome::Reused(record),
        ArtifactCachePreparation::Build(transaction) => {
            let output = transaction.output_path("deploy")?;
            optimizer.run(&[input.into(), "-o".into(), output.clone().into()], context, limits)?.require_success()?;
            hash_reader(std::fs::File::open(&output)?, max_output_bytes as u64)?;
            transaction.commit()?
        }
    };
    drop(wasm); // The post-link transaction has finished consuming the input.
    let bytes = ic_host_fs::read::read_file(
        deploy.record().artifacts()[0].path(), max_output_bytes)?;
    drop(deploy); // Reading is complete; maintenance may now reclaim it.
    Ok(bytes)
}

Structs§

ArtifactBuildTransaction: Owned miss transaction holding the recipe and content-key process locks.
ArtifactCacheArtifact: One read-only exact artifact retained by its owning acquisition record.
ArtifactCacheBatchEntry: One ordered labeled result from a generic artifact batch.
ArtifactCacheBatchFailedEntry: One failed generic artifact batch entry.
ArtifactCacheBatchFailureTimings: Partial phase timings retained for one failed artifact batch entry.
ArtifactCacheBatchMetrics: Aggregate counters and successful-acquisition timings for an artifact batch.
ArtifactCacheBatchOutcomeEntry: One successful generic artifact batch entry.
ArtifactCacheBatchReport: Ordered labeled entries from a collect-all artifact transaction batch.
ArtifactCachePrunePolicy: Caller-selected retention limits for content-addressed artifact entries.
ArtifactCachePruneReport: Summary of one lock-coordinated artifact-cache pruning pass.
ArtifactCacheRecord: Details shared by built and reused transactional artifact outcomes.
ArtifactCacheSpec: Complete caller-owned description of one transactional artifact set.
ArtifactCacheTimings: Phase timings for one transactional artifact-cache acquisition.
ArtifactStagingDirectory: Temporary artifact directory retained until its owner is closed or dropped.
CapturedArtifact: Owned copy of one completed producer output, independent of later source replacement.
CargoBuildInput: One exact local Cargo source or configuration input under a stable logical label.
InputDigest: SHA-256 digest of one deterministic artifact-input set.
InputEvidence: Per-path bytes, directory membership or explicit absence observed before work.
InputEvidenceSpec: Caller-selected filesystem roots, exclusions and opaque non-file identity.
LabeledArtifactCacheSpec: Caller-labeled specification for one generic artifact batch entry.
LabeledWasmBuildSpec: Caller-labeled specification for one exact Wasm batch entry.
ResolvedCargoBuildInputs: Resolved exact inputs and identity for one WasmBuildSpec.
SharedIncrementalTargetInspection: Lock-coordinated disk-usage observation for a caller-owned shared Cargo target.
SharedIncrementalTargetMaintenance: Result of explicit shared Cargo target maintenance.
SharedIncrementalTargetMaintenanceConfig: Scheduled shared incremental-target maintenance attached to a Wasm acquisition.
SharedIncrementalTargetPrunePolicy: Whole-target retention limits for caller-owned shared Cargo state.
WasmBuildBatchConfig: Orchestration shared by every entry in one independent Wasm build batch.
WasmBuildBatchEntry: One ordered caller-labeled result from a Wasm build batch.
WasmBuildBatchFailure: One failed Wasm batch entry with its retained wall-clock time.
WasmBuildBatchMaintenanceEntry: One integrated shared-target maintenance outcome from a Wasm batch.
WasmBuildBatchMetrics: Aggregate counters and successful-acquisition timings for a Wasm build batch.
WasmBuildBatchOutcomeEntry: One successful Wasm batch entry.
WasmBuildBatchReport: Ordered outcomes and failures from a collect-all Wasm build batch.
WasmBuildFailureDetails: Structured phase and partial timings for one failed Wasm entry.
WasmBuildFailureTimings: Partial phase timings retained when a Wasm acquisition fails.
WasmBuildInputSnapshot: Immutable prepared Cargo input resolution shared by concurrent readers.
WasmBuildInputSnapshotMetrics: Preparation and reader-reuse counters for one immutable input snapshot.
WasmBuildProgressConfig: Observation settings for one cacheable Wasm build.
WasmBuildRecord: Details shared by built and reused Wasm outcomes.
WasmBuildSession: Explicit cross-call input snapshot scoped to a caller-held source lease.
WasmBuildSessionMetrics: Aggregate state retained by one explicit Wasm build session.
WasmBuildSpec: Complete caller-owned description of one cacheable Cargo Wasm build.
WasmBuildTimings: Timings for cache coordination, input resolution, and Cargo execution.
WasmInputResolutionTimings: Detailed timings for exact Wasm build-input resolution.
WatchedInputSnapshot: Exact content digest captured across a set of watched input trees.

Enums§

ArtifactCacheBatchContractError: Structural error that prevents a labeled artifact batch from starting.
ArtifactCacheBatchFailure: Failure from one entry in a collect-all artifact transaction batch.
ArtifactCacheBatchFailurePhase: Primary phase in which a generic artifact batch entry failed.
ArtifactCacheError: Structured failure from transactional artifact caching.
ArtifactCacheMaintenance: Nonfatal retention attempted as part of a successful cache acquisition.
ArtifactCacheOutcome: Whether an artifact transaction published or reused its exact output set.
ArtifactCachePreparation: Result of preparing a transactional artifact-set acquisition.
ArtifactOutputValidation: Built-in validation applied to one transactional artifact output.
InputEvidenceError: Failure to capture or validate standalone input authority.
InputEvidenceValue: Exact filesystem fact recorded for an input path.
SharedIncrementalTargetMaintenanceFailureMode: Failure handling for integrated shared incremental-target maintenance.
SharedIncrementalTargetMaintenanceOutcome: Result of interval-limited shared Cargo target maintenance.
WasmBuildBatchContractError: Structural error that prevents a labeled Wasm batch from starting.
WasmBuildBatchProgressEvent: Structured progress for an independent sequence of exact Wasm builds.
WasmBuildCacheMode: Cargo-target ownership mode for one exact cached Wasm build.
WasmBuildError: Structured failure from a cacheable Wasm build.
WasmBuildFailurePhase: Primary phase in which one cacheable Wasm acquisition failed.
WasmBuildOutcome: Whether a cacheable Wasm build ran Cargo or reused exact matching artifacts.
WasmBuildOutputStream: Raw child-process stream attached to a Cargo progress event.
WasmBuildPhase: External phase associated with a cacheable Wasm build failure.
WasmBuildProgressEvent: Structured progress emitted by an observed cacheable Wasm build.
WasmBuildProgressOutcome: Final cache state reported by a successful observed build.
WasmBuildProgressPhase: Potentially long phase of one observed Wasm-cache acquisition.

Functions§

build_artifact_caches_batch: Build every independent caller-labeled artifact specification.
build_wasm_canisters_cached: Build or reuse one exact set of Cargo Wasm artifacts.
build_wasm_canisters_cached_batch: Build every Wasm specification as an independent Cargo invocation.
build_wasm_canisters_cached_batch_with_config: Build an independent Wasm batch with shared batch orchestration.
build_wasm_canisters_cached_batch_with_config_and_progress: Build a configured independent Wasm batch while forwarding structured progress.
build_wasm_canisters_cached_batch_with_progress: Build an independent Wasm batch while forwarding structured progress.
build_wasm_canisters_cached_with_progress: Build or reuse one exact Wasm set while streaming structured progress.
discover_cargo_depfile_inputs: Discover source inputs from .d records directly in caller-selected directories.
icp_artifact_ready_for_build: Check whether an ICP artifact exists, is nonempty, and is fresh against watched inputs.
icp_artifact_ready_with_snapshot: Check one ICP artifact against one already-captured watched-input snapshot.
inspect_shared_incremental_target: Inspect one configured shared Cargo target under its build coordination lock.
maintain_shared_incremental_target: Apply explicit whole-target retention to caller-owned shared Cargo state.
maintain_shared_incremental_target_at_most_every: Apply whole-target retention at most once per interval across processes.
parse_cargo_depfile: Parse Cargo/rustc Make depfiles without interpreting unsupported Make syntax.
prepare_artifact_cache: Verify or begin one exact external artifact-set transaction.
prune_artifact_cache: Prune one transactional artifact namespace without acquiring an artifact.
prune_wasm_build_cache: Prune fingerprint-specific Cargo target directories under target_dir.
resolve_cargo_build_inputs: Resolve the exact Cargo source, configuration, toolchain, argument, and environment identity.
test_target_dir: Return <workspace>/target/<name> for isolated host-side test artifacts.
wasm_artifacts_ready: Check whether every requested Wasm artifact is a regular file.
wasm_path: Resolve one crate’s Wasm artifact under a caller-selected Cargo target directory.
workspace_root_for: Ask Cargo for the workspace owning a crate manifest directory.