ic_memory/
lib.rs

1#![forbid(unsafe_code)]
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 integration flow is:
19//!
20//! 1. Recover the persisted allocation ledger.
21//! 2. Declare the stable stores expected by the current binary.
22//! 3. Validate those declarations against ledger history and any framework
23//!    policy.
24//! 4. Commit the next generation.
25//! 5. Only then open stable-memory handles through a validated allocation
26//!    session.
27//!
28//! This crate owns allocation invariants, not framework policy. Namespace
29//! rules, controller authorization, endpoint lifecycle, schema migrations, and
30//! application validation belong to the framework or application.
31//!
32//! For the default `MemoryManager` runtime, registered `ic-memory` range claims
33//! are generic allocation policy and are enforced before caller-supplied
34//! policy. A framework such as Canic that wants higher-level range semantics
35//! should adapt to this contract deliberately: either register the ranges it
36//! wants `ic-memory` to enforce, or omit user ranges and enforce application
37//! space through its own [`AllocationPolicy`].
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, validate declarations against history and policy, commit a
42//! new generation, and only then publish a validated allocation session that can
43//! open slots through a storage substrate.
44//!
45//! [`AllocationBootstrap`] is the golden path for whichever layer owns a given
46//! ledger store. Canic may own bootstrap for a framework canister and compose
47//! IcyDB/application declarations through its registry; IcyDB may own bootstrap
48//! directly for generated database stores; or a standalone application canister
49//! may own bootstrap itself. Exactly one owner should bootstrap one ledger
50//! store. Multiple layers in the same canister must either compose declarations
51//! into that owner or use distinct ledger stores and allocation domains.
52//!
53//! `ic-stable-structures` `MemoryManager` IDs are the first-class supported
54//! physical slot substrate. That ID domain is `u8`: IDs `0..=254` are usable,
55//! and ID `255` is always the `ic-stable-structures` unallocated sentinel.
56//! The crate still keeps narrow internal abstractions for storage adapters and
57//! diagnostics, but the native IC path is
58//! `MemoryManager` ID 0 -> `ic-stable-structures::Cell<StableCellLedgerRecord,
59//! _>` -> [`LedgerCommitStore`] -> [`CommittedGenerationBytes`] ->
60//! [`LedgerPayloadEnvelope`] -> [`RecoveredLedger`] -> [`ValidatedAllocations`].
61//!
62//! `ic-memory` is not a replacement for `ic-stable-structures` collections and
63//! does not wrap typed stores such as `StableBTreeMap`.
64
65pub mod bootstrap;
66mod constants;
67pub mod declaration;
68pub mod diagnostics;
69pub mod key;
70pub mod ledger;
71pub mod physical;
72pub mod policy;
73pub mod registry;
74pub mod runtime;
75pub mod schema;
76pub mod session;
77pub mod slot;
78pub mod stable_cell;
79pub mod substrate;
80pub mod validation;
81
82pub use ic_stable_structures as stable_structures;
83
84pub use bootstrap::{
85    AllocationBootstrap, BootstrapCommit, BootstrapError, BootstrapReservationError,
86    BootstrapRetirementError,
87};
88pub use constants::WASM_PAGE_SIZE_BYTES;
89pub use declaration::{
90    AllocationDeclaration, DeclarationCollector, DeclarationSnapshot, DeclarationSnapshotError,
91};
92pub use diagnostics::{
93    DefaultMemoryManagerDoctorReport, DiagnosticCheck, DiagnosticCheckStatus,
94    DiagnosticDeclaration, DiagnosticExport, DiagnosticGeneration, DiagnosticMemorySize,
95    DiagnosticRangeAuthority, DiagnosticRecord, DiagnosticStableCell, DiagnosticStableCellStatus,
96};
97pub use key::{StableKey, StableKeyError};
98pub use ledger::{
99    AllocationHistory, AllocationLedger, AllocationRecord, AllocationReservationError,
100    AllocationRetirement, AllocationRetirementError, AllocationStageError, AllocationState,
101    GenerationRecord, LedgerCommitError, LedgerCommitStore, LedgerIntegrityError,
102    LedgerPayloadEnvelope, LedgerPayloadEnvelopeError, RecoveredLedger, SchemaMetadataRecord,
103};
104pub use physical::{
105    AuthoritativeSlot, CommitRecoveryError, CommitSlotDiagnostic, CommitSlotIndex,
106    CommitStoreDiagnostic, CommittedGenerationBytes, DualCommitStore, DualProtectedCommitStore,
107    ProtectedGenerationSlot, select_authoritative_slot,
108};
109pub use policy::AllocationPolicy;
110pub use registry::{
111    StaticMemoryDeclaration, StaticMemoryDeclarationError, StaticMemoryRangeDeclaration,
112    collect_static_memory_declarations, register_static_memory_declaration,
113    register_static_memory_manager_declaration,
114    register_static_memory_manager_declaration_with_schema, register_static_memory_manager_range,
115    register_static_memory_range_declaration, static_memory_declaration_snapshot,
116    static_memory_declarations, static_memory_range_authority, static_memory_range_declarations,
117};
118pub use runtime::{
119    RuntimeBootstrapError, RuntimeDiagnosticError, RuntimeOpenError, RuntimePolicyError,
120    bootstrap_default_memory_manager, bootstrap_default_memory_manager_with_policy,
121    default_memory_manager_commit_recovery_diagnostic, default_memory_manager_diagnostic_export,
122    default_memory_manager_doctor_report,
123};
124pub use schema::{SchemaMetadata, SchemaMetadataError};
125pub use session::{AllocationSession, AllocationSessionError, ValidatedAllocations};
126pub use slot::{
127    AllocationSlot, AllocationSlotDescriptor, IC_MEMORY_AUTHORITY_OWNER,
128    IC_MEMORY_AUTHORITY_PURPOSE, IC_MEMORY_LEDGER_LABEL, IC_MEMORY_LEDGER_STABLE_KEY,
129    IC_MEMORY_STABLE_KEY_PREFIX, MEMORY_MANAGER_GOVERNANCE_MAX_ID, MEMORY_MANAGER_INVALID_ID,
130    MEMORY_MANAGER_LEDGER_ID, MEMORY_MANAGER_MAX_ID, MEMORY_MANAGER_MIN_ID,
131    MemoryManagerAuthorityRecord, MemoryManagerIdRange, MemoryManagerRangeAuthority,
132    MemoryManagerRangeAuthorityError, MemoryManagerRangeError, MemoryManagerRangeMode,
133    MemoryManagerSlotError, is_ic_memory_stable_key, memory_manager_governance_range,
134    validate_memory_manager_id,
135};
136pub use stable_cell::{
137    STABLE_CELL_HEADER_SIZE, STABLE_CELL_LAYOUT_VERSION, STABLE_CELL_MAGIC,
138    STABLE_CELL_VALUE_OFFSET, StableCellLedgerError, StableCellLedgerRecord,
139    StableCellPayloadError, decode_stable_cell_ledger_record, decode_stable_cell_payload,
140    validate_stable_cell_ledger_memory,
141};
142pub use substrate::{LedgerAnchor, StorageSubstrate};
143pub use validation::{AllocationValidationError, Validate, validate_allocations};
144
145#[doc(hidden)]
146pub mod __reexports {
147    pub use ctor;
148}
149
150/// Register a `MemoryManager` allocation declaration during static initialization.
151///
152/// This macro only registers declaration metadata. It does not open stable
153/// memory. The bootstrap owner still has to collect/seal declarations, validate
154/// them against the ledger, commit the generation, and then open memory handles.
155#[macro_export]
156macro_rules! ic_memory_declaration {
157    (key = $stable_key:literal, ty = $label:path, id = $id:expr $(,)?) => {
158        const _: () = {
159            #[allow(dead_code)]
160            type IcMemoryTypeCheck = $label;
161
162            #[ $crate::__reexports::ctor::ctor(unsafe, anonymous, crate_path = $crate::__reexports::ctor) ]
163            fn __ic_memory_register_static_declaration() {
164                $crate::register_static_memory_manager_declaration(
165                    $id,
166                    env!("CARGO_PKG_NAME"),
167                    stringify!($label),
168                    $stable_key,
169                )
170                .expect("ic-memory static memory declaration failed");
171            }
172        };
173    };
174    (key = $stable_key:literal, label = $label:literal, id = $id:expr $(,)?) => {
175        const _: () = {
176            #[ $crate::__reexports::ctor::ctor(unsafe, anonymous, crate_path = $crate::__reexports::ctor) ]
177            fn __ic_memory_register_static_declaration() {
178                $crate::register_static_memory_manager_declaration(
179                    $id,
180                    env!("CARGO_PKG_NAME"),
181                    $label,
182                    $stable_key,
183                )
184                .expect("ic-memory static memory declaration failed");
185            }
186        };
187    };
188}
189
190/// Declare a `MemoryManager` allocation range during static initialization.
191#[macro_export]
192macro_rules! ic_memory_range {
193    (start = $start:expr, end = $end:expr $(,)?) => {
194        $crate::ic_memory_range!(
195            start = $start,
196            end = $end,
197            mode = Reserved,
198        );
199    };
200    (start = $start:expr, end = $end:expr, mode = $mode:ident $(,)?) => {
201        const _: () = {
202            #[ $crate::__reexports::ctor::ctor(unsafe, anonymous, crate_path = $crate::__reexports::ctor) ]
203            fn __ic_memory_register_static_range() {
204                $crate::register_static_memory_manager_range(
205                    $start,
206                    $end,
207                    env!("CARGO_PKG_NAME"),
208                    $crate::MemoryManagerRangeMode::$mode,
209                    None,
210                )
211                .expect("ic-memory static memory range declaration failed");
212            }
213        };
214    };
215}
216
217/// Declare and open a validated `MemoryManager` slot by stable key.
218///
219/// The macro registers declaration metadata during static initialization and
220/// returns the validated default-runtime memory handle at expression use time.
221#[macro_export]
222macro_rules! ic_memory_key {
223    ($stable_key:literal, $label:path, $id:expr $(,)?) => {{
224        $crate::ic_memory_declaration!(key = $stable_key, ty = $label, id = $id,);
225        $crate::runtime::open_default_memory_manager_memory($stable_key, $id)
226            .expect("ic-memory failed to open validated stable memory; bootstrap must run first and the stable key/id must match the validated declaration")
227    }};
228    (key = $stable_key:literal, ty = $label:path, id = $id:expr $(,)?) => {{ $crate::ic_memory_key!($stable_key, $label, $id) }};
229    (key = $stable_key:literal, label = $label:literal, id = $id:expr $(,)?) => {{
230        $crate::ic_memory_declaration!(key = $stable_key, label = $label, id = $id,);
231        $crate::runtime::open_default_memory_manager_memory($stable_key, $id)
232            .expect("ic-memory failed to open validated stable memory; bootstrap must run first and the stable key/id must match the validated declaration")
233    }};
234}
235
236/// Register one pre-bootstrap hook.
237#[macro_export]
238macro_rules! eager_init {
239    ($body:block) => {
240        const _: () = {
241            fn __ic_memory_registered_eager_init_body() {
242                $body
243            }
244
245            #[ $crate::__reexports::ctor::ctor(unsafe, anonymous, crate_path = $crate::__reexports::ctor) ]
246            fn __ic_memory_register_eager_init() {
247                $crate::runtime::defer_eager_init(__ic_memory_registered_eager_init_body);
248            }
249        };
250    };
251}
ic_memory/lib.rs

ic_memory/
lib.rs
