1#![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 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 #[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}