Skip to main content

ic_storage/runtime/directory_model/
mod.rs

1//! Owned named-allocation directory and durable extent validation.
2pub(super) mod leases;
3mod persistence;
4
5use crate::StableKey;
6use serde::{Deserialize, Serialize};
7
8///
9/// `StorageConfig`
10///
11/// Resource ceilings checked when creating, opening and extending the directory.
12/// Physical page accounting includes reserved metadata and bucket slack.
13/// Table capacities are fixed when creating an image; reopening may impose
14/// smaller live-usage limits but cannot increase the image capacities.
15///
16
17#[derive(Clone, Copy, Debug)]
18pub struct StorageConfig {
19    /// Maximum retained named allocations, including currently omitted names.
20    pub allocations: usize,
21    /// Maximum allocated eight-page buckets across every allocation.
22    pub extents: usize,
23    /// Maximum physical backing extent, in 64 KiB Wasm pages.
24    pub pages: u64,
25}
26
27impl Default for StorageConfig {
28    fn default() -> Self {
29        Self {
30            allocations: 4_096,
31            extents: 16_384,
32            pages: 1_048_576,
33        }
34    }
35}
36
37///
38/// `AllocationId`
39///
40/// Opaque durable identity assigned by the directory. It grants no access.
41///
42
43#[derive(Clone, Copy, Debug, Deserialize, Eq, Ord, PartialEq, PartialOrd, Serialize)]
44pub struct AllocationId(u64);
45impl AllocationId {
46    /// Opaque diagnostic identity; callers cannot choose an allocation ID.
47    #[must_use]
48    pub const fn get(self) -> u64 {
49        self.0
50    }
51}
52
53///
54/// `Error`
55///
56/// Admission, bounds and custody failures from the governed allocation directory.
57///
58
59#[derive(Debug, thiserror::Error)]
60pub enum Error {
61    /// Logical page count overflowed before any backing access.
62    #[error("allocation page count overflow")]
63    ArithmeticOverflow,
64    /// The requested allocation exceeds the configured directory resource budget.
65    #[error("directory budget exceeded")]
66    Budget,
67    /// Persisted metadata or allocation geometry failed validation.
68    #[error("invalid directory: {0}")]
69    Invalid(&'static str),
70    /// An exclusive lease for the allocation already exists.
71    #[error("allocation already has a live lease")]
72    AlreadyOpen,
73    /// The requested byte range lies outside the allocation.
74    #[error("access exceeds allocation bounds")]
75    Bounds,
76    /// Another owner retains custody of the backing.
77    #[error("backing already has a live owner")]
78    AlreadyClaimed,
79    /// The requested opaque identity has no directory entry.
80    #[error("allocation does not exist")]
81    Missing,
82    /// Physical backing growth failed before the requested capacity was available.
83    #[error("backing growth refused")]
84    Growth,
85    /// Earlier interrupted backing IO invalidated this owner's in-memory authority.
86    #[error("directory owner is poisoned after interrupted backing IO")]
87    Poisoned,
88}