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}