ic-memory 0.24.0

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
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138

use super::{MemoryRuntime, RuntimeLifecycle, RuntimeOpenError};
use crate::{AllocationDeclaration, 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 fixed-ID verification failed.
    #[error(transparent)]
    Open(#[from] RuntimeOpenError),
    /// The supplied snapshot contains no fixed declarations or 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 or fixed-declaration label 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 fixed declaration and logical request for one authority in
    /// the supplied requirements against this runtime's current commitment.
    ///
    /// Fixed declarations must match key, ID, label and diagnostic schema;
    /// logical 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, .. } = &self.lifecycle else {
            return Err(RuntimeOpenError::NotBootstrapped.into());
        };
        let committed = &binding.declarations;
        let mut found = false;
        for registration in requirements.registered_declarations() {
            if registration.authority() == authority {
                found = true;
                let expected = registration.declaration();
                verify_requirement(
                    committed,
                    authority,
                    expected.stable_key(),
                    expected.schema(),
                    Some(expected),
                )?;
            }
        }
        for request in requirements.requests() {
            if request.authority() == authority {
                found = true;
                verify_requirement(
                    committed,
                    authority,
                    request.stable_key(),
                    request.schema(),
                    None,
                )?;
            }
        }
        if !found {
            return Err(RuntimeAdoptionError::UnknownAuthority {
                authority: authority.to_string(),
            });
        }
        Ok(())
    }
}

fn verify_requirement(
    committed: &SealedDeclarationSnapshot,
    authority: &str,
    key: &StableKey,
    schema: &SchemaMetadata,
    fixed: Option<&AllocationDeclaration>,
) -> Result<(), RuntimeAdoptionError> {
    let registration = committed
        .registered_declaration(key)
        .ok_or_else(|| RuntimeOpenError::StableKeyNotCommitted(key.to_string()))?;
    if registration.authority() != authority {
        return Err(RuntimeAdoptionError::AuthorityMismatch {
            stable_key: key.to_string(),
            committed_authority: registration.authority().to_string(),
            requested_authority: authority.to_string(),
        });
    }
    let committed = registration.declaration();
    if let Some(expected) = fixed
        && expected.slot() != committed.slot()
    {
        return Err(RuntimeOpenError::MemoryIdMismatch {
            stable_key: key.to_string(),
            committed_id: committed
                .slot()
                .memory_manager_id()
                .expect("sealed host declaration slot"),
            requested_id: expected
                .slot()
                .memory_manager_id()
                .expect("sealed requirement slot"),
        }
        .into());
    }
    if schema != committed.schema()
        || fixed.is_some_and(|expected| expected.label() != committed.label())
    {
        return Err(RuntimeAdoptionError::DeclarationMetadataMismatch {
            stable_key: key.to_string(),
        });
    }
    Ok(())
}