ic_memory/lib.rs
1#![deny(unsafe_code, unsafe_op_in_unsafe_fn)]
2#![deny(rustdoc::broken_intra_doc_links)]
3#![doc = include_str!("../README.md")]
4
5//! Stable-memory allocation-governance primitives for Internet Computer
6//! canister upgrades.
7//!
8//! `ic-memory` prevents stable-memory slot drift.
9//!
10//! Once a stable key is committed to a physical allocation slot, future binaries
11//! must either reopen that same stable key on that same slot or declare a new
12//! stable key.
13//!
14//! The crate records and validates durable ownership in both directions: an
15//! active stable key cannot move to a different physical slot, and an active
16//! physical slot cannot be reused by a different stable key.
17//!
18//! The intended runtime integration flow is:
19//!
20//! 1. Recover the persisted allocation ledger.
21//! 2. Admit consumer identity and authorized historical selections from bounded
22//! metadata under the host's `RuntimeBootstrapPolicy`.
23//! 3. Resolve key requests in the host-wide pool under current namespace grants,
24//! then validate retained key-to-ID bindings and application policy.
25//! 4. Stage and durably persist the next generation.
26//! 5. Only then open stable-memory handles through committed allocation
27//! authority.
28//!
29//! This crate owns allocation invariants, not framework policy. Namespace
30//! rules, controller authorization, endpoint lifecycle, schema migrations, and
31//! application validation belong to the framework or application.
32//!
33//! The host supplies one [`MemoryAllocationPool`] with explicit namespace grants
34//! and physical exclusions. Linked components request permanent keys and name
35//! their owner; they do not select numeric IDs or reserve component subranges.
36//! Namespace grants are current host policy, not caller authentication or
37//! persisted ownership labels. Application admission remains host-owned.
38//!
39//! Use these primitives before opening stable-memory handles. Integrations
40//! should recover the historical ledger, declare the stores expected by the
41//! current binary, admit recovered identity, resolve requests, validate against
42//! history and policy, persist a new generation, and only then publish authority
43//! before opening slots through the storage owner.
44//!
45//! Bounded physical attribution is available through
46//! [`MemoryRuntime::memory_allocations`] and
47//! [`MemoryRuntime::memory_allocations`]. It reports actual persisted
48//! buckets and explicit residuals without decoding retained ownership. Virtual
49//! extent is not payload occupancy. Opens return [`RuntimeMemory`]; explicit
50//! [`MemoryManagerConfig`] selects fresh-state buckets or checks a persisted
51//! setting without migration. The default remains 128 pages.
52//!
53//! [`MemoryRuntime`] is the canonical owner for one backing memory instance. It
54//! owns that memory's manager, ledger persistence, bootstrap lifecycle, committed
55//! capability, opens, and diagnostics. Each bootstrap attempt fallibly decodes
56//! its ledger record and uses a temporary cell for capacity-checked writes.
57//! Linked code contributes declarations to
58//! one immutable [`SealedDeclarationSnapshot`], which is supplied to each
59//! runtime independently.
60//!
61//! The host supplies the complete checked request snapshot, allocation pool and
62//! admission policy directly to the runtime. Component factories and generators
63//! contribute request lists; opening a store never registers a declaration.
64//! Exactly one runtime owns bootstrap and persistence for each backing memory.
65//!
66//! `ic-stable-structures` `MemoryManager` IDs are the first-class supported
67//! physical slot substrate. That ID domain is `u8`: IDs `0..=254` are usable,
68//! and ID `255` is always the `ic-stable-structures` unallocated sentinel.
69//! Protected current-snapshot commits and stable-cell encoding remain internal to the
70//! runtime. Public diagnostics describe their state without granting a manual
71//! commit or persistence-confirmation route.
72//!
73//! [`ic_stable_structures`] re-exports the exact substrate version used by this
74//! crate. Use its collections and traits with [`RuntimeMemory`] handles;
75//! `ic-memory` owns allocation governance without wrapping typed collections.
76
77mod allocation_pool;
78mod bounded_writer;
79mod capability;
80mod cbor;
81mod constants;
82mod declaration;
83mod diagnostics;
84mod hash;
85mod key;
86mod ledger;
87mod physical;
88mod policy;
89mod requests;
90mod runtime;
91mod schema;
92mod slot;
93mod sort;
94mod stable_cell;
95mod text;
96mod validation;
97
98#[cfg(test)]
99mod test_cbor {
100 use serde::{Serialize, de::DeserializeOwned};
101
102 pub use ciborium::Value;
103
104 pub fn to_vec<T: Serialize>(
105 value: &T,
106 ) -> Result<Vec<u8>, ciborium::ser::Error<std::io::Error>> {
107 let mut bytes = Vec::new();
108 ciborium::into_writer(value, &mut bytes)?;
109 Ok(bytes)
110 }
111
112 pub fn from_slice<T: DeserializeOwned>(
113 bytes: &[u8],
114 ) -> Result<T, ciborium::de::Error<std::io::Error>> {
115 crate::cbor::from_slice_exact(bytes)
116 }
117
118 pub fn to_value<T: Serialize>(value: T) -> Result<Value, ciborium::value::Error> {
119 Value::serialized(&value)
120 }
121
122 pub fn hex_fixture(contents: &str) -> Vec<u8> {
123 let hex = contents
124 .chars()
125 .filter(|char| !char.is_whitespace())
126 .collect::<String>();
127 assert_eq!(hex.len() % 2, 0, "fixture hex must have byte pairs");
128 hex.as_bytes()
129 .as_chunks::<2>()
130 .0
131 .iter()
132 .map(|pair| {
133 let pair = std::str::from_utf8(pair).expect("fixture hex is utf8");
134 u8::from_str_radix(pair, 16).expect("fixture hex byte")
135 })
136 .collect()
137 }
138}
139
140/// Stable collections and traits from this crate's exact substrate dependency.
141///
142/// Use the upstream collections with [`RuntimeMemory`] handles obtained through
143/// the owned runtime. This re-export preserves upstream type identity.
144pub use ic_stable_structures;
145
146pub use allocation_pool::{MemoryAllocationPool, MemoryAllocationPoolError, MemoryAuthority};
147pub use capability::CommittedAllocations;
148pub use constants::{
149 MAX_LEDGER_BYTES, MAX_LEDGER_NESTING, MAX_LEDGER_RECORD_BYTES, WASM_PAGE_SIZE_BYTES,
150};
151pub use declaration::{AllocationDeclaration, DeclarationSnapshotError};
152pub use diagnostics::{
153 DiagnosticCheck, DiagnosticCode, DiagnosticExport, DiagnosticFailure, DiagnosticMemorySize,
154 DiagnosticRecord, DiagnosticRuntimeBinding, DiagnosticStableCell, DiagnosticStableCellStatus,
155 MemoryRuntimeDoctorReport,
156};
157pub use key::{StableKey, StableKeyError};
158pub use ledger::LedgerCommitStore;
159pub use ledger::{
160 AllocationLedger, AllocationRecord, AllocationStageError, AllocationState, LedgerCommitError,
161 LedgerIntegrityError, RecoveredLedger,
162};
163pub use physical::{CommitRecoveryError, CommitSnapshotDiagnostic};
164pub use policy::{PolicyIdentity, PolicyIdentityError, RuntimeBootstrapPolicy};
165pub use requests::{MemoryDeclarationError, MemoryRequest, SealedDeclarationSnapshot};
166pub use runtime::{
167 AllocationBinding, BootstrapAdmission, BootstrapAdmissionError, GenericAllocationPolicy,
168 MemoryAllocation, MemoryAllocationSummary, MemoryAllocations, MemoryBindingSummary,
169 MemoryManagerConfig, MemoryManagerLayoutError, MemoryResolutionError, MemoryRuntime,
170 RuntimeAdoptionError, RuntimeBootstrapError, RuntimeConstructionError, RuntimeDiagnosticError,
171 RuntimeGrowError, RuntimeMemory, RuntimeOpenError,
172};
173pub use schema::{SchemaMetadata, SchemaMetadataError};
174pub use slot::{
175 IC_MEMORY_AUTHORITY_OWNER, IC_MEMORY_LEDGER_STABLE_KEY, IC_MEMORY_STABLE_KEY_PREFIX,
176 MEMORY_MANAGER_GOVERNANCE_MAX_ID, MEMORY_MANAGER_INVALID_ID, MEMORY_MANAGER_LEDGER_ID,
177 MEMORY_MANAGER_MAX_ID, MEMORY_MANAGER_MIN_ID, MemoryManagerIdRange, MemoryManagerRangeError,
178 MemoryManagerSlot, MemoryManagerSlotError, is_ic_memory_stable_key,
179 memory_manager_governance_range, validate_memory_manager_id,
180};
181pub use stable_cell::{
182 STABLE_CELL_HEADER_SIZE, STABLE_CELL_LAYOUT_VERSION, STABLE_CELL_MAGIC,
183 STABLE_CELL_VALUE_OFFSET, StableCellLedgerError, StableCellPayloadError,
184 decode_stable_cell_commit_store, decode_stable_cell_commit_store_from_memory,
185 decode_stable_cell_payload,
186};
187pub use validation::AllocationValidationError;
188
189#[cfg(test)]
190mod allocation_measurements_tests;
191
192#[cfg(any(test, feature = "test-support"))]
193pub mod testing;