store-io 0.6.0

Durable storage I/O for Rust databases: evidence-based durability classes, unforgeable receipts, direct I/O, io_uring and IOCP.
Documentation
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
//! The simple API on the operating system's native backend.

use std::ops::Deref;
use std::path::Path;

use store_io_core::decide::{Trust, decide};
use store_io_core::error::{Error, ErrorContext, Named, NotWrittenCause, Op, OsError};
use store_io_platform::{FileName, LinuxTier, Platform};

use crate::{
    CopyOptions, CopyReport, FileSinkOptions, FileSourceOptions, ImportError, ImportOptions,
    ImportReport, ImportSource, NativePlatform, Probe, StoreOptions, StoreSinkOptions,
};

/// The native platform on the kernel interface `tier` asks for (D-082;
/// only Linux has a choice).
fn platform(tier: LinuxTier) -> Result<NativePlatform, Error> {
    #[cfg(target_os = "linux")]
    {
        NativePlatform::with_tier(tier).map_err(|raw| io(Op::Queue, raw))
    }
    #[cfg(not(target_os = "linux"))]
    {
        let _ = tier;
        Ok(NativePlatform::new())
    }
}

/// Paths accepted by the simple API.
fn path_of<P: AsRef<Path> + ?Sized>(p: &P) -> &Path {
    p.as_ref()
}

/// A region store-io appends to (see [`store_io_engine::AppendRegion`]).
pub type AppendRegion = store_io_engine::AppendRegion<NativePlatform>;
/// A region of caller-addressed blocks (see [`store_io_engine::PageRegion`]).
pub type PageRegion = store_io_engine::PageRegion<NativePlatform>;
/// A small object committed atomically (see [`store_io_engine::Slot`]).
pub type Slot = store_io_engine::Slot<NativePlatform>;
/// Many appends, one barrier (see [`store_io_engine::AppendBatch`]).
pub type AppendBatch = store_io_engine::AppendBatch<NativePlatform>;
/// Many page writes, one barrier (see [`store_io_engine::PageBatch`]).
pub type PageBatch = store_io_engine::PageBatch<NativePlatform>;
/// Space set aside for provisioning (see [`store_io_engine::Reservation`]).
pub type Reservation = store_io_engine::Reservation<NativePlatform>;
/// Many reads and writes in flight from one thread, without blocking (see
/// [`store_io_engine::Submitter`]); from [`Store::submitter`](store_io_engine::Store::submitter).
pub type Submitter = store_io_engine::Submitter<NativePlatform>;
/// Stores on several devices, made durable together (see
/// [`store_io_engine::StoreSet`]); built from [`Store`]s.
pub type StoreSet = store_io_engine::StoreSet<NativePlatform>;

/// A region's bytes in order as owned chunks (`read_stream` on a region).
pub type ReadStream = store_io_engine::ReadStream<NativePlatform>;

/// One range for `Store::prefetch` (`stream_range` on a region).
pub type StreamRange<'a> = store_io_engine::StreamRange<'a, NativePlatform>;

/// An export written to a directory ([`file_sink`]).
pub type FileSink = store_io_engine::FileSink<NativePlatform>;
/// An export read back from a directory ([`file_source`]).
pub type FileSource = store_io_engine::FileSource<NativePlatform>;
/// An export restored straight into a new store ([`store_sink`]).
pub type StoreSink = store_io_engine::StoreSink<NativePlatform>;

/// A store: one container file in a directory of its own, on one device.
///
/// Every method of [`store_io_engine::Store`] is available through `Deref`:
/// provisioning and looking up regions and slots, `reserve`, `space`,
/// `report`, `poison`.
///
/// ```no_run
/// use store_io::{Store, StoreOptions};
///
/// let store = Store::create("data/orders", StoreOptions::default())?;
/// println!("{}", store.report());
/// drop(store);
/// let store = Store::open("data/orders")?;
/// let wal = store.append_region("wal");
/// # let _ = wal;
/// # Ok::<(), store_io::Error>(())
/// ```
#[derive(Clone, Debug)]
pub struct Store(store_io_engine::Store<NativePlatform>);

impl Store {
    /// Creates a new store in `path` (the directory is created if needed).
    /// The device is probed first: unsafe or unverified devices are refused
    /// unless `opts.trust` attests or overrides (and then every receipt is
    /// labelled accordingly).
    ///
    /// # Errors
    ///
    /// `AlreadyExists`, `UnsafeDevice`, `Unverified`, `NoSpace`, `Io`.
    pub fn create(path: impl AsRef<Path>, opts: StoreOptions) -> Result<Self, Error> {
        store_io_engine::Store::create(platform(opts.linux_tier)?, path_of(&path), opts).map(Self)
    }

    /// Opens an existing store for writing, with default options. Takes the
    /// ownership lock, waits out a dead owner's writes, and verifies every
    /// region against its header. Append regions must be positioned with
    /// `resume_at` before the first append.
    ///
    /// # Errors
    ///
    /// `NotFound`, `Locked`, `UnsafeDevice`, `Unverified`, `Corruption`,
    /// `DurabilityUnknown` (a dead owner's writes could not be made
    /// durable), `Io`; `Unsupported(FormatVersion)` for a newer format and for a
    /// store of container format 1 (before 0.5), which opens read-only
    /// ([`Self::open_readonly`]) and moves to format 2 by [`copy_store`]
    /// (`store-io copy`).
    pub fn open(path: impl AsRef<Path>) -> Result<Self, Error> {
        Self::open_with(path, StoreOptions::default())
    }

    /// Opens an existing store for writing with explicit options.
    ///
    /// # Errors
    ///
    /// As [`Self::open`].
    pub fn open_with(path: impl AsRef<Path>, opts: StoreOptions) -> Result<Self, Error> {
        store_io_engine::Store::open(platform(opts.linux_tier)?, path_of(&path), opts).map(Self)
    }

    /// Opens an existing store for reading and recovery only: no write
    /// rights, and nothing on disk changes.
    ///
    /// # Errors
    ///
    /// `NotFound`, `Corruption`, `Io`.
    pub fn open_readonly(path: impl AsRef<Path>) -> Result<Self, Error> {
        Self::open_readonly_with(path, StoreOptions::default())
    }

    /// Opens an existing store for reading and recovery only, with
    /// explicit options (for example `linux_tier: LinuxTier::Sync`).
    ///
    /// # Errors
    ///
    /// As [`Self::open_readonly`].
    pub fn open_readonly_with(path: impl AsRef<Path>, opts: StoreOptions) -> Result<Self, Error> {
        store_io_engine::Store::open_readonly(platform(opts.linux_tier)?, path_of(&path), opts)
            .map(Self)
    }

    /// The engine store underneath.
    #[must_use]
    pub fn engine(&self) -> &store_io_engine::Store<NativePlatform> {
        &self.0
    }
}

impl Deref for Store {
    type Target = store_io_engine::Store<NativePlatform>;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

impl From<store_io_engine::Store<NativePlatform>> for Store {
    fn from(s: store_io_engine::Store<NativePlatform>) -> Self {
        Self(s)
    }
}

impl From<Store> for store_io_engine::Store<NativePlatform> {
    fn from(s: Store) -> Self {
        s.0
    }
}

/// A directory of small files, each replaced atomically and durably (see
/// [`store_io_engine::Directory`]).
///
/// ```no_run
/// use store_io::Directory;
///
/// let dir = Directory::open("data/meta", true)?;
/// dir.replace("CURRENT", b"MANIFEST-000042")?;
/// assert_eq!(dir.read("CURRENT")?, b"MANIFEST-000042");
/// # Ok::<(), store_io::Error>(())
/// ```
#[derive(Debug)]
pub struct Directory(store_io_engine::Directory<NativePlatform>);

impl Directory {
    /// Opens `path` (creating it if `create`), with default trust.
    ///
    /// # Errors
    ///
    /// `NotFound`, `Io`.
    pub fn open(path: impl AsRef<Path>, create: bool) -> Result<Self, Error> {
        Self::open_with(path, create, Trust::default())
    }

    /// Opens `path` with explicit trust inputs.
    ///
    /// # Errors
    ///
    /// As [`Self::open`].
    pub fn open_with(path: impl AsRef<Path>, create: bool, trust: Trust) -> Result<Self, Error> {
        store_io_engine::Directory::open(platform(LinuxTier::Auto)?, path_of(&path), create, trust)
            .map(Self)
    }

    /// The largest object a handle writes or reads by default (see
    /// [`Self::with_max_object`]): 16 MiB.
    pub const DEFAULT_MAX_OBJECT: u64 =
        store_io_engine::Directory::<NativePlatform>::DEFAULT_MAX_OBJECT;

    /// The handle with `max` as its largest object, written or read (see
    /// [`store_io_engine::Directory::with_max_object`]): a larger `replace`
    /// is refused before anything is written, and a larger file by `read`
    /// before anything is allocated.
    #[must_use]
    pub fn with_max_object(self, max: u64) -> Self {
        Self(self.0.with_max_object(max))
    }
}

impl Deref for Directory {
    type Target = store_io_engine::Directory<NativePlatform>;

    fn deref(&self) -> &Self::Target {
        &self.0
    }
}

fn io(op: Op, raw: OsError) -> Error {
    Error::Io {
        op,
        raw,
        ctx: ErrorContext::default(),
    }
}

/// Copies the store in `from` into a new store (container format 2) in
/// `to`, whose directory must hold no store: the way a format-1 store
/// moves to format 2, and the way to compact a format-2 one. The source is
/// opened read-only and never written; the copy is built under a temporary
/// name and renamed into place only when whole and durable, so after a
/// crash `to` holds nothing or the whole copy (run the copy again).
///
/// ```no_run
/// use store_io::CopyOptions;
///
/// let r = store_io::copy_store("data/orders", "data/orders-2", CopyOptions::default())?;
/// println!("{} regions, {} bytes", r.regions, r.bytes);
/// # Ok::<(), store_io::Error>(())
/// ```
///
/// # Errors
///
/// As [`store_io_engine::copy_store`], among them: `AlreadyExists` if `to`
/// holds a store; `Locked` while a writer holds `from` open or another
/// copy into `to` runs;
/// `NotWritten(NotReady | Frozen | TooLarge)` for a source it cannot copy
/// whole, before anything is created; `NotWritten(Misaligned)` if `to`'s
/// device needs larger blocks than the source's; `NotFound`, `Corruption`
/// or `Unsupported` opening the source; `UnsafeDevice`, `Unverified` (the
/// target's device refused: see `StoreOptions::trust`), `NoSpace`, `Io`;
/// `DurabilityUnknown` if the final rename or directory flush failed (the
/// copy may or may not be in place).
pub fn copy_store(
    from: impl AsRef<Path>,
    to: impl AsRef<Path>,
    opts: CopyOptions,
) -> Result<CopyReport, Error> {
    store_io_engine::copy_store(
        platform(opts.store.linux_tier)?,
        path_of(&from),
        path_of(&to),
        opts,
    )
}

/// A sink writing an export into the existing, empty directory `dir`: one
/// data file per region and a `regions.info` record, restorable only once
/// the export returned `Ok`.
///
/// ```no_run
/// let store = store_io::Store::open("data/orders")?;
/// let mut sink = store_io::file_sink("backup/orders", store_io::FileSinkOptions::default())?;
/// let report = store.export(&mut sink).map_err(|e| e.error)?;
/// assert!(report.complete);
/// # Ok::<(), store_io::Error>(())
/// ```
///
/// # Errors
///
/// As [`store_io_engine::FileSink::create`]: `NotFound` if `dir` does not
/// exist, `NotWritten(InvalidOptions)` if it is not empty, `Io`.
pub fn file_sink(dir: impl AsRef<Path>, opts: FileSinkOptions) -> Result<FileSink, Error> {
    store_io_engine::FileSink::create(platform(opts.store.linux_tier)?, path_of(&dir), opts)
}

/// A source reading back the export a [`file_sink`] wrote into `dir`, for
/// [`import`]: every span of every data file checked against its CRC-32C
/// before its bytes are handed out.
///
/// # Errors
///
/// As [`store_io_engine::FileSource::open`]: `NotFound` if `dir` does not
/// exist, `Corruption` if it holds no `regions.info`, `Io`.
pub fn file_source(dir: impl AsRef<Path>, opts: FileSourceOptions) -> Result<FileSource, Error> {
    store_io_engine::FileSource::open(platform(opts.store.linux_tier)?, path_of(&dir), opts)
}

/// Imports an export into a new store in `to`, whose directory must hold
/// no store: built under a temporary name and renamed into place only when
/// whole and durable, so after a crash `to` holds nothing or the whole
/// store (import again).
///
/// ```no_run
/// let mut source = store_io::file_source("backup/orders", Default::default())?;
/// let r = store_io::import(&mut source, "data/orders", store_io::ImportOptions::default())
///     .map_err(|e| e.error)?;
/// println!("{} regions, {} bytes", r.regions.len(), r.bytes);
/// # Ok::<(), store_io::Error>(())
/// ```
///
/// # Errors
///
/// As [`store_io_engine::import`] (boxed, with how far it got).
pub fn import(
    source: &mut dyn ImportSource,
    to: impl AsRef<Path>,
    opts: ImportOptions,
) -> Result<ImportReport, Box<ImportError>> {
    let p = platform(opts.store.linux_tier)
        .map_err(|error| Box::new(ImportError::from_error(error)))?;
    store_io_engine::import(p, path_of(&to), source, opts)
}

/// A sink restoring an export straight into a new store in `to`, whose
/// directory must hold no store (its copy lock held until the sink drops):
/// each region rebuilt as [`import`] rebuilds it, the store renamed into
/// place only once the export returned `Ok`, so after a crash `to` holds
/// nothing or the whole store.
///
/// ```no_run
/// let store = store_io::Store::open("data/orders")?;
/// let mut sink = store_io::store_sink("replica/orders", store_io::StoreSinkOptions::default())?;
/// let report = store.export(&mut sink).map_err(|e| e.error)?;
/// assert!(report.complete && sink.is_complete());
/// # Ok::<(), store_io::Error>(())
/// ```
///
/// # Errors
///
/// As [`store_io_engine::StoreSink::create`]: `AlreadyExists` if a store
/// is in `to`, `Locked` while another copy, import or sink into it runs,
/// `Io`.
pub fn store_sink(to: impl AsRef<Path>, opts: StoreSinkOptions) -> Result<StoreSink, Error> {
    store_io_engine::StoreSink::create(platform(opts.store.linux_tier)?, path_of(&to), opts)
}

/// Probes the device under the existing directory `dir`: the evidence
/// store-io reads and the durability class it would decide with default
/// trust. Creates, probes and removes a small temporary file there.
///
/// ```no_run
/// let p = store_io::probe("data")?;
/// println!("{:?}: {:?}", p.decision.class, p.decision.reasons);
/// # Ok::<(), store_io::Error>(())
/// ```
///
/// # Errors
///
/// `NotFound`, `Io`.
pub fn probe(dir: impl AsRef<Path>) -> Result<Probe, Error> {
    let p = NativePlatform::new();
    let d = p.open_dir(path_of(&dir), false).map_err(|raw| {
        if store_io_core::errno::is_not_found(raw) {
            Error::NotFound { what: Named::Store }
        } else {
            io(Op::Open, raw)
        }
    })?;
    // Unique per call (process, a counter and a random part, for processes
    // in different PID namespaces sharing a directory), so concurrent
    // probes of one directory never share, or remove, each other's file.
    static PROBES: std::sync::atomic::AtomicU64 = std::sync::atomic::AtomicU64::new(0);
    let n = PROBES.fetch_add(1, std::sync::atomic::Ordering::Relaxed);
    let salt = {
        use std::hash::{BuildHasher, Hasher};
        let mut h = std::collections::hash_map::RandomState::new().build_hasher();
        h.write_u64(n);
        h.finish()
    };
    let unique = format!(".store-io-probe-{}-{n}-{salt:016x}", std::process::id());
    let name = FileName::new(&unique).map_err(|_| Error::NotWritten {
        cause: NotWrittenCause::InvalidName,
        ctx: ErrorContext::default(),
    })?;
    let file = p
        .create_file(&d, &name)
        .map_err(|raw| io(Op::Create, raw))?;
    let evidence = p
        .allocate(&file, 4096)
        .and_then(|()| p.probe(&d, &file))
        .map_err(|raw| io(Op::Probe, raw));
    drop(file);
    let _removed = p.unlink(&d, &name);
    let evidence = evidence?;
    let decision = decide(&evidence, &Trust::default());
    Ok(Probe { evidence, decision })
}