ic-memory 0.34.1

Durable stable-memory allocation governance for Internet Computer canisters
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

use super::{MemoryRuntime, RuntimeLifecycle, RuntimeOpenError};
use crate::{SchemaMetadata, SealedDeclarationSnapshot, StableKey};
use ic_stable_structures::Memory;

///
/// RuntimeAdoptionError
///
/// A consumer's declared requirements do not match the existing committed
/// runtime. Verification never bootstraps, grants authority, opens memory,
/// replays admission, or changes the host's policy or bucket configuration.
///

#[derive(Clone, Debug, Eq, PartialEq, thiserror::Error)]
#[non_exhaustive]
pub enum RuntimeAdoptionError {
    /// Runtime readiness, key resolution or requirement verification failed.
    #[error(transparent)]
    Open(#[from] RuntimeOpenError),
    /// The supplied snapshot contains no requests for this authority.
    #[error("no allocation requirements declared by authority '{authority}'")]
    UnknownAuthority { authority: String },
    /// This key was committed under a different current declaration authority.
    #[error(
        "stable key '{stable_key}' is committed under '{committed_authority}', not '{requested_authority}'"
    )]
    AuthorityMismatch {
        stable_key: String,
        committed_authority: String,
        requested_authority: String,
    },
    /// Declared diagnostic schema differs from the commitment.
    #[error("declaration metadata for stable key '{stable_key}' differs from the commitment")]
    DeclarationMetadataMismatch { stable_key: String },
}

impl From<super::RuntimeStateError> for RuntimeAdoptionError {
    fn from(error: super::RuntimeStateError) -> Self {
        Self::Open(RuntimeOpenError::State(error))
    }
}

impl<M: Memory> MemoryRuntime<M> {
    /// Verify every logical request for one authority in
    /// the supplied requirements against this runtime's current commitment.
    ///
    /// Requests must match key, authority and diagnostic schema while
    /// retaining the host's assigned ID. Other authorities and additional
    /// committed keys are ignored. An authority with no requirements rejects.
    /// Grants and application schema semantics are not revalidated. Success
    /// neither grants new access nor proves application lifecycle readiness.
    pub fn verify_authority(
        &self,
        requirements: &SealedDeclarationSnapshot,
        authority: &str,
    ) -> Result<(), RuntimeAdoptionError> {
        let RuntimeLifecycle::Bootstrapped {
            binding,
            committed_allocations,
        } = &self.lifecycle
        else {
            return Err(RuntimeOpenError::NotBootstrapped.into());
        };
        let mut found = false;
        for request in requirements.requests() {
            if request.authority() == authority {
                found = true;
                verify_requirement(
                    committed_allocations,
                    &binding.pool,
                    authority,
                    request.stable_key(),
                    request.schema(),
                )?;
            }
        }
        if !found {
            return Err(RuntimeAdoptionError::UnknownAuthority {
                authority: authority.to_string(),
            });
        }
        Ok(())
    }
}

fn verify_requirement(
    committed: &crate::CommittedAllocations,
    pool: &crate::MemoryAllocationPool,
    authority: &str,
    key: &StableKey,
    schema: &SchemaMetadata,
) -> Result<(), RuntimeAdoptionError> {
    let declaration =
        crate::capability::declaration_for_key(committed.declarations(), key.as_str())
            .ok_or_else(|| RuntimeOpenError::StableKeyNotCommitted(key.to_string()))?;
    let admitted_authority = pool
        .authority_for_key(key)
        .expect("committed key has an admitted owner");
    if admitted_authority != authority {
        return Err(RuntimeAdoptionError::AuthorityMismatch {
            stable_key: key.to_string(),
            committed_authority: admitted_authority.to_string(),
            requested_authority: authority.to_string(),
        });
    }
    if schema != declaration.schema() {
        return Err(RuntimeAdoptionError::DeclarationMetadataMismatch {
            stable_key: key.to_string(),
        });
    }
    Ok(())
}