appcore_storage/
storage.rs

1// =============================================================================
2//        #######
3//     ###       ###     F: storage.rs
4//    ##   ## ##   ##    P: AppCore-Runtime
5//         ## ##
6//                       C: 2026/05/31 13:38:42 by dnettoRaw
7//    ##   ## ##   ##    U: 2026/08/02 00:04:12 by dnettoRaw
8//      ###########      S: 1.0.1-rc.8
9// =============================================================================
10
11//! Minimal storage contracts (no concrete database implementation).
12
13/// Storage-local result type.
14pub type StorageResult<T> = Result<T, StorageError>;
15
16/// Storage-local typed errors.
17#[derive(Debug, Clone, PartialEq, Eq)]
18pub enum StorageError {
19    /// Provider is unavailable or not open.
20    NotAvailable,
21    /// Requested repository or file does not exist.
22    RepositoryNotFound(String),
23    /// Migration execution or compatibility failed.
24    MigrationFailed(String),
25    /// Atomic storage operation failed.
26    TransactionFailed(String),
27    /// Provider does not implement transaction semantics.
28    TransactionsUnsupported,
29    /// Backup operation failed.
30    BackupFailed(String),
31    /// Path escaped or violated the provider root policy.
32    InvalidPath(String),
33    /// Cryptographic storage operation failed.
34    SecurityFailed(String),
35    /// Required authentication boundary is unavailable.
36    AuthUnavailable(String),
37}
38
39/// Coarse storage availability status.
40#[derive(Debug, Clone, Copy, PartialEq, Eq)]
41pub enum StorageStatus {
42    /// Provider is available for reads and writes.
43    Online,
44    /// Provider remains available with reduced guarantees.
45    Degraded,
46    /// Provider accepts reads only.
47    ReadOnly,
48    /// Provider is unavailable.
49    Offline,
50}
51
52/// Storage health snapshot.
53#[derive(Debug, Clone, PartialEq, Eq)]
54pub struct StorageHealth {
55    /// Coarse storage status.
56    pub status: StorageStatus,
57    /// Optional non-sensitive detail.
58    pub message: Option<String>,
59}
60
61/// Stable repository name.
62#[derive(Debug, Clone, PartialEq, Eq, Hash)]
63pub struct RepositoryName(
64    /// Stable repository identifier.
65    pub String,
66);
67
68/// Stable migration identifier.
69#[derive(Debug, Clone, PartialEq, Eq, Hash)]
70pub struct MigrationId(
71    /// Stable migration identifier.
72    pub String,
73);
74
75/// Backup descriptor contract.
76#[derive(Debug, Clone, PartialEq, Eq)]
77pub struct BackupDescriptor {
78    /// Provider-owned backup name.
79    pub name: String,
80    /// Creation timestamp in Unix milliseconds.
81    pub created_at_ms: u64,
82}
83
84/// Transaction contract for unit-of-work boundaries.
85pub trait Transaction {
86    /// Atomically commits the unit of work.
87    fn commit(&mut self) -> StorageResult<()>;
88    /// Discards the unit of work.
89    fn rollback(&mut self) -> StorageResult<()>;
90}
91
92/// Repository contract for app/runtime persistence boundaries.
93pub trait Repository {
94    /// Returns the stable repository name.
95    fn name(&self) -> &RepositoryName;
96}
97
98/// Migration contract.
99pub trait Migration {
100    /// Returns the stable migration identity.
101    fn id(&self) -> &MigrationId;
102    /// Applies this migration within an explicit transaction boundary.
103    fn apply(&self, tx: &mut dyn Transaction) -> StorageResult<()>;
104}
105
106/// Storage provider contract.
107pub trait StorageProvider {
108    /// Returns coarse provider availability.
109    fn status(&self) -> StorageStatus;
110    /// Returns a current provider health snapshot.
111    fn health(&self) -> StorageHealth;
112    /// Opens and validates provider resources.
113    fn open(&mut self) -> StorageResult<()>;
114    /// Closes provider resources.
115    fn close(&mut self) -> StorageResult<()>;
116    /// Begins a real unit of work or fails explicitly when unsupported.
117    fn begin_transaction(&mut self) -> StorageResult<Box<dyn Transaction>>;
118    /// Lists provider-owned backups.
119    fn list_backups(&self) -> Vec<BackupDescriptor>;
120}
121
122#[path = "storage_auth_http.rs"]
123mod storage_auth_http;
124#[path = "storage_auth_remote.rs"]
125mod storage_auth_remote;
126#[path = "storage_backup.rs"]
127mod storage_backup;
128#[path = "storage_backup_io.rs"]
129mod storage_backup_io;
130#[path = "storage_backup_list.rs"]
131mod storage_backup_list;
132#[path = "storage_capability.rs"]
133mod storage_capability;
134#[path = "storage_file.rs"]
135mod storage_file;
136#[path = "storage_file_fs.rs"]
137mod storage_file_fs;
138#[path = "storage_tree.rs"]
139mod storage_tree;
140pub use storage_auth_remote::{
141    data_claims, make_auth_request, now_ms, open_remote_request, open_remote_response,
142    process_remote_request, seal_remote_request, seal_remote_response, transport_claims,
143    validate_auth_resource, AuthRemoteRequest, AuthRemoteResponse, RemoteAuthStorageClient,
144    AUTH_REMOTE_ENDPOINT, AUTH_REMOTE_SCHEMA, DEFAULT_AUTH_REMOTE_MAX_BYTES,
145    DEFAULT_AUTH_REMOTE_MAX_HTTP_RESPONSE_BYTES, DEFAULT_AUTH_REMOTE_MAX_PLAINTEXT_BYTES,
146    DEFAULT_AUTH_REMOTE_MAX_SEALED_BYTES, DEFAULT_AUTH_REMOTE_TIMEOUT_MS,
147    DEFAULT_AUTH_REMOTE_TTL_MS,
148};
149pub use storage_backup::{
150    StorageBackupManifestFileV1, StorageBackupManifestV1, MAX_STORAGE_SNAPSHOT_BYTES,
151    STORAGE_BACKUP_FORMAT_V1,
152};
153pub use storage_capability::{
154    StorageCapabilityCatalogV1, StorageCapabilityDescriptorV1, StorageCapabilityError,
155    StorageCapabilityProviderV1, StorageCapabilityRequirementsV1, StorageCapabilityV1,
156    MAX_STORAGE_CAPABILITY_PROVIDERS_V1, STORAGE_CAPABILITY_COUNT_V1,
157    STORAGE_CAPABILITY_DESCRIPTOR_VERSION_V1, STORAGE_REQUIRED_CAPABILITIES_SETTING,
158};
159#[path = "storage_dnt.rs"]
160mod storage_dnt;
161pub use storage_dnt::{
162    DntFileObjectStore, DntFileSecretStore, DntFileSnapshotStore, SealedObjectStore,
163    SealedSecretStore, SealedSnapshotStore, SealedStoragePolicy,
164};
165pub use storage_file::{
166    file_storage_capability_descriptor_v1, FileStorageProvider, DEFAULT_FILE_READ_MAX_BYTES,
167    MAX_STORAGE_BACKUP_FILE_BYTES,
168};
169#[cfg(test)]
170pub(crate) use storage_file_fs::tmp_path_for;
171
172#[cfg(test)]
173#[path = "storage_backup_tests.rs"]
174mod storage_backup_tests;
175#[cfg(test)]
176#[path = "storage_tests.rs"]
177mod storage_tests;
appcore_storage/storage.rs

appcore_storage/
storage.rs
