Skip to main content

dekopon_provider_storage/
lib.rs

1//! This crate contains component bindings only; it cannot select a host path, namespace,
2//! transaction, authority, or storage backend.
3
4#![forbid(unsafe_code)]
5#![cfg_attr(test, allow(clippy::unwrap_used))]
6#![cfg_attr(
7    test,
8    allow(
9        clippy::disallowed_methods,
10        clippy::disallowed_types,
11        reason = "tests spawn, join and drain freely; production sites carry their own expectation"
12    )
13)]
14pub const STORAGE_WIT: &str = include_str!("../wit/deps/storage.wit");
15
16#[cfg(feature = "jsonl")]
17mod jsonl_bindings {
18    wit_bindgen::generate!({
19        path: "wit",
20        world: "jsonl-client",
21        generate_all,
22    });
23}
24
25#[cfg(feature = "durable-files")]
26mod durable_bindings {
27    wit_bindgen::generate!({
28        path: "wit",
29        world: "durable-files-client",
30        generate_all,
31    });
32}
33
34#[cfg(feature = "jsonl")]
35pub mod jsonl {
36    //! Curated JSONL operations. Writes take effect per host call without invocation-wide rollback.
37
38    use std::{error::Error, fmt};
39
40    use super::jsonl_bindings::dekopon::storage::jsonl as wit;
41
42    #[derive(Clone, Debug, Eq, PartialEq)]
43    pub struct Chunk {
44        pub bytes: Vec<u8>,
45        pub next_offset: u64,
46        pub eof: bool,
47    }
48
49    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
50    pub enum StorageError {
51        NotFound,
52        AlreadyExists,
53        InvalidName,
54        InvalidArgument,
55        PermissionDenied,
56        QuotaExceeded,
57        Busy,
58        Timeout,
59        Unsupported,
60        Corrupt,
61        Io,
62    }
63
64    impl fmt::Display for StorageError {
65        fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
66            write!(
67                formatter,
68                "{}",
69                match self {
70                    Self::NotFound => "not found",
71                    Self::AlreadyExists => "already exists",
72                    Self::InvalidName => "invalid logical name",
73                    Self::InvalidArgument => "invalid argument",
74                    Self::PermissionDenied => "permission denied",
75                    Self::QuotaExceeded => "quota exceeded",
76                    Self::Busy => "busy",
77                    Self::Timeout => "timeout",
78                    Self::Unsupported => "unsupported",
79                    Self::Corrupt => "corrupt",
80                    Self::Io => "storage I/O failed",
81                }
82            )
83        }
84    }
85
86    impl Error for StorageError {}
87
88    pub fn size(name: &str) -> Result<u64, StorageError> {
89        wit::size(name).map_err(map_error)
90    }
91
92    pub fn read_chunk(name: &str, offset: u64, max_bytes: u32) -> Result<Chunk, StorageError> {
93        wit::read_chunk(name, offset, max_bytes)
94            .map(|chunk| Chunk {
95                bytes: chunk.bytes,
96                next_offset: chunk.next_offset,
97                eof: chunk.eof,
98            })
99            .map_err(map_error)
100    }
101
102    pub fn append(name: &str, expected_size: u64, record: &[u8]) -> Result<u64, StorageError> {
103        wit::append(name, expected_size, record).map_err(map_error)
104    }
105
106    pub fn replace(name: &str, expected_size: u64, contents: &[u8]) -> Result<(), StorageError> {
107        wit::replace(name, expected_size, contents).map_err(map_error)
108    }
109
110    fn map_error(error: wit::StorageError) -> StorageError {
111        match error {
112            wit::StorageError::NotFound => StorageError::NotFound,
113            wit::StorageError::AlreadyExists => StorageError::AlreadyExists,
114            wit::StorageError::InvalidName => StorageError::InvalidName,
115            wit::StorageError::InvalidArgument => StorageError::InvalidArgument,
116            wit::StorageError::PermissionDenied => StorageError::PermissionDenied,
117            wit::StorageError::QuotaExceeded => StorageError::QuotaExceeded,
118            wit::StorageError::Busy => StorageError::Busy,
119            wit::StorageError::Timeout => StorageError::Timeout,
120            wit::StorageError::Unsupported => StorageError::Unsupported,
121            wit::StorageError::Corrupt => StorageError::Corrupt,
122            wit::StorageError::Io => StorageError::Io,
123        }
124    }
125
126    #[cfg(test)]
127    mod tests {
128        use super::{StorageError, map_error, wit};
129
130        #[test]
131        fn every_wit_error_maps_to_its_own_variant() {
132            let table = [
133                (wit::StorageError::NotFound, StorageError::NotFound),
134                (
135                    wit::StorageError::AlreadyExists,
136                    StorageError::AlreadyExists,
137                ),
138                (wit::StorageError::InvalidName, StorageError::InvalidName),
139                (
140                    wit::StorageError::InvalidArgument,
141                    StorageError::InvalidArgument,
142                ),
143                (
144                    wit::StorageError::PermissionDenied,
145                    StorageError::PermissionDenied,
146                ),
147                (
148                    wit::StorageError::QuotaExceeded,
149                    StorageError::QuotaExceeded,
150                ),
151                (wit::StorageError::Busy, StorageError::Busy),
152                (wit::StorageError::Timeout, StorageError::Timeout),
153                (wit::StorageError::Unsupported, StorageError::Unsupported),
154                (wit::StorageError::Corrupt, StorageError::Corrupt),
155                (wit::StorageError::Io, StorageError::Io),
156            ];
157            assert_eq!(table.len(), 11, "every WIT failure class must be covered");
158            for (wire, expected) in table {
159                assert_eq!(map_error(wire), expected, "{wire:?} must not be remapped");
160            }
161        }
162    }
163}
164
165#[cfg(feature = "durable-files")]
166pub mod durable_files {
167
168    use std::{error::Error, fmt};
169
170    use super::durable_bindings::dekopon::storage::durable_files as wit;
171
172    /// Validated open intent. At least one of read or write must be selected.
173    #[derive(Clone, Copy, Debug, Default, Eq, PartialEq)]
174    #[expect(
175        clippy::struct_excessive_bools,
176        reason = "reshaped by the unit that next rewrites this"
177    )]
178    pub struct OpenOptions {
179        pub read: bool,
180        pub write: bool,
181        pub create: bool,
182        pub create_new: bool,
183        pub delete_on_close: bool,
184    }
185
186    impl OpenOptions {
187        #[must_use]
188        pub const fn new() -> Self {
189            Self {
190                read: false,
191                write: false,
192                create: false,
193                create_new: false,
194                delete_on_close: false,
195            }
196        }
197
198        #[must_use]
199        pub const fn read(mut self, enabled: bool) -> Self {
200            self.read = enabled;
201            self
202        }
203        #[must_use]
204        pub const fn write(mut self, enabled: bool) -> Self {
205            self.write = enabled;
206            self
207        }
208        #[must_use]
209        pub const fn create(mut self, enabled: bool) -> Self {
210            self.create = enabled;
211            self
212        }
213        #[must_use]
214        pub const fn create_new(mut self, enabled: bool) -> Self {
215            self.create_new = enabled;
216            self
217        }
218        #[must_use]
219        pub const fn delete_on_close(mut self, enabled: bool) -> Self {
220            self.delete_on_close = enabled;
221            self
222        }
223    }
224
225    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
226    pub enum Durability {
227        Data,
228        DataAndMetadata,
229        Full,
230    }
231
232    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
233    pub struct FileStat {
234        pub size: u64,
235        pub identity: u64,
236    }
237
238    #[derive(Clone, Copy, Debug, Eq, PartialEq)]
239    pub enum StorageError {
240        NotFound,
241        AlreadyExists,
242        InvalidName,
243        InvalidArgument,
244        PermissionDenied,
245        QuotaExceeded,
246        Busy,
247        Timeout,
248        Unsupported,
249        Corrupt,
250        Io,
251    }
252
253    impl fmt::Display for StorageError {
254        fn fmt(&self, formatter: &mut fmt::Formatter<'_>) -> fmt::Result {
255            write!(
256                formatter,
257                "{}",
258                match self {
259                    Self::NotFound => "not found",
260                    Self::AlreadyExists => "already exists",
261                    Self::InvalidName => "invalid logical name",
262                    Self::InvalidArgument => "invalid argument",
263                    Self::PermissionDenied => "permission denied",
264                    Self::QuotaExceeded => "quota exceeded",
265                    Self::Busy => "busy",
266                    Self::Timeout => "timeout",
267                    Self::Unsupported => "unsupported",
268                    Self::Corrupt => "corrupt",
269                    Self::Io => "storage I/O failed",
270                }
271            )
272        }
273    }
274
275    impl Error for StorageError {}
276
277    pub struct File(wit::File);
278
279    impl File {
280        pub fn read_at(&self, offset: u64, max_bytes: u32) -> Result<Vec<u8>, StorageError> {
281            self.0.read_at(offset, max_bytes).map_err(map_error)
282        }
283        pub fn write_at(&self, offset: u64, bytes: &[u8]) -> Result<(), StorageError> {
284            self.0.write_at(offset, bytes).map_err(map_error)
285        }
286        pub fn size(&self) -> Result<u64, StorageError> {
287            self.0.size().map_err(map_error)
288        }
289        pub fn truncate(&self, size: u64) -> Result<(), StorageError> {
290            self.0.truncate(size).map_err(map_error)
291        }
292        pub fn sync(&self, mode: Durability) -> Result<(), StorageError> {
293            self.0.sync(map_durability(mode)).map_err(map_error)
294        }
295    }
296
297    pub fn open(name: &str, options: OpenOptions) -> Result<File, StorageError> {
298        let mut flags = wit::OpenFlags::empty();
299        flags.set(wit::OpenFlags::READ, options.read);
300        flags.set(wit::OpenFlags::WRITE, options.write);
301        flags.set(wit::OpenFlags::CREATE, options.create);
302        flags.set(wit::OpenFlags::CREATE_NEW, options.create_new);
303        flags.set(wit::OpenFlags::DELETE_ON_CLOSE, options.delete_on_close);
304        wit::open(name, flags).map(File).map_err(map_error)
305    }
306
307    pub fn stat(name: &str) -> Result<Option<FileStat>, StorageError> {
308        wit::stat(name)
309            .map(|value| {
310                value.map(|stat| FileStat {
311                    size: stat.size,
312                    identity: stat.identity,
313                })
314            })
315            .map_err(map_error)
316    }
317
318    pub fn remove(name: &str, mode: Durability) -> Result<(), StorageError> {
319        wit::remove(name, map_durability(mode)).map_err(map_error)
320    }
321
322    pub fn rename_atomic(
323        from: &str,
324        to: &str,
325        replace: bool,
326        mode: Durability,
327    ) -> Result<(), StorageError> {
328        wit::rename_atomic(from, to, replace, map_durability(mode)).map_err(map_error)
329    }
330
331    pub fn random_bytes(length: u32) -> Result<Vec<u8>, StorageError> {
332        wit::random_bytes(length).map_err(map_error)
333    }
334    pub fn monotonic_time_ns() -> Result<u64, StorageError> {
335        wit::monotonic_time_ns().map_err(map_error)
336    }
337    pub fn wall_time_ms() -> Result<u64, StorageError> {
338        wit::wall_time_ms().map_err(map_error)
339    }
340
341    fn map_durability(value: Durability) -> wit::Durability {
342        match value {
343            Durability::Data => wit::Durability::Data,
344            Durability::DataAndMetadata => wit::Durability::DataAndMetadata,
345            Durability::Full => wit::Durability::Full,
346        }
347    }
348    fn map_error(error: wit::StorageError) -> StorageError {
349        match error {
350            wit::StorageError::NotFound => StorageError::NotFound,
351            wit::StorageError::AlreadyExists => StorageError::AlreadyExists,
352            wit::StorageError::InvalidName => StorageError::InvalidName,
353            wit::StorageError::InvalidArgument => StorageError::InvalidArgument,
354            wit::StorageError::PermissionDenied => StorageError::PermissionDenied,
355            wit::StorageError::QuotaExceeded => StorageError::QuotaExceeded,
356            wit::StorageError::Busy => StorageError::Busy,
357            wit::StorageError::Timeout => StorageError::Timeout,
358            wit::StorageError::Unsupported => StorageError::Unsupported,
359            wit::StorageError::Corrupt => StorageError::Corrupt,
360            wit::StorageError::Io => StorageError::Io,
361        }
362    }
363
364    #[cfg(test)]
365    mod tests {
366        use super::{StorageError, map_error, wit};
367
368        #[test]
369        fn every_wit_error_maps_to_its_own_variant() {
370            let table = [
371                (wit::StorageError::NotFound, StorageError::NotFound),
372                (
373                    wit::StorageError::AlreadyExists,
374                    StorageError::AlreadyExists,
375                ),
376                (wit::StorageError::InvalidName, StorageError::InvalidName),
377                (
378                    wit::StorageError::InvalidArgument,
379                    StorageError::InvalidArgument,
380                ),
381                (
382                    wit::StorageError::PermissionDenied,
383                    StorageError::PermissionDenied,
384                ),
385                (
386                    wit::StorageError::QuotaExceeded,
387                    StorageError::QuotaExceeded,
388                ),
389                (wit::StorageError::Busy, StorageError::Busy),
390                (wit::StorageError::Timeout, StorageError::Timeout),
391                (wit::StorageError::Unsupported, StorageError::Unsupported),
392                (wit::StorageError::Corrupt, StorageError::Corrupt),
393                (wit::StorageError::Io, StorageError::Io),
394            ];
395            assert_eq!(table.len(), 11, "every WIT failure class must be covered");
396            for (wire, expected) in table {
397                assert_eq!(map_error(wire), expected, "{wire:?} must not be remapped");
398            }
399        }
400    }
401}