Skip to main content

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