Skip to main content

store_io_conformance/
lib.rs

1//! # store-io-conformance
2//!
3//! The checks every store-io platform backend must pass, on every file system
4//! it supports. A [`Suite`] runs each scenario in a fresh directory under a
5//! scratch root and returns a [`Report`] naming every scenario and what, if
6//! anything, went wrong; one failure never hides the others.
7//!
8//! Two kinds of scenario:
9//!
10//! - **The platform contract** (the `Platform` and `Queue` traits): exclusive
11//!   create and not-found mapping, sizes, many operations in flight completing
12//!   once each with their buffers, durable writes and flushes, queue limits,
13//!   read-only handles, rename and unlink, directory sync, the ownership lock,
14//!   range state after a full write, release, and the probe's honesty about
15//!   what it could not read.
16//! - **Store behaviour on that platform**: a round trip through a reopen, a
17//!   read-only open that changes nothing, ownership, and directory-mode
18//!   replace.
19//!
20//! The suite cannot cut power: crash behaviour is tested on the simulator
21//! (`store-io-sim`) and, for certification, on a power-cut rig.
22
23#![deny(warnings)]
24#![forbid(unsafe_code)]
25
26use std::fmt;
27use std::ops::ControlFlow;
28use std::path::{Path, PathBuf};
29use std::sync::atomic::{AtomicU32, Ordering};
30
31use store_io_buf::{BufPool, IoBuf, PoolConfig};
32use store_io_core::class::Missing;
33use store_io_core::decide::Trust;
34use store_io_core::errno::{is_already_exists, is_not_found};
35use store_io_core::error::{Error, OsError, OsErrorSource};
36use store_io_core::evidence::Tri;
37use store_io_engine::{CONTAINER, Directory, ScanItem, Store, StoreOptions};
38use store_io_platform::{
39    Completion, CompletionBuf, FileMode, FileName, IoOp, Owner, Platform, Queue, QueueConfig,
40    RawResult, ReleaseHow,
41};
42
43/// Bytes per block in the scenarios: a multiple of every direct-I/O
44/// alignment store-io supports.
45const BLOCK: usize = 4096;
46
47/// One scenario's outcome.
48#[derive(Debug, Clone, PartialEq, Eq)]
49pub struct Outcome {
50    /// The scenario's name.
51    pub name: &'static str,
52    /// `None` if it passed, else what went wrong.
53    pub failure: Option<String>,
54}
55
56/// The outcome of every scenario.
57#[derive(Debug, Clone, PartialEq, Eq, Default)]
58pub struct Report {
59    /// One entry per scenario, in run order.
60    pub outcomes: Vec<Outcome>,
61}
62
63impl Report {
64    /// Whether every scenario passed.
65    #[must_use]
66    pub fn passed(&self) -> bool {
67        self.outcomes.iter().all(|o| o.failure.is_none())
68    }
69}
70
71impl fmt::Display for Report {
72    fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
73        for o in &self.outcomes {
74            match &o.failure {
75                None => writeln!(f, "pass  {}", o.name)?,
76                Some(why) => writeln!(f, "FAIL  {}: {why}", o.name)?,
77            }
78        }
79        let failed = self.outcomes.iter().filter(|o| o.failure.is_some()).count();
80        write!(f, "{} scenarios, {failed} failed", self.outcomes.len())
81    }
82}
83
84/// A conformance run over one platform and one scratch directory.
85#[derive(Debug)]
86pub struct Suite<'a, P> {
87    platform: &'a P,
88    root: PathBuf,
89    trust: Trust,
90    owner: Owner,
91    parallel: bool,
92}
93
94/// What a scenario gets: the platform, a fresh directory, buffers, trust.
95struct Ctx<'a, P> {
96    p: &'a P,
97    path: PathBuf,
98    pool: BufPool,
99    trust: Trust,
100    /// Who uses the queues the scenarios make themselves.
101    owner: Owner,
102    /// Whether those queues are asked to run operations concurrently.
103    parallel: bool,
104}
105
106type Check = Result<(), String>;
107type Scenario<P> = (&'static str, fn(&Ctx<'_, P>) -> Check);
108
109/// Fails the scenario with a message unless `$cond` holds.
110macro_rules! check {
111    ($cond:expr, $($msg:tt)+) => {
112        if !$cond {
113            return Err(format!($($msg)+));
114        }
115    };
116}
117
118/// Unwraps a platform result or fails the scenario naming the step.
119fn ok<T>(r: RawResult<T>, step: &str) -> Result<T, String> {
120    r.map_err(|e| format!("{step}: {e}"))
121}
122
123/// Unwraps a store result or fails the scenario naming the step.
124fn done<T>(r: Result<T, Error>, step: &str) -> Result<T, String> {
125    r.map_err(|e| format!("{step}: {e}"))
126}
127
128fn name(s: &str) -> Result<FileName, String> {
129    FileName::new(s).map_err(|_| format!("invalid name {s:?}"))
130}
131
132mod parallel;
133mod submitter;
134mod wake;
135
136fn pattern(seed: u8, len: usize) -> Vec<u8> {
137    (0..len)
138        .map(|i| seed.wrapping_mul(31).wrapping_add((i * 7 + (i >> 9)) as u8))
139        .collect()
140}
141
142impl<'a, P> Suite<'a, P>
143where
144    P: Platform + Clone,
145    P::Queue: Send,
146{
147    /// A suite over `platform`, running each scenario in a fresh directory
148    /// under `root` (which must exist and should be empty). `trust` is used
149    /// for the store scenarios: pass an override only for devices that are
150    /// refused (virtual disks, `nobarrier` mounts), and say so in your
151    /// report.
152    pub fn new(platform: &'a P, root: impl AsRef<Path>, trust: Trust) -> Self {
153        Self {
154            platform,
155            root: root.as_ref().to_path_buf(),
156            trust,
157            owner: Owner::Shared,
158            parallel: false,
159        }
160    }
161
162    /// The suite with its own queues (those the queue scenarios make, not
163    /// the store's) set up for `owner` ([`QueueConfig::owner`]): with
164    /// [`Owner::Thread`], a backend that sets thread-owned queues up
165    /// differently (a thread-owned io_uring ring) is checked that way too.
166    /// Every scenario uses its queues on the thread that made them.
167    #[must_use]
168    pub fn owner(mut self, owner: Owner) -> Self {
169        self.owner = owner;
170        self
171    }
172
173    /// The suite with its own queues asked to run their operations
174    /// concurrently ([`QueueConfig::parallel`]): a backend that sets such
175    /// queues up differently (the Linux backend gives them io_uring rings on
176    /// its io_uring tier, and performs a lone-operation queue's operations
177    /// inline) is checked that way too.
178    #[must_use]
179    pub fn parallel(mut self, parallel: bool) -> Self {
180        self.parallel = parallel;
181        self
182    }
183
184    /// The scenarios, in run order.
185    fn scenarios() -> Vec<Scenario<P>> {
186        vec![
187            (
188                "create is exclusive and a missing file is not found",
189                create_is_exclusive,
190            ),
191            ("allocate only grows and set_len is exact", sizes),
192            (
193                "many operations in flight complete once each, with their buffers",
194                many_in_flight,
195            ),
196            (
197                "durable writes, data flushes and full flushes complete",
198                durable_and_flushes,
199            ),
200            (
201                "a full queue refuses with the buffer and no OS error",
202                queue_full,
203            ),
204            (
205                "a parallel queue completes every operation once, with its buffer",
206                parallel::many_in_flight,
207            ),
208            (
209                "a parallel queue makes durable writes and flushes",
210                parallel::durable_and_flushes,
211            ),
212            (
213                "a full parallel queue refuses with the buffer and no OS error",
214                parallel::queue_full,
215            ),
216            (
217                "a parallel queue dropped with operations in flight returns every buffer",
218                parallel::drop_in_flight,
219            ),
220            (
221                "a wake never creates, loses or repeats a completion",
222                wake::wake_keeps_every_completion,
223            ),
224            (
225                "a read-only handle reads and never writes",
226                read_only_handle,
227            ),
228            (
229                "rename replaces, unlink removes, the directory syncs",
230                rename_unlink_sync,
231            ),
232            (
233                "a no-replace rename refuses an existing name and renames to a free one",
234                rename_noreplace,
235            ),
236            (
237                "the ownership lock admits one holder at a time",
238                ownership_lock,
239            ),
240            ("the monotonic clock never goes back", monotonic_clock),
241            (
242                "readers share the lock on read-only handles and exclude the owner",
243                shared_lock,
244            ),
245            (
246                "a fully written range is allocated, unshared and uncached",
247                written_range_state,
248            ),
249            ("a released range keeps the file's size", release_keeps_size),
250            (
251                "allocate_range allocates inside the file and keeps its size and bytes",
252                allocate_range_keeps_size,
253            ),
254            (
255                "the probe reports alignment and lists what it could not read",
256                probe_is_honest,
257            ),
258            ("a store round-trips through a reopen", store_round_trip),
259            (
260                "a submitter's writes, barrier and reads complete once each and round-trip",
261                submitter::submitter_round_trip,
262            ),
263            (
264                "a read-only open changes nothing",
265                read_only_open_changes_nothing,
266            ),
267            ("a second writable open is refused", second_open_is_locked),
268            (
269                "a directory replace round-trips with exact bytes",
270                directory_replace,
271            ),
272        ]
273    }
274
275    /// The scenario names, in run order.
276    #[must_use]
277    pub fn names() -> Vec<&'static str> {
278        Self::scenarios().into_iter().map(|(n, _)| n).collect()
279    }
280
281    /// Runs every scenario.
282    #[must_use]
283    pub fn run(&self) -> Report {
284        static RUN: AtomicU32 = AtomicU32::new(0);
285        let run = RUN.fetch_add(1, Ordering::Relaxed);
286        let outcomes = Self::scenarios()
287            .into_iter()
288            .enumerate()
289            .map(|(i, (name, scenario))| {
290                let path = self
291                    .root
292                    .join(format!("sio-conf-{}-{run}-{i:02}", std::process::id()));
293                let failure = match BufPool::new(&PoolConfig::uniform(BLOCK, BLOCK, 1 << 17, 16)) {
294                    Ok(pool) => scenario(&Ctx {
295                        p: self.platform,
296                        path,
297                        pool,
298                        trust: self.trust,
299                        owner: self.owner,
300                        parallel: self.parallel,
301                    })
302                    .err(),
303                    Err(e) => Some(format!("buffer pool: {e:?}")),
304                };
305                Outcome { name, failure }
306            })
307            .collect();
308        Report { outcomes }
309    }
310}
311
312impl<P: Platform> Ctx<'_, P> {
313    fn dir(&self) -> Result<P::Dir, String> {
314        ok(self.p.open_dir(&self.path, true), "open_dir")
315    }
316
317    fn queue(&self, depth: u32) -> Result<P::Queue, String> {
318        ok(
319            self.p.queue(QueueConfig {
320                depth,
321                owner: self.owner,
322                parallel: self.parallel,
323                ..QueueConfig::default()
324            }),
325            "queue",
326        )
327    }
328
329    fn buf(&self, bytes: &[u8]) -> Result<IoBuf, String> {
330        let mut b = self
331            .pool
332            .take(bytes.len())
333            .map_err(|_| "buffer pool exhausted".to_owned())?;
334        b.as_mut_slice().copy_from_slice(bytes);
335        Ok(b)
336    }
337
338    /// A new file of `len` bytes, allocated.
339    fn file(&self, dir: &P::Dir, file: &str, len: u64) -> Result<P::File, String> {
340        let f = ok(self.p.create_file(dir, &name(file)?), "create_file")?;
341        ok(self.p.allocate(&f, len), "allocate")?;
342        Ok(f)
343    }
344}
345
346/// Waits for `n` completions.
347fn drain<Q: Queue>(q: &mut Q, n: usize) -> Result<Vec<Completion>, String> {
348    let mut out = CompletionBuf::with_capacity(n.max(1));
349    let mut got = Vec::new();
350    while got.len() < n {
351        let _added = ok(q.wait(1, &mut out), "wait")?;
352        got.extend(out.drain());
353    }
354    Ok(got)
355}
356
357fn write_one<Q: Queue>(
358    q: &mut Q,
359    file: &Q::File,
360    offset: u64,
361    buf: IoBuf,
362    dsync: bool,
363) -> Result<RawResult<usize>, String> {
364    q.submit(
365        IoOp::Write {
366            file,
367            offset,
368            buf,
369            dsync,
370        },
371        offset,
372    )
373    .map_err(|r| format!("write at {offset} refused: {:?}", r.raw))?;
374    let c = drain(q, 1)?.pop().ok_or("no completion")?;
375    Ok(c.result)
376}
377
378fn read_one<Q: Queue>(
379    q: &mut Q,
380    file: &Q::File,
381    offset: u64,
382    buf: IoBuf,
383) -> Result<(RawResult<usize>, Option<IoBuf>), String> {
384    q.submit(IoOp::Read { file, offset, buf }, offset)
385        .map_err(|r| format!("read at {offset} refused: {:?}", r.raw))?;
386    let c = drain(q, 1)?.pop().ok_or("no completion")?;
387    Ok((c.result, c.buf))
388}
389
390// ---------------------------------------------------------------------------
391// The platform contract
392// ---------------------------------------------------------------------------
393
394fn create_is_exclusive<P: Platform>(c: &Ctx<'_, P>) -> Check {
395    let dir = c.dir()?;
396    let _a = c.file(&dir, "a", BLOCK as u64)?;
397    match c.p.create_file(&dir, &name("a")?) {
398        Ok(_) => return Err("a second create of the same name succeeded".into()),
399        Err(e) => check!(
400            is_already_exists(e),
401            "second create: {e} is not 'already exists'"
402        ),
403    }
404    match c.p.open_file(&dir, &name("missing")?, FileMode::ReadOnly) {
405        Ok(_) => Err("opening a missing file succeeded".into()),
406        Err(e) => {
407            check!(is_not_found(e), "missing file: {e} is not 'not found'");
408            Ok(())
409        }
410    }
411}
412
413fn sizes<P: Platform>(c: &Ctx<'_, P>) -> Check {
414    let dir = c.dir()?;
415    let f = c.file(&dir, "s", 16 * BLOCK as u64)?;
416    check!(
417        ok(c.p.size(&f), "size")? == 16 * BLOCK as u64,
418        "allocate did not set the size"
419    );
420    ok(c.p.allocate(&f, BLOCK as u64), "allocate smaller")?;
421    let after = ok(c.p.size(&f), "size")?;
422    check!(
423        after == 16 * BLOCK as u64,
424        "allocate shrank the file to {after}"
425    );
426    ok(c.p.set_len(&f, 100), "set_len 100")?;
427    check!(ok(c.p.size(&f), "size")? == 100, "set_len did not truncate");
428    ok(c.p.set_len(&f, 3 * BLOCK as u64), "set_len grow")?;
429    check!(
430        ok(c.p.size(&f), "size")? == 3 * BLOCK as u64,
431        "set_len did not extend"
432    );
433    Ok(())
434}
435
436fn many_in_flight<P: Platform>(c: &Ctx<'_, P>) -> Check {
437    many_in_flight_on(c, c.queue(16)?)
438}
439
440/// Sixteen writes of mixed sizes in flight on `q` (depth at least 16), each
441/// completing once with its buffer, then read back.
442fn many_in_flight_on<P: Platform>(c: &Ctx<'_, P>, mut q: P::Queue) -> Check {
443    let dir = c.dir()?;
444    let f = c.file(&dir, "m", 1 << 20)?;
445    let mut expect = Vec::new();
446    let mut at = 0u64;
447    for i in 0..16u8 {
448        let len = BLOCK * (1 + usize::from(i % 4));
449        let bytes = pattern(i, len);
450        let buf = c.buf(&bytes)?;
451        q.submit(
452            IoOp::Write {
453                file: &f,
454                offset: at,
455                buf,
456                dsync: false,
457            },
458            u64::from(i),
459        )
460        .map_err(|r| format!("write {i} refused: {:?}", r.raw))?;
461        expect.push((at, bytes));
462        at += len as u64;
463    }
464    let mut seen = [false; 16];
465    for comp in drain(&mut q, 16)? {
466        let i = usize::try_from(comp.tag).unwrap_or(usize::MAX);
467        check!(
468            i < 16 && !seen[i],
469            "completion tag {} unknown or repeated",
470            comp.tag
471        );
472        seen[i] = true;
473        let len = expect[i].1.len();
474        check!(
475            comp.result == Ok(len),
476            "write {i}: {:?}, want {len}",
477            comp.result
478        );
479        check!(
480            comp.buf.as_ref().is_some_and(|b| b.len() == len),
481            "write {i} did not return its buffer"
482        );
483    }
484    for (i, (at, bytes)) in expect.iter().enumerate() {
485        let buf = c.buf(&vec![0; bytes.len()])?;
486        let (r, back) = read_one(&mut q, &f, *at, buf)?;
487        check!(r == Ok(bytes.len()), "read {i}: {r:?}");
488        check!(
489            back.is_some_and(|b| b.as_slice() == bytes.as_slice()),
490            "read {i} returned other bytes"
491        );
492    }
493    Ok(())
494}
495
496fn durable_and_flushes<P: Platform>(c: &Ctx<'_, P>) -> Check {
497    durable_and_flushes_on(c, c.queue(4)?)
498}
499
500fn durable_and_flushes_on<P: Platform>(c: &Ctx<'_, P>, mut q: P::Queue) -> Check {
501    let dir = c.dir()?;
502    let f = c.file(&dir, "d", 4 * BLOCK as u64)?;
503    let r = write_one(&mut q, &f, 0, c.buf(&pattern(1, BLOCK))?, true)?;
504    check!(r == Ok(BLOCK), "durable write: {r:?}");
505    q.submit(IoOp::FlushData { file: &f }, 7)
506        .map_err(|r| format!("data flush refused: {:?}", r.raw))?;
507    let comp = drain(&mut q, 1)?.pop().ok_or("no flush completion")?;
508    check!(
509        comp.tag == 7 && comp.result.is_ok(),
510        "data flush: {:?}",
511        comp.result
512    );
513    check!(comp.buf.is_none(), "a flush completion carried a buffer");
514    ok(c.p.flush_all(&f), "flush_all")
515}
516
517fn queue_full<P: Platform>(c: &Ctx<'_, P>) -> Check {
518    queue_full_on(c, c.queue(2)?)
519}
520
521/// `q` has depth 2.
522fn queue_full_on<P: Platform>(c: &Ctx<'_, P>, mut q: P::Queue) -> Check {
523    let dir = c.dir()?;
524    let f = c.file(&dir, "q", 4 * BLOCK as u64)?;
525    for i in 0..2u64 {
526        let buf = c.buf(&pattern(2, BLOCK))?;
527        q.submit(
528            IoOp::Write {
529                file: &f,
530                offset: i * BLOCK as u64,
531                buf,
532                dsync: false,
533            },
534            i,
535        )
536        .map_err(|r| format!("write {i} refused: {:?}", r.raw))?;
537    }
538    let third = q.submit(
539        IoOp::Write {
540            file: &f,
541            offset: 2 * BLOCK as u64,
542            buf: c.buf(&pattern(3, BLOCK))?,
543            dsync: false,
544        },
545        2,
546    );
547    match third {
548        Ok(()) => return Err("a third operation on a queue of depth 2 was accepted".into()),
549        Err(r) => {
550            check!(
551                r.raw.is_none(),
552                "a full queue reported an OS error {:?}",
553                r.raw
554            );
555            check!(
556                r.buf.is_some_and(|b| b.len() == BLOCK),
557                "the refused buffer was not returned"
558            );
559        }
560    }
561    let _two = drain(&mut q, 2)?;
562    check!(
563        q.in_flight() == 0,
564        "operations left in flight after draining"
565    );
566    Ok(())
567}
568
569fn read_only_handle<P: Platform>(c: &Ctx<'_, P>) -> Check {
570    let dir = c.dir()?;
571    let w = c.file(&dir, "r", 4 * BLOCK as u64)?;
572    let mut q = c.queue(4)?;
573    let _written = write_one(&mut q, &w, 0, c.buf(&pattern(4, BLOCK))?, false)?;
574    ok(c.p.flush_all(&w), "flush_all")?;
575    let r = ok(
576        c.p.open_file(&dir, &name("r")?, FileMode::ReadOnly),
577        "open read-only",
578    )?;
579    let (got, back) = read_one(&mut q, &r, 0, c.buf(&[0; BLOCK])?)?;
580    check!(got == Ok(BLOCK), "read-only read: {got:?}");
581    check!(
582        back.is_some_and(|b| b.as_slice() == pattern(4, BLOCK).as_slice()),
583        "read-only read returned other bytes"
584    );
585    let attempt = q.submit(
586        IoOp::Write {
587            file: &r,
588            offset: 0,
589            buf: c.buf(&pattern(5, BLOCK))?,
590            dsync: false,
591        },
592        9,
593    );
594    if attempt.is_ok() {
595        let comp = drain(&mut q, 1)?.pop().ok_or("no completion")?;
596        check!(
597            comp.result.is_err(),
598            "a write through a read-only handle succeeded"
599        );
600    }
601    check!(
602        c.p.allocate(&r, 64 * BLOCK as u64).is_err(),
603        "allocate through a read-only handle succeeded"
604    );
605    check!(
606        c.p.set_len(&r, 0).is_err(),
607        "set_len through a read-only handle succeeded"
608    );
609    let (again, back) = read_one(&mut q, &r, 0, c.buf(&[0; BLOCK])?)?;
610    check!(
611        again == Ok(BLOCK) && back.is_some_and(|b| b.as_slice() == pattern(4, BLOCK).as_slice()),
612        "the file changed through a read-only handle"
613    );
614    Ok(())
615}
616
617fn rename_unlink_sync<P: Platform>(c: &Ctx<'_, P>) -> Check {
618    let dir = c.dir()?;
619    let mut q = c.queue(4)?;
620    let a = c.file(&dir, "a", BLOCK as u64)?;
621    let b = c.file(&dir, "b", BLOCK as u64)?;
622    let _x = write_one(&mut q, &a, 0, c.buf(&pattern(6, BLOCK))?, false)?;
623    let _y = write_one(&mut q, &b, 0, c.buf(&pattern(7, BLOCK))?, false)?;
624    ok(c.p.flush_all(&a), "flush a")?;
625    ok(c.p.flush_all(&b), "flush b")?;
626    ok(
627        c.p.rename_replace(&dir, &name("a")?, &name("b")?, &a),
628        "rename_replace",
629    )?;
630    ok(c.p.sync_dir(&dir), "sync_dir")?;
631    drop((a, b));
632    let now_b = ok(
633        c.p.open_file(&dir, &name("b")?, FileMode::ReadOnly),
634        "open b",
635    )?;
636    let (r, back) = read_one(&mut q, &now_b, 0, c.buf(&[0; BLOCK])?)?;
637    check!(
638        r == Ok(BLOCK) && back.is_some_and(|x| x.as_slice() == pattern(6, BLOCK).as_slice()),
639        "the target does not hold the renamed file's bytes"
640    );
641    match c.p.open_file(&dir, &name("a")?, FileMode::ReadOnly) {
642        Ok(_) => return Err("the renamed name still exists".into()),
643        Err(e) => check!(is_not_found(e), "old name: {e}"),
644    }
645    drop(now_b);
646    ok(c.p.unlink(&dir, &name("b")?), "unlink")?;
647    ok(c.p.sync_dir(&dir), "sync_dir after unlink")?;
648    match c.p.open_file(&dir, &name("b")?, FileMode::ReadOnly) {
649        Ok(_) => Err("an unlinked file still opens".into()),
650        Err(e) => {
651            check!(is_not_found(e), "unlinked: {e}");
652            Ok(())
653        }
654    }
655}
656
657fn rename_noreplace<P: Platform>(c: &Ctx<'_, P>) -> Check {
658    let dir = c.dir()?;
659    let mut q = c.queue(4)?;
660    let a = c.file(&dir, "a", BLOCK as u64)?;
661    let b = c.file(&dir, "b", BLOCK as u64)?;
662    let _x = write_one(&mut q, &a, 0, c.buf(&pattern(8, BLOCK))?, false)?;
663    let _y = write_one(&mut q, &b, 0, c.buf(&pattern(9, BLOCK))?, false)?;
664    ok(c.p.flush_all(&a), "flush a")?;
665    ok(c.p.flush_all(&b), "flush b")?;
666    // Onto an existing name: refused, both files as they were.
667    match c.p.rename_noreplace(&dir, &name("a")?, &name("b")?, &a) {
668        Ok(()) => return Err("a no-replace rename replaced a file".into()),
669        Err(e) => check!(is_already_exists(e), "onto an existing name: {e}"),
670    }
671    drop(b);
672    let still_b = ok(
673        c.p.open_file(&dir, &name("b")?, FileMode::ReadOnly),
674        "open b",
675    )?;
676    let (r, back) = read_one(&mut q, &still_b, 0, c.buf(&[0; BLOCK])?)?;
677    check!(
678        r == Ok(BLOCK) && back.is_some_and(|x| x.as_slice() == pattern(9, BLOCK).as_slice()),
679        "the existing file changed"
680    );
681    drop(still_b);
682    // Onto a free name: renamed.
683    ok(
684        c.p.rename_noreplace(&dir, &name("a")?, &name("c")?, &a),
685        "rename_noreplace",
686    )?;
687    ok(c.p.sync_dir(&dir), "sync_dir")?;
688    drop(a);
689    let now_c = ok(
690        c.p.open_file(&dir, &name("c")?, FileMode::ReadOnly),
691        "open c",
692    )?;
693    let (r, back) = read_one(&mut q, &now_c, 0, c.buf(&[0; BLOCK])?)?;
694    check!(
695        r == Ok(BLOCK) && back.is_some_and(|x| x.as_slice() == pattern(8, BLOCK).as_slice()),
696        "the new name does not hold the renamed file's bytes"
697    );
698    drop(now_c);
699    match c.p.open_file(&dir, &name("a")?, FileMode::ReadOnly) {
700        Ok(_) => Err("the renamed name still exists".into()),
701        Err(e) => {
702            check!(is_not_found(e), "old name: {e}");
703            Ok(())
704        }
705    }
706}
707
708fn monotonic_clock<P: Platform>(c: &Ctx<'_, P>) -> Check {
709    let mut last = c.p.monotonic_ms();
710    for _ in 0..10_000 {
711        let now = c.p.monotonic_ms();
712        check!(now >= last, "the clock went back: {last} then {now}");
713        last = now;
714    }
715    Ok(())
716}
717
718fn ownership_lock<P: Platform>(c: &Ctx<'_, P>) -> Check {
719    let dir = c.dir()?;
720    let f = c.file(&dir, "l", BLOCK as u64)?;
721    let held = ok(c.p.lock_exclusive(&f), "first lock")?;
722    let other = ok(
723        c.p.open_file(&dir, &name("l")?, FileMode::ReadWrite),
724        "second open",
725    )?;
726    check!(
727        c.p.lock_exclusive(&other).is_err(),
728        "a second holder took the lock"
729    );
730    drop(held);
731    drop(f);
732    ok(c.p.lock_exclusive(&other), "lock after release").map(|_| ())
733}
734
735fn shared_lock<P: Platform>(c: &Ctx<'_, P>) -> Check {
736    let dir = c.dir()?;
737    let f = c.file(&dir, "s", BLOCK as u64)?;
738    let reader = |what: &str| ok(c.p.open_file(&dir, &name("s")?, FileMode::ReadOnly), what);
739    let r1 = reader("first read-only open")?;
740    let r2 = reader("second read-only open")?;
741    let s1 = ok(c.p.lock_shared(&r1), "shared lock on a read-only handle")?;
742    let s2 = ok(c.p.lock_shared(&r2), "a second shared holder")?;
743    check!(
744        c.p.lock_exclusive(&f).is_err(),
745        "the owner's lock was taken while readers held theirs"
746    );
747    // Releasing one reader leaves the other: the owner is still excluded.
748    drop(s1);
749    check!(
750        c.p.lock_exclusive(&f).is_err(),
751        "the owner's lock was taken while one reader still held its lock"
752    );
753    drop(s2);
754    let owner = ok(
755        c.p.lock_exclusive(&f),
756        "the owner's lock after the readers left",
757    )?;
758    check!(
759        c.p.lock_shared(&r1).is_err(),
760        "a reader's lock was taken while the owner held its lock"
761    );
762    drop(owner);
763    ok(c.p.lock_shared(&r1), "a shared lock after the owner left").map(|_| ())
764}
765
766fn written_range_state<P: Platform>(c: &Ctx<'_, P>) -> Check {
767    let dir = c.dir()?;
768    let len = 16 * BLOCK;
769    let f = c.file(&dir, "w", len as u64)?;
770    let mut q = c.queue(4)?;
771    let r = write_one(&mut q, &f, 0, c.buf(&pattern(8, len))?, false)?;
772    check!(r == Ok(len), "full write: {r:?}");
773    ok(c.p.flush_all(&f), "flush_all")?;
774    let s = ok(c.p.range_state(&f, 0, len as u64), "range_state")?;
775    check!(
776        s.unwritten != Tri::Yes,
777        "a written range reports unwritten extents"
778    );
779    check!(s.shared != Tri::Yes, "a fresh file reports shared extents");
780    check!(
781        s.cached_pages.is_none_or(|n| n == 0),
782        "direct writes left {:?} cached pages",
783        s.cached_pages
784    );
785    check!(
786        s.valid_data != Tri::No,
787        "the valid data length does not cover a written range"
788    );
789    Ok(())
790}
791
792fn release_keeps_size<P: Platform>(c: &Ctx<'_, P>) -> Check {
793    let dir = c.dir()?;
794    let len = 32 * BLOCK as u64;
795    let f = c.file(&dir, "x", len)?;
796    let mut q = c.queue(4)?;
797    let _w = write_one(&mut q, &f, 0, c.buf(&pattern(9, 32 * BLOCK))?, false)?;
798    ok(c.p.flush_all(&f), "flush_all")?;
799    ok(
800        c.p.release_range(
801            &f,
802            8 * BLOCK as u64,
803            8 * BLOCK as u64,
804            ReleaseHow::Deallocate,
805        ),
806        "release",
807    )?;
808    check!(
809        ok(c.p.size(&f), "size")? == len,
810        "release changed the file size"
811    );
812    let (r, back) = read_one(&mut q, &f, 0, c.buf(&[0; BLOCK])?)?;
813    check!(
814        r == Ok(BLOCK) && back.is_some_and(|b| b.as_slice() == &pattern(9, 32 * BLOCK)[..BLOCK]),
815        "release changed bytes outside its range"
816    );
817    Ok(())
818}
819
820fn allocate_range_keeps_size<P: Platform>(c: &Ctx<'_, P>) -> Check {
821    let dir = c.dir()?;
822    let len = 32 * BLOCK as u64;
823    let f = c.file(&dir, "a", len)?;
824    let mut q = c.queue(4)?;
825    let _w = write_one(&mut q, &f, 0, c.buf(&pattern(5, 32 * BLOCK))?, false)?;
826    ok(c.p.flush_all(&f), "flush_all")?;
827    // macOS cannot allocate inside a file and says so; the rest of the
828    // contract still holds there. Elsewhere the file systems the suite runs
829    // on can.
830    match c.p.allocate_range(&f, 8 * BLOCK as u64, 8 * BLOCK as u64) {
831        Err(e) if cannot_allocate_inside(e) => {}
832        r => ok(r, "allocate_range")?,
833    }
834    check!(
835        ok(c.p.size(&f), "size")? == len,
836        "allocate_range changed the file size"
837    );
838    let (r, back) = read_one(&mut q, &f, 8 * BLOCK as u64, c.buf(&[0; BLOCK])?)?;
839    check!(
840        r == Ok(BLOCK)
841            && back.is_some_and(|b| b.as_slice() == &pattern(5, 32 * BLOCK)[8 * BLOCK..9 * BLOCK]),
842        "allocate_range changed written bytes"
843    );
844    check!(
845        c.p.allocate_range(&f, len - BLOCK as u64, 2 * BLOCK as u64)
846            .is_err(),
847        "allocate_range past the end succeeded"
848    );
849    check!(
850        ok(c.p.size(&f), "size")? == len,
851        "allocate_range past the end grew the file"
852    );
853    ok(
854        c.p.allocate_range(&f, len, 0),
855        "allocate_range of 0 at the end",
856    )?;
857    let r = ok(
858        c.p.open_file(&dir, &name("a")?, FileMode::ReadOnly),
859        "open read-only",
860    )?;
861    check!(
862        c.p.allocate_range(&r, 0, BLOCK as u64).is_err(),
863        "allocate_range on a read-only handle succeeded"
864    );
865    Ok(())
866}
867
868/// Whether `raw` is macOS's `ENOTSUP` (45) for an allocation inside a file,
869/// which it never makes. Nowhere else is a refusal accepted.
870fn cannot_allocate_inside(raw: OsError) -> bool {
871    cfg!(target_vendor = "apple") && raw.source == OsErrorSource::Errno && raw.code == 45
872}
873
874fn probe_is_honest<P: Platform>(c: &Ctx<'_, P>) -> Check {
875    let dir = c.dir()?;
876    let f = c.file(&dir, "p", BLOCK as u64)?;
877    let ev = ok(c.p.probe(&dir, &f), "probe")?;
878    let a = ev.fs.dio_offset_align;
879    let m = ev.fs.dio_mem_align;
880    if ev.missing.contains(Missing::DioAlignment) || ev.fs.direct_io == Tri::No {
881        // Not reported (Linux before 6.1 has no STATX_DIOALIGN), or no direct
882        // I/O on this file (ext4 data=journal): unknown, never a guess; the
883        // engine then works in whole blocks.
884        check!(
885            a == 0 && m == 0,
886            "unread direct-I/O alignment given as {a} / {m}"
887        );
888    } else {
889        check!(
890            a.is_power_of_two() && a as usize <= BLOCK,
891            "direct-I/O offset alignment {a}"
892        );
893        check!(
894            m.is_power_of_two() && m as usize <= BLOCK,
895            "direct-I/O memory alignment {m}"
896        );
897    }
898    if ev.device.cache_present == Tri::Unknown {
899        check!(
900            ev.missing.contains(Missing::CachePresence),
901            "an unknown write cache is not listed as missing"
902        );
903    }
904    Ok(())
905}
906
907// ---------------------------------------------------------------------------
908// Store behaviour on the platform
909// ---------------------------------------------------------------------------
910
911fn opts(trust: Trust) -> StoreOptions {
912    StoreOptions {
913        trust,
914        queues: 2,
915        buffers_per_class: 16,
916        max_io: 1 << 17,
917        ..StoreOptions::default()
918    }
919}
920
921fn store_round_trip<P: Platform + Clone>(c: &Ctx<'_, P>) -> Check
922where
923    P::Queue: Send,
924{
925    let s = done(Store::create(c.p.clone(), &c.path, opts(c.trust)), "create")?;
926    let wal = done(s.provision_append_region("wal", 4 << 20), "provision wal")?;
927    let big = pattern(10, 600_000);
928    let (pos, receipt) = done(wal.append_durable(&big), "append")?;
929    check!(
930        receipt.durable_through() >= pos.offset() + big.len() as u64,
931        "receipt short"
932    );
933    let mut batch = wal.batch();
934    for i in 0..50u8 {
935        let _at = done(batch.append(&pattern(i, 100)), "batch append")?;
936    }
937    let (bpos, _r) = done(batch.commit(), "batch commit")?;
938    let pages = done(s.provision_page_region("pages", 1 << 20), "provision pages")?;
939    let _p = done(
940        pages.write_durable(
941            done(pages.pos(4 * BLOCK as u64), "pos")?,
942            &pattern(11, BLOCK),
943        ),
944        "page write",
945    )?;
946    let slot = done(s.provision_slot("manifest"), "provision slot")?;
947    let _c = done(slot.commit(b"v1"), "slot commit")?;
948    drop((batch, wal, pages, slot, s));
949    let s = done(Store::open(c.p.clone(), &c.path, opts(c.trust)), "reopen")?;
950    let wal = done(s.append_region("wal"), "wal lookup")?;
951    let mut back = vec![0; big.len()];
952    let _n = done(wal.read(pos.offset(), &mut back), "read")?;
953    check!(back == big, "append did not round-trip");
954    let mut first = vec![0; 100];
955    let _n = done(wal.read(bpos.offset(), &mut first), "read batch")?;
956    check!(first == pattern(0, 100), "batch did not round-trip");
957    check!(
958        done(s.slot("manifest"), "slot lookup")?.read().as_deref() == Some(b"v1".as_slice()),
959        "slot did not round-trip"
960    );
961    let pages = done(s.page_region("pages"), "pages lookup")?;
962    let mut page = vec![0; BLOCK];
963    let _n = done(
964        pages.read(done(pages.pos(4 * BLOCK as u64), "pos")?, &mut page),
965        "page read",
966    )?;
967    check!(page == pattern(11, BLOCK), "page did not round-trip");
968    check!(
969        wal.append(b"x").is_err(),
970        "a reopened append region accepted an unpositioned append"
971    );
972    let _at = done(wal.resume_at(bpos.offset() + 50 * 100), "resume_at")?;
973    let _t = done(wal.append_durable(b"after"), "append after resume")?;
974    Ok(())
975}
976
977/// Every byte of the container, read through the platform.
978fn container_bytes<P: Platform>(c: &Ctx<'_, P>) -> Result<Vec<u8>, String> {
979    let dir = c.dir()?;
980    let f = ok(
981        c.p.open_file(&dir, &name(CONTAINER)?, FileMode::ReadOnly),
982        "open container",
983    )?;
984    let len = usize::try_from(ok(c.p.size(&f), "size")?).map_err(|_| "container too large")?;
985    let mut q = c.queue(2)?;
986    let mut out = Vec::with_capacity(len);
987    let chunk = 1 << 16;
988    while out.len() < len {
989        let want = (len - out.len()).min(chunk);
990        let padded = want.div_ceil(BLOCK) * BLOCK;
991        let (r, back) = read_one(&mut q, &f, out.len() as u64, c.buf(&vec![0; padded])?)?;
992        let n = ok(r, "read container")?.min(want);
993        let b = back.ok_or("no buffer")?;
994        out.extend_from_slice(&b.as_slice()[..n]);
995        check!(n > 0, "short read of the container at {}", out.len());
996    }
997    Ok(out)
998}
999
1000fn read_only_open_changes_nothing<P: Platform + Clone>(c: &Ctx<'_, P>) -> Check
1001where
1002    P::Queue: Send,
1003{
1004    let s = done(Store::create(c.p.clone(), &c.path, opts(c.trust)), "create")?;
1005    let wal = done(s.provision_append_region("wal", 1 << 20), "provision")?;
1006    let _r = done(wal.append_durable(&pattern(12, 70_000)), "append")?;
1007    drop((wal, s));
1008    let before = container_bytes(c)?;
1009    let ro = done(
1010        Store::open_readonly(c.p.clone(), &c.path, opts(c.trust)),
1011        "open_readonly",
1012    )?;
1013    let wal = done(ro.append_region("wal"), "lookup")?;
1014    let _s = done(
1015        wal.scan(0, |_: ScanItem<'_>| ControlFlow::Continue(())),
1016        "scan",
1017    )?;
1018    check!(
1019        wal.append(b"x").is_err(),
1020        "a read-only store accepted an append"
1021    );
1022    drop((wal, ro));
1023    let after = container_bytes(c)?;
1024    check!(
1025        before.len() == after.len(),
1026        "a read-only open changed the size"
1027    );
1028    check!(before == after, "a read-only open changed the bytes");
1029    Ok(())
1030}
1031
1032fn second_open_is_locked<P: Platform + Clone>(c: &Ctx<'_, P>) -> Check
1033where
1034    P::Queue: Send,
1035{
1036    let s = done(Store::create(c.p.clone(), &c.path, opts(c.trust)), "create")?;
1037    match Store::open(c.p.clone(), &c.path, opts(c.trust)) {
1038        Ok(_) => return Err("a second writable open succeeded".into()),
1039        Err(e) => check!(matches!(e, Error::Locked), "second open: {e}"),
1040    }
1041    drop(s);
1042    done(
1043        Store::open(c.p.clone(), &c.path, opts(c.trust)),
1044        "open after close",
1045    )
1046    .map(|_| ())
1047}
1048
1049fn directory_replace<P: Platform + Clone>(c: &Ctx<'_, P>) -> Check {
1050    let d = done(Directory::open(c.p.clone(), &c.path, true, c.trust), "open")?;
1051    for (i, len) in [0usize, 1, 4095, 4096, 70_000].into_iter().enumerate() {
1052        let bytes = pattern(i as u8, len);
1053        done(d.replace("CURRENT", &bytes), "replace")?;
1054        check!(
1055            done(d.read("CURRENT"), "read")? == bytes,
1056            "replace of {len} bytes did not round-trip"
1057        );
1058    }
1059    done(d.remove("CURRENT"), "remove")?;
1060    check!(
1061        matches!(d.read("CURRENT"), Err(Error::NotFound { .. })),
1062        "a removed file still reads"
1063    );
1064    Ok(())
1065}