ic_storage/runtime/
mod.rs

1//! Named allocation admission and exclusive leases over the owned directory.
2mod admission;
3mod custody;
4mod directory_model;
5
6use crate::{Memory, StableKey};
7pub use admission::{
8    AdmissionError, AllocationGrants, BootstrapAdmission, GenericAllocationPolicy, MemoryAuthority,
9    MemoryRequest, PolicyIdentity, RuntimeBootstrapPolicy, SealedDeclarationSnapshot,
10};
11pub use custody::{BackingIdentity, MemoryBacking};
12pub use directory_model::Error as DirectoryError;
13use directory_model::leases::{Lease, Owner};
14pub use directory_model::{AllocationId, StorageConfig};
15use std::collections::BTreeSet;
16
17/// Construction refuses aliased or malformed backing without resetting it.
18#[derive(Debug, thiserror::Error)]
19pub enum RuntimeConstructionError {
20    /// Another runtime or detached lease retains custody.
21    #[error("backing already claimed")]
22    BackingAlreadyClaimed,
23    /// The current owned directory could not be loaded or initialized.
24    #[error(transparent)]
25    Directory(#[from] DirectoryError),
26}
27
28/// Allocation growth failures before authority publication.
29#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
30pub enum RuntimeGrowError {
31    /// Requested page arithmetic overflowed.
32    #[error("allocation page count overflow")]
33    ArithmeticOverflow,
34    /// The configured allocation or directory resource budget was exceeded.
35    #[error("allocation capacity exceeded")]
36    CapacityExceeded,
37    /// Physical backing capacity was refused.
38    #[error("backing refused growth by {additional_pages} pages")]
39    BackingRefused { additional_pages: u64 },
40    /// A previous backing failure poisoned this owner.
41    #[error("allocation owner is poisoned")]
42    Poisoned,
43    /// Directory validation failed at a checked boundary.
44    #[error("allocation directory validation failed")]
45    InvalidDirectory,
46}
47
48/// A key cannot be opened until current host admission succeeds.
49#[derive(Debug, thiserror::Error)]
50pub enum RuntimeOpenError {
51    /// Bootstrap has not committed current authority.
52    #[error("runtime is not bootstrapped")]
53    NotBootstrapped,
54    /// The key is absent from the current admitted declarations.
55    #[error("key is not admitted: {0}")]
56    NotAdmitted(StableKey),
57    /// An exclusive lease for this allocation is already alive.
58    #[error("allocation {id} already open")]
59    AlreadyOpen { id: u64 },
60    /// The directory refused opening.
61    #[error(transparent)]
62    Directory(#[from] DirectoryError),
63}
64
65/// Bootstrap failed before current authority could be published.
66#[derive(Debug, thiserror::Error)]
67pub enum RuntimeBootstrapError<E> {
68    /// Host declarations or namespace grants were invalid.
69    #[error(transparent)]
70    Admission(#[from] AdmissionError),
71    /// The host's policy rejected the preparation or an allocation.
72    #[error("host policy rejected allocation")]
73    Policy(E),
74    /// Current bootstrap inputs differ from the established binding.
75    #[error("bootstrap binding mismatch")]
76    BindingMismatch,
77    /// A shared verification cannot bootstrap an uninitialized owner.
78    #[error("runtime is not bootstrapped")]
79    NotBootstrapped,
80    /// Durable directory commitment failed.
81    #[error(transparent)]
82    Directory(#[from] DirectoryError),
83}
84
85struct Binding {
86    source: SealedDeclarationSnapshot,
87    grants: AllocationGrants,
88    policy: PolicyIdentity,
89    admitted: BTreeSet<StableKey>,
90}
91
92///
93/// `MemoryRuntime`
94///
95/// One custodian of named allocations on a backing. Bootstrap validates namespace
96/// grants and host policy, commits bindings, then permits exclusive leases.
97/// Omitted retained names keep their allocation, but require current admission
98/// before opening. IDs are opaque u64 values, never selected by applications.
99///
100pub struct MemoryRuntime<M: Memory> {
101    owner: Owner<M>,
102    config: StorageConfig,
103    binding: Option<Binding>,
104}
105
106impl<M: Memory> MemoryRuntime<M> {
107    /// Claim backing and create or read its owned directory. Never reset nonempty backing.
108    ///
109    /// # Errors
110    /// Rejects duplicate backing custody or invalid/non-admissible retained directory data.
111    pub fn new(memory: M) -> Result<Self, RuntimeConstructionError>
112    where
113        M: MemoryBacking,
114    {
115        Self::new_with_config(memory, StorageConfig::default())
116    }
117    /// Use explicit directory resource limits; reopening revalidates under those limits.
118    ///
119    /// # Errors
120    /// Rejects duplicate backing custody, invalid configuration, or invalid/non-admissible retained directory data.
121    pub fn new_with_config(
122        memory: M,
123        config: StorageConfig,
124    ) -> Result<Self, RuntimeConstructionError>
125    where
126        M: MemoryBacking,
127    {
128        let owner = Owner::init(memory, config).map_err(|error| match error {
129            DirectoryError::AlreadyClaimed => RuntimeConstructionError::BackingAlreadyClaimed,
130            error => RuntimeConstructionError::Directory(error),
131        })?;
132        Ok(Self {
133            owner,
134            config,
135            binding: None,
136        })
137    }
138    /// Whether current host authority has been committed.
139    #[must_use]
140    pub const fn is_bootstrapped(&self) -> bool {
141        self.binding.is_some()
142    }
143    /// Current durable directory generation, after bootstrap admission.
144    ///
145    /// # Errors
146    /// Returns `NotBootstrapped` until bootstrap establishes a binding.
147    pub fn committed_generation(&self) -> Result<u64, RuntimeOpenError> {
148        if self.binding.is_none() {
149            return Err(RuntimeOpenError::NotBootstrapped);
150        }
151        Ok(self.owner.generation())
152    }
153    /// Effective resource admission limits.
154    #[must_use]
155    pub const fn config(&self) -> StorageConfig {
156        self.config
157    }
158    /// Admit a complete declaration set, retaining omitted historical bindings.
159    ///
160    /// # Errors
161    /// Rejects invalid grants or declarations, host-policy refusal, conflicting bindings, and directory validation or commitment failures.
162    pub fn bootstrap<P: RuntimeBootstrapPolicy>(
163        &mut self,
164        source: &SealedDeclarationSnapshot,
165        grants: &AllocationGrants,
166        policy: &P,
167    ) -> Result<u64, RuntimeBootstrapError<P::Error>> {
168        if self.binding.is_some() {
169            return self.verify_bootstrap(source, grants, policy);
170        }
171        self.owner.verify()?;
172        let policy_identity = policy.runtime_bootstrap_identity();
173        let bindings = self.owner.bindings();
174        let mut admission =
175            BootstrapAdmission::new(source, grants, &bindings, self.config.allocations)?;
176        let result = policy.prepare_bootstrap(&mut admission);
177        let (requests, admitted) = admission.complete()?;
178        result.map_err(RuntimeBootstrapError::Policy)?;
179        for request in requests {
180            policy
181                .validate_allocation(request.stable_key())
182                .map_err(RuntimeBootstrapError::Policy)?;
183        }
184        self.owner.bind(&admitted)?;
185        self.binding = Some(Binding {
186            source: source.clone(),
187            grants: grants.clone(),
188            policy: policy_identity,
189            admitted,
190        });
191        Ok(self.owner.generation())
192    }
193    /// Compare the complete established binding without IO or policy callbacks.
194    ///
195    /// # Errors
196    /// Returns `NotBootstrapped` or `BindingMismatch` when the supplied composition differs from the established binding.
197    pub fn verify_bootstrap<P: RuntimeBootstrapPolicy>(
198        &self,
199        source: &SealedDeclarationSnapshot,
200        grants: &AllocationGrants,
201        policy: &P,
202    ) -> Result<u64, RuntimeBootstrapError<P::Error>> {
203        let binding = self
204            .binding
205            .as_ref()
206            .ok_or(RuntimeBootstrapError::NotBootstrapped)?;
207        if binding.source != *source
208            || binding.grants != *grants
209            || binding.policy != policy.runtime_bootstrap_identity()
210        {
211            return Err(RuntimeBootstrapError::BindingMismatch);
212        }
213        Ok(self.owner.generation())
214    }
215    /// Open one currently admitted name, preserving custody through detached handles.
216    /// Uses the live admitted directory without backing IO. To check backing
217    /// integrity explicitly, use [`Self::diagnostics`] or [`Self::memory_allocations`].
218    ///
219    /// # Panics
220    /// Propagates a broken internal binding invariant.
221    ///
222    /// # Errors
223    /// Rejects unbootstrapped or unadmitted access, an existing lease, and a poisoned owner.
224    pub fn open_memory(&self, key: &StableKey) -> Result<RuntimeMemory<M>, RuntimeOpenError> {
225        let binding = self
226            .binding
227            .as_ref()
228            .ok_or(RuntimeOpenError::NotBootstrapped)?;
229        if !binding.admitted.contains(key) {
230            return Err(RuntimeOpenError::NotAdmitted(key.clone()));
231        }
232        let lease = self.owner.lease(key).map_err(|error| match error {
233            DirectoryError::AlreadyOpen => RuntimeOpenError::AlreadyOpen {
234                id: self.allocation_id(key).unwrap().get(),
235            },
236            error => RuntimeOpenError::Directory(error),
237        })?;
238        Ok(RuntimeMemory { lease })
239    }
240    /// Verify component requirements against current host admission without IO.
241    ///
242    /// # Errors
243    /// Rejects unbootstrapped access or requirements not admitted under the requested authority.
244    pub fn verify_authority(
245        &self,
246        requirements: &SealedDeclarationSnapshot,
247        authority: &str,
248    ) -> Result<(), RuntimeOpenError> {
249        let binding = self
250            .binding
251            .as_ref()
252            .ok_or(RuntimeOpenError::NotBootstrapped)?;
253        for request in requirements.requests() {
254            if request.authority() != authority
255                || !binding.admitted.contains(request.stable_key())
256                || binding.grants.check(request).is_err()
257            {
258                return Err(RuntimeOpenError::NotAdmitted(request.stable_key().clone()));
259            }
260        }
261        Ok(())
262    }
263    /// Resolve a retained identity for diagnostics; this grants no access.
264    #[must_use]
265    pub fn allocation_id(&self, key: &StableKey) -> Option<AllocationId> {
266        self.owner.allocation_id(key)
267    }
268    /// Observe checked directory entries and actual logical extents.
269    ///
270    /// # Errors
271    /// Returns a directory error when ownership is poisoned or the retained directory fails validation.
272    pub fn memory_allocations(&self) -> Result<Vec<MemoryAllocation>, DirectoryError> {
273        self.owner.verify()?;
274        Ok(self
275            .owner
276            .bindings()
277            .into_iter()
278            .map(|(stable_key, id, pages)| MemoryAllocation {
279                stable_key,
280                id,
281                pages,
282            })
283            .collect())
284    }
285
286    /// Validate the current directory and report physical capacity and custody.
287    /// Available before bootstrap; collecting diagnostics never admits or opens a key.
288    /// Page totals describe reserved capacity, not application payload occupancy.
289    ///
290    /// # Errors
291    /// Rejects a poisoned owner or backing that no longer matches its directory.
292    pub fn diagnostics(&self) -> Result<StorageDiagnostics, DirectoryError> {
293        let mut report = self.owner.diagnostics()?;
294        report.admitted_allocations = self.binding.as_ref().map_or(0, |b| b.admitted.len());
295        Ok(report)
296    }
297}
298
299///
300/// `StorageDiagnostics`
301///
302/// Read-only totals from the validated current directory and physical backing.
303/// The protected root occupies one additional page: data, metadata, unassigned
304/// and root pages sum to physical pages. Unassigned pages are not reclaimable
305/// through this API. Diagnostics grant no allocation authority.
306///
307
308#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Serialize)]
309pub struct StorageDiagnostics {
310    /// Committed directory generation.
311    pub generation: u64,
312    /// Retained named allocations, including currently omitted names.
313    pub allocations: usize,
314    /// Names admitted by this runtime's bootstrap, or zero before bootstrap.
315    pub admitted_allocations: usize,
316    /// Currently live exclusive allocation leases.
317    pub live_leases: usize,
318    /// Total allocated application buckets.
319    pub extents: usize,
320    /// Logical data capacity across retained allocations, in 64 KiB pages.
321    pub data_pages: u64,
322    /// Reserved allocation controls excluding the protected root page, in 64 KiB pages.
323    pub metadata_pages: u64,
324    /// Used root, name/size rows and bucket-owner bytes.
325    pub directory_bytes: u64,
326    /// Actual physical backing extent, in 64 KiB pages.
327    pub physical_pages: u64,
328    /// Reserved bucket slack outside logical data, controls and the root page.
329    pub unassigned_pages: u64,
330}
331
332///
333/// `MemoryAllocation`
334///
335/// Passive diagnostic entry; no lease or allocation authority is carried.
336///
337#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
338pub struct MemoryAllocation {
339    /// Durable name.
340    pub stable_key: StableKey,
341    /// Opaque identity.
342    pub id: AllocationId,
343    /// Logical extent in Wasm pages.
344    pub pages: u64,
345}
346
347///
348/// `RuntimeMemory`
349///
350/// Exclusive non-cloneable allocation lease. IO trusts custody between checked
351/// boundaries; growth commits the directory before publishing its new extent.
352/// A detached lease retains the backing claim until it is dropped.
353///
354pub struct RuntimeMemory<M: Memory> {
355    lease: Lease<M>,
356}
357impl<M: Memory> RuntimeMemory<M> {
358    #[cfg(not(target_arch = "wasm32"))]
359    pub(crate) fn poison_on_unwind(&self) -> directory_model::leases::PanicGuard<M> {
360        self.lease.poison_on_unwind()
361    }
362    /// Logical page extent.
363    #[must_use]
364    pub fn size(&self) -> u64 {
365        self.lease.size()
366    }
367    /// Reserve additional zero-filled logical pages without exposing backing.
368    ///
369    /// # Errors
370    /// Rejects arithmetic overflow, resource limits, backing refusal, poisoned ownership, or invalid directory state.
371    pub fn grow(&self, pages: u64) -> Result<u64, RuntimeGrowError> {
372        self.lease.try_grow(pages).map_err(|error| match error {
373            DirectoryError::ArithmeticOverflow => RuntimeGrowError::ArithmeticOverflow,
374            DirectoryError::Growth => RuntimeGrowError::BackingRefused {
375                additional_pages: pages,
376            },
377            DirectoryError::Budget => RuntimeGrowError::CapacityExceeded,
378            DirectoryError::Poisoned => RuntimeGrowError::Poisoned,
379            _ => RuntimeGrowError::InvalidDirectory,
380        })
381    }
382    /// Read a completely bounds-checked logical range.
383    pub fn read(&self, offset: u64, bytes: &mut [u8]) {
384        self.lease.read(offset, bytes);
385    }
386    /// Write a completely bounds-checked logical range.
387    pub fn write(&self, offset: u64, bytes: &[u8]) {
388        self.lease.write(offset, bytes);
389    }
390}
391impl<M: Memory> Memory for RuntimeMemory<M> {
392    fn size(&self) -> u64 {
393        self.size()
394    }
395    fn grow(&self, pages: u64) -> i64 {
396        self.grow(pages)
397            .map_or(-1, |previous| i64::try_from(previous).expect("page count"))
398    }
399    fn read(&self, offset: u64, bytes: &mut [u8]) {
400        self.read(offset, bytes);
401    }
402    #[expect(
403        unsafe_code,
404        reason = "Forward the raw-read contract through the governed lease"
405    )]
406    unsafe fn read_unsafe(&self, offset: u64, dst: *mut u8, count: usize) {
407        // SAFETY: forwarding preserves the caller's exclusive destination.
408        unsafe { self.lease.read_unsafe(offset, dst, count) }
409    }
410    fn write(&self, offset: u64, bytes: &[u8]) {
411        self.write(offset, bytes);
412    }
413}
ic_storage/runtime/mod.rs

ic_storage/runtime/
mod.rs
