canic-host 0.110.53

Host-side App build and desired-state Fleet reconciliation library for Canic workspaces
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121

//! Module: protocol_binding::release
//!
//! Responsibility: select infrastructure Candid from a terminal Fleet's selected release.
//! Does not own: Fleet discovery, live admission or release production.
//! Boundary: finalized manifest authority and terminal protocol identity must agree.

#[cfg(test)]
mod tests;

use crate::{
    protocol_binding::{
        ProtocolBindingError, RegistryProtocolBinding, ResolvedProtocolBinding,
        resolve_protocol_binding,
    },
    registry::RegistryEntry,
    release_build::{ReleaseBuildPlanError, validate_finalized_release_build_manifest},
    release_set::{
        CanicInfrastructureArtifactPersistenceError, CurrentReleaseSetManifestError,
        load_persisted_canic_infrastructure_artifact_manifest,
        load_persisted_current_release_set_manifest,
    },
};
use canic_core::ids::ReleaseBuildId;
use std::path::{Path, PathBuf};
use thiserror::Error;

/// Failures binding a retained infrastructure participant to its immutable release.
#[derive(Debug, Error)]
pub enum ReleaseProtocolBindingError {
    #[error("Canister {canister} does not match its selected release infrastructure artifact")]
    ArtifactBindingMismatch { canister: String },

    #[error(transparent)]
    Binding(#[from] ProtocolBindingError),

    #[error(transparent)]
    Infrastructure(#[from] CanicInfrastructureArtifactPersistenceError),

    #[error("selected release infrastructure manifest digest does not match finalization")]
    ManifestDigestMismatch,

    #[error(transparent)]
    ReleaseBuild(#[from] ReleaseBuildPlanError),

    #[error(transparent)]
    ReleaseSet(#[from] CurrentReleaseSetManifestError),

    #[error("selected release Candid sidecar is not a regular contained file: {}", path.display())]
    UnsafeCandid { path: PathBuf },
}

/// Resolve an infrastructure participant using its exact retained release, before transport.
pub fn resolve_release_registry_protocol_binding(
    root: &Path,
    release_build_id: ReleaseBuildId,
    entry: &RegistryEntry,
) -> Result<ResolvedProtocolBinding, ReleaseProtocolBindingError> {
    let release = load_persisted_current_release_set_manifest(root, release_build_id)?;
    validate_finalized_release_build_manifest(root, release_build_id, &release.path)?;
    let infrastructure =
        load_persisted_canic_infrastructure_artifact_manifest(root, release_build_id)?;
    if infrastructure.digest != release.manifest.infrastructure_artifact_manifest_sha256 {
        return Err(ReleaseProtocolBindingError::ManifestDigestMismatch);
    }
    let mismatch = || ReleaseProtocolBindingError::ArtifactBindingMismatch {
        canister: entry.pid.clone(),
    };
    let artifact = infrastructure
        .manifest
        .entries
        .iter()
        .find(|artifact| entry.role.as_deref() == Some(artifact.protocol_role.as_str()))
        .ok_or_else(mismatch)?;
    resolve_infrastructure_registry_protocol_binding(root, artifact, entry)
}

/// Bind a participant to an artifact after the caller has verified its manifest provenance.
pub fn resolve_infrastructure_registry_protocol_binding(
    root: &Path,
    artifact: &crate::release_set::CanicInfrastructureArtifactEntry,
    entry: &RegistryEntry,
) -> Result<ResolvedProtocolBinding, ReleaseProtocolBindingError> {
    let mismatch = || ReleaseProtocolBindingError::ArtifactBindingMismatch {
        canister: entry.pid.clone(),
    };
    let binding = entry.protocol_binding.as_ref().ok_or_else(mismatch)?;
    let expected = RegistryProtocolBinding {
        release_identity: artifact.protocol_release_identity.clone(),
        role: artifact.protocol_role.clone(),
        capabilities: artifact.protocol_capabilities.clone(),
        candid_sha256: artifact.candid_sha256,
        protocol_profile_digest: artifact.protocol_profile_digest,
    };
    if binding != &expected
        || entry.role.as_deref() != Some(artifact.protocol_role.as_str())
        || entry.module_hash.as_deref() != Some(&artifact.wasm_sha256_hex)
    {
        return Err(mismatch());
    }
    let candid_path = root
        .join(&artifact.wasm_relative_path)
        .with_extension("did");
    require_contained_sidecar(root, &candid_path)?;
    Ok(resolve_protocol_binding(&entry.pid, expected, candid_path)?)
}

pub fn require_contained_sidecar(
    root: &Path,
    path: &Path,
) -> Result<(), ReleaseProtocolBindingError> {
    let unsafe_path = || ReleaseProtocolBindingError::UnsafeCandid {
        path: path.to_path_buf(),
    };
    let canonical_root = root.canonicalize().map_err(|_| unsafe_path())?;
    let parent = path.parent().ok_or_else(unsafe_path)?;
    let canonical_parent = parent.canonicalize().map_err(|_| unsafe_path())?;
    if !canonical_parent.starts_with(canonical_root) {
        return Err(unsafe_path());
    }
    Ok(())
}