Skip to main content

rig_memory/
conformance.rs

1//! The contract every [`AsyncStore`] keeps, checked against a store: what
2//! a missing log or file reads as, the length check of the two log writes,
3//! names refused, and racing writers, of which exactly one wins. A store's
4//! own tests run [`check_store`] on two handles to one empty storage, such
5//! as two connections to one database, so it also checks that what one
6//! handle writes the other reads.
7//!
8//! ```
9//! use std::future::Future;
10//! use std::pin::pin;
11//! use std::task::{Context, Poll, Waker};
12//!
13//! use rig_memory::MemoryStore;
14//! use rig_memory::conformance::check_store;
15//!
16//! let store = MemoryStore::default();
17//! let other = store.clone();
18//! let check = pin!(check_store(&store, &other));
19//! // A local store's calls are done when made, so one poll finishes it.
20//! let Poll::Ready(checked) = check.poll(&mut Context::from_waker(Waker::noop())) else {
21//!     return Err("pending".into());
22//! };
23//! checked?;
24//! # Ok::<(), Box<dyn std::error::Error>>(())
25//! ```
26
27use std::future::{Future, poll_fn};
28use std::io;
29use std::pin::Pin;
30use std::task::Poll;
31
32use rig_core::message::Message;
33
34use crate::{AsyncStore, LogWriteError, SessionError, load_async, save_async};
35
36/// A part of the contract a store broke.
37#[derive(Debug, thiserror::Error)]
38#[error("{check}: {detail}")]
39pub struct Violation {
40    /// The part of the contract.
41    pub check: &'static str,
42    /// What the store did instead.
43    pub detail: String,
44}
45
46/// How many writers race for one log.
47const RACERS: usize = 8;
48
49/// Checks that `a` and `b`, two handles to one storage that holds nothing
50/// yet, keep [`AsyncStore`]'s contract together.
51///
52/// # Errors
53///
54/// The first [`Violation`] found.
55pub async fn check_store<S: AsyncStore + ?Sized>(a: &S, b: &S) -> Result<(), Violation> {
56    missing(a).await?;
57    appends(a, b).await?;
58    replaces(a, b).await?;
59    files(a, b).await?;
60    names(a).await?;
61    races(a, b).await?;
62    sessions(a, b).await
63}
64
65fn ensure(ok: bool, check: &'static str, detail: impl FnOnce() -> String) -> Result<(), Violation> {
66    if ok {
67        return Ok(());
68    }
69    Err(Violation {
70        check,
71        detail: detail(),
72    })
73}
74
75fn is_kind<T>(result: &io::Result<T>, kind: io::ErrorKind) -> bool {
76    matches!(result, Err(error) if error.kind() == kind)
77}
78
79fn is_changed(result: &Result<(), LogWriteError>) -> bool {
80    matches!(result, Err(LogWriteError::Changed))
81}
82
83/// `read`, which must be `want`.
84fn reads(check: &'static str, read: io::Result<Vec<u8>>, want: &[u8]) -> Result<(), Violation> {
85    match read {
86        Ok(bytes) => ensure(bytes == want, check, || {
87            format!("read {bytes:?}, not {want:?}")
88        }),
89        Err(error) => ensure(false, check, || format!("read failed: {error}")),
90    }
91}
92
93/// `write`, which must succeed.
94fn wrote<E: std::fmt::Display>(check: &'static str, write: Result<(), E>) -> Result<(), Violation> {
95    match write {
96        Ok(()) => Ok(()),
97        Err(error) => ensure(false, check, || format!("write failed: {error}")),
98    }
99}
100
101/// A log or file that was never written is not found, and a log write
102/// that names a length other than 0 neither writes nor starts it.
103async fn missing<S: AsyncStore + ?Sized>(a: &S) -> Result<(), Violation> {
104    let check = "a missing log or file is not found";
105    let read = a.read_log_async("missing").await;
106    ensure(is_kind(&read, io::ErrorKind::NotFound), check, || {
107        format!("read_log_async gave {read:?}")
108    })?;
109    let read = a.read_file_async("missing/file").await;
110    ensure(is_kind(&read, io::ErrorKind::NotFound), check, || {
111        format!("read_file_async gave {read:?}")
112    })?;
113    let check = "a log write to a missing log at a length other than 0 is refused";
114    let append = a.append_log_async("missing", 3, b"abc").await;
115    ensure(is_changed(&append), check, || {
116        format!("append gave {append:?}")
117    })?;
118    let replace = a.replace_log_async("missing", 1, b"abc").await;
119    ensure(is_changed(&replace), check, || {
120        format!("replace gave {replace:?}")
121    })?;
122    let read = a.read_log_async("missing").await;
123    ensure(is_kind(&read, io::ErrorKind::NotFound), check, || {
124        format!("the refused writes left {read:?}")
125    })
126}
127
128/// An append at the log's length adds its bytes, binary ones included;
129/// one at another length writes nothing; an empty append at 0 starts an
130/// empty log.
131async fn appends<S: AsyncStore + ?Sized>(a: &S, b: &S) -> Result<(), Violation> {
132    let check = "an append at the log's length adds its bytes";
133    let first = b"one\n\0\xff\n";
134    wrote(check, a.append_log_async("appends", 0, first).await)?;
135    reads(check, b.read_log_async("appends").await, first)?;
136    let second = b"two\n";
137    let len = first.len() as u64;
138    wrote(check, b.append_log_async("appends", len, second).await)?;
139    reads(
140        check,
141        a.read_log_async("appends").await,
142        b"one\n\0\xff\ntwo\n",
143    )?;
144
145    let check = "an append at another length is refused and writes nothing";
146    for stale in [0, len, len + 100, i64::MAX as u64, u64::MAX] {
147        let append = a.append_log_async("appends", stale, b"lost\n").await;
148        ensure(is_changed(&append), check, || {
149            format!("an append at {stale} gave {append:?}")
150        })?;
151    }
152    reads(
153        check,
154        b.read_log_async("appends").await,
155        b"one\n\0\xff\ntwo\n",
156    )?;
157
158    let check = "an empty append at 0 starts an empty log";
159    wrote(check, a.append_log_async("empty", 0, b"").await)?;
160    reads(check, b.read_log_async("empty").await, b"")?;
161    wrote(check, b.append_log_async("empty", 0, b"after\n").await)?;
162    wrote(check, a.append_log_async("empty", 6, b"").await)?;
163    reads(check, a.read_log_async("empty").await, b"after\n")
164}
165
166/// A replace at the log's length replaces it, and starts a missing one at
167/// 0; at another length it writes nothing; an append after it goes after
168/// the new bytes.
169async fn replaces<S: AsyncStore + ?Sized>(a: &S, b: &S) -> Result<(), Violation> {
170    let check = "a replace at the log's length replaces it";
171    wrote(
172        check,
173        a.append_log_async("replaces", 0, b"old\nlog\n").await,
174    )?;
175    wrote(check, b.replace_log_async("replaces", 8, b"new\n").await)?;
176    reads(check, a.read_log_async("replaces").await, b"new\n")?;
177    wrote(check, a.append_log_async("replaces", 4, b"more\n").await)?;
178    reads(check, b.read_log_async("replaces").await, b"new\nmore\n")?;
179    wrote(check, b.replace_log_async("replaces", 9, b"").await)?;
180    reads(check, a.read_log_async("replaces").await, b"")?;
181
182    let check = "a replace at another length is refused and writes nothing";
183    let replace = a.replace_log_async("replaces", 9, b"lost\n").await;
184    ensure(is_changed(&replace), check, || {
185        format!("replace gave {replace:?}")
186    })?;
187    reads(check, b.read_log_async("replaces").await, b"")?;
188
189    let check = "a replace at 0 starts a missing log";
190    wrote(check, a.replace_log_async("started", 0, b"fresh\n").await)?;
191    reads(check, b.read_log_async("started").await, b"fresh\n")
192}
193
194/// A file write replaces the whole file, under a nested name too.
195async fn files<S: AsyncStore + ?Sized>(a: &S, b: &S) -> Result<(), Violation> {
196    let check = "a file write replaces the whole file";
197    let name = "blobs/nested/file";
198    wrote(check, a.write_file_async(name, b"long content\0\xff").await)?;
199    reads(check, b.read_file_async(name).await, b"long content\0\xff")?;
200    wrote(check, b.write_file_async(name, b"short").await)?;
201    reads(check, a.read_file_async(name).await, b"short")?;
202    wrote(check, a.write_file_async("top", b"").await)?;
203    reads(check, b.read_file_async("top").await, b"")?;
204    let check = "a file and a log of one name are apart";
205    let read = a.read_file_async("appends").await;
206    ensure(is_kind(&read, io::ErrorKind::NotFound), check, || {
207        format!("the file `appends` read {read:?}")
208    })?;
209    let read = b.read_log_async("top").await;
210    ensure(is_kind(&read, io::ErrorKind::NotFound), check, || {
211        format!("the log `top` read {read:?}")
212    })
213}
214
215/// Names that [`check_name`](crate::check_name) refuses, and log names in
216/// more than one part, are refused with [`io::ErrorKind::InvalidInput`].
217async fn names<S: AsyncStore + ?Sized>(a: &S) -> Result<(), Violation> {
218    let check = "a name that is no name in a session is refused";
219    let invalid = |result: &Result<(), LogWriteError>| matches!(result, Err(LogWriteError::Io(error)) if error.kind() == io::ErrorKind::InvalidInput);
220    for name in ["", ".", "..", "../up", "/root", "a//b", "a\\b", "a/./b"] {
221        let read = a.read_file_async(name).await;
222        ensure(is_kind(&read, io::ErrorKind::InvalidInput), check, || {
223            format!("read_file_async({name:?}) gave {read:?}")
224        })?;
225        let write = a.write_file_async(name, b"x").await;
226        ensure(is_kind(&write, io::ErrorKind::InvalidInput), check, || {
227            format!("write_file_async({name:?}) gave {write:?}")
228        })?;
229    }
230    for name in ["", "..", "../up", "/root", "a\\b", "nested/log"] {
231        let read = a.read_log_async(name).await;
232        ensure(is_kind(&read, io::ErrorKind::InvalidInput), check, || {
233            format!("read_log_async({name:?}) gave {read:?}")
234        })?;
235        let append = a.append_log_async(name, 0, b"x").await;
236        ensure(invalid(&append), check, || {
237            format!("append_log_async({name:?}) gave {append:?}")
238        })?;
239        let replace = a.replace_log_async(name, 0, b"x").await;
240        ensure(invalid(&replace), check, || {
241            format!("replace_log_async({name:?}) gave {replace:?}")
242        })?;
243    }
244    Ok(())
245}
246
247/// Every future in `futures`, polled together until all are done: writes
248/// in flight at once, on whichever connections the handles hold.
249async fn together<'f, T>(futures: Vec<Pin<Box<dyn Future<Output = T> + 'f>>>) -> Vec<T> {
250    let mut futures: Vec<_> = futures.into_iter().map(Some).collect();
251    let mut outputs: Vec<Option<T>> = futures.iter().map(|_| None).collect();
252    poll_fn(|cx| {
253        for (slot, output) in futures.iter_mut().zip(outputs.iter_mut()) {
254            if let Some(future) = slot
255                && let Poll::Ready(done) = future.as_mut().poll(cx)
256            {
257                *output = Some(done);
258                *slot = None;
259            }
260        }
261        if futures.iter().all(Option::is_none) {
262            Poll::Ready(())
263        } else {
264            Poll::Pending
265        }
266    })
267    .await;
268    outputs.into_iter().flatten().collect()
269}
270
271/// Of writers that read a log at one length and write to it at once,
272/// through both handles, exactly one writes and the others are refused:
273/// when they start the log, when they append to it, and when a replace
274/// races the appends. Writers of one file at once all write, and it holds
275/// one of their bytes whole, as two saves storing one blob do.
276async fn races<S: AsyncStore + ?Sized>(a: &S, b: &S) -> Result<(), Violation> {
277    let lines: Vec<Vec<u8>> = (0..RACERS)
278        .map(|racer| format!("writer {racer}\n").into_bytes())
279        .collect();
280    let mut log = Vec::new();
281    for (check, replacing) in [
282        ("of writers starting a log at once, one writes", false),
283        (
284            "of writers appending at one length at once, one writes",
285            false,
286        ),
287        (
288            "of a replace and appends at one length at once, one writes",
289            true,
290        ),
291    ] {
292        let len = log.len() as u64;
293        let writes = lines.iter().enumerate().map(|(racer, line)| {
294            let store = if racer % 2 == 0 { a } else { b };
295            let write: Pin<Box<dyn Future<Output = _>>> = if replacing && racer == 0 {
296                Box::pin(store.replace_log_async("raced", len, line))
297            } else {
298                Box::pin(store.append_log_async("raced", len, line))
299            };
300            write
301        });
302        let results = together(writes.collect()).await;
303        let mut winners = Vec::new();
304        for (racer, result) in results.iter().enumerate() {
305            match result {
306                Ok(()) => winners.push(racer),
307                Err(LogWriteError::Changed) => {}
308                Err(error) => {
309                    return ensure(false, check, || format!("writer {racer} failed: {error}"));
310                }
311            }
312        }
313        let &[winner] = winners.as_slice() else {
314            return ensure(false, check, || format!("writers {winners:?} all wrote"));
315        };
316        let line = lines.get(winner).map_or(&[][..], Vec::as_slice);
317        if replacing && winner == 0 {
318            log = line.to_vec();
319        } else {
320            log.extend_from_slice(line);
321        }
322        reads(check, a.read_log_async("raced").await, &log)?;
323    }
324
325    let check = "of writers of one file at once, all write and one's bytes are kept";
326    let writes = lines.iter().enumerate().map(|(racer, line)| {
327        let store = if racer % 2 == 0 { a } else { b };
328        let write: Pin<Box<dyn Future<Output = _>>> =
329            Box::pin(store.write_file_async("blobs/raced", line));
330        write
331    });
332    for (racer, result) in together(writes.collect()).await.into_iter().enumerate() {
333        if let Err(error) = result {
334            return ensure(false, check, || format!("writer {racer} failed: {error}"));
335        }
336    }
337    match b.read_file_async("blobs/raced").await {
338        Ok(file) => ensure(lines.contains(&file), check, || {
339            format!("the file holds {file:?}")
340        }),
341        Err(error) => ensure(false, check, || format!("read failed: {error}")),
342    }
343}
344
345/// Through [`save_async`] and [`load_async`]: a conversation saved through
346/// one handle loads through the other, and of two saves that loaded the
347/// same conversation the second is refused with [`SessionError::Changed`],
348/// until it loads again.
349async fn sessions<S: AsyncStore + ?Sized>(a: &S, b: &S) -> Result<(), Violation> {
350    let check = "a saved conversation loads through the other handle";
351    let failed = |error: SessionError| Violation {
352        check,
353        detail: error.to_string(),
354    };
355    let mut first = load_async(a, "chat").await.map_err(failed)?;
356    first.extend([
357        Message::user("My name is Alice."),
358        Message::assistant("Hi Alice!"),
359    ]);
360    save_async(a, "chat", &mut first).await.map_err(failed)?;
361    let mut second = load_async(b, "chat").await.map_err(failed)?;
362    ensure(second == first, check, || {
363        format!("loaded {second:?}, not {first:?}")
364    })?;
365
366    let check = "of two saves that loaded one conversation, the second is refused";
367    first.push(Message::user("What is my name?"));
368    save_async(a, "chat", &mut first)
369        .await
370        .map_err(|error| Violation {
371            check,
372            detail: error.to_string(),
373        })?;
374    second.push(Message::user("Forget my name."));
375    let refused = save_async(b, "chat", &mut second).await;
376    ensure(
377        matches!(refused, Err(SessionError::Changed { ref log }) if log == "chat"),
378        check,
379        || format!("the second save gave {refused:?}"),
380    )?;
381    let loaded = load_async(b, "chat").await.map_err(|error| Violation {
382        check,
383        detail: error.to_string(),
384    })?;
385    ensure(loaded == first, check, || {
386        format!("loaded {loaded:?}, not the first save's {first:?}")
387    })
388}
389
390#[cfg(test)]
391mod tests;