1mod 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#[derive(Debug, thiserror::Error)]
19pub enum RuntimeConstructionError {
20 #[error("backing already claimed")]
22 BackingAlreadyClaimed,
23 #[error(transparent)]
25 Directory(#[from] DirectoryError),
26}
27
28#[derive(Clone, Copy, Debug, Eq, PartialEq, thiserror::Error)]
30pub enum RuntimeGrowError {
31 #[error("allocation page count overflow")]
33 ArithmeticOverflow,
34 #[error("allocation capacity exceeded")]
36 CapacityExceeded,
37 #[error("backing refused growth by {additional_pages} pages")]
39 BackingRefused {
40 additional_pages: u64,
42 },
43 #[error("allocation owner is poisoned")]
45 Poisoned,
46 #[error("allocation directory validation failed")]
48 InvalidDirectory,
49}
50
51#[derive(Debug, thiserror::Error)]
53pub enum RuntimeOpenError {
54 #[error("runtime is not bootstrapped")]
56 NotBootstrapped,
57 #[error("key is not admitted: {0}")]
59 NotAdmitted(StableKey),
60 #[error("allocation {id} already open")]
62 AlreadyOpen {
63 id: u64,
65 },
66 #[error(transparent)]
68 Directory(#[from] DirectoryError),
69}
70
71#[derive(Debug, thiserror::Error)]
73pub enum RuntimeBootstrapError<E> {
74 #[error(transparent)]
76 Admission(#[from] AdmissionError),
77 #[error("host policy rejected allocation")]
79 Policy(E),
80 #[error("bootstrap binding mismatch")]
82 BindingMismatch,
83 #[error("runtime is not bootstrapped")]
85 NotBootstrapped,
86 #[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
98pub struct MemoryRuntime<M: Memory> {
107 owner: Owner<M>,
108 config: StorageConfig,
109 binding: Option<Binding>,
110}
111
112impl<M: Memory> MemoryRuntime<M> {
113 pub fn new(memory: M) -> Result<Self, RuntimeConstructionError>
118 where
119 M: MemoryBacking,
120 {
121 Self::new_with_config(memory, StorageConfig::default())
122 }
123 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 #[must_use]
146 pub const fn is_bootstrapped(&self) -> bool {
147 self.binding.is_some()
148 }
149 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 #[must_use]
161 pub const fn config(&self) -> StorageConfig {
162 self.config
163 }
164 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 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 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 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 #[must_use]
271 pub fn allocation_id(&self, key: &StableKey) -> Option<AllocationId> {
272 self.owner.allocation_id(key)
273 }
274 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 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#[derive(Clone, Copy, Debug, Eq, PartialEq, serde::Serialize)]
315pub struct StorageDiagnostics {
316 pub generation: u64,
318 pub allocations: usize,
320 pub admitted_allocations: usize,
322 pub live_leases: usize,
324 pub extents: usize,
326 pub data_pages: u64,
328 pub metadata_pages: u64,
330 pub directory_bytes: u64,
332 pub physical_pages: u64,
334 pub unassigned_pages: u64,
336}
337
338#[derive(Clone, Debug, Eq, PartialEq, serde::Serialize)]
344pub struct MemoryAllocation {
345 pub stable_key: StableKey,
347 pub id: AllocationId,
349 pub pages: u64,
351}
352
353pub 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 #[must_use]
370 pub fn size(&self) -> u64 {
371 self.lease.size()
372 }
373 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 pub fn read(&self, offset: u64, bytes: &mut [u8]) {
390 self.lease.read(offset, bytes);
391 }
392 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 unsafe { self.lease.read_unsafe(offset, dst, count) }
415 }
416 fn write(&self, offset: u64, bytes: &[u8]) {
417 self.write(offset, bytes);
418 }
419}