willow-data-model 0.2.0

The datatypes of Willow, an eventually consistent data store with improved distributed deletion.
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

use crate::entry::Entry;
use core::fmt::Debug;

/// A type for identifying [namespaces](https://willowprotocol.org/specs/data-model/index.html#namespace).
///
/// When an implementing type implements [`PartialOrd`], then `Self::default()` must return a least element with respect to the ordering.
///
/// [Definition](https://willowprotocol.org/specs/data-model/index.html#NamespaceId).
pub trait NamespaceId: Eq + Default + Clone + Debug {}

/// A type for identifying [subspaces](https://willowprotocol.org/specs/data-model/index.html#subspace).
///
/// [Definition](https://willowprotocol.org/specs/data-model/index.html#SubspaceId).
///
/// ## Implementation notes
///
/// The [`Default`] implementation **must** return the least element in the total order of [`SubspaceId`].
pub trait SubspaceId: Ord + Default + Clone + Debug {
    /// Returns the next possible value in the set of all [`SubspaceId`], i.e. the (unique) least value that is strictly greater than `self`. Only if there is no greater value at all may this method return `None`.
    fn successor(&self) -> Option<Self>;
}

/// A totally ordered type for [content-addressing](https://en.wikipedia.org/wiki/Content_addressing) the data that Willow stores.
///
/// This trait mirrors the [`std::hash::Hasher`] trait (with the hasher state as an associated type), but hashing not to `u64`s but to `Self`s.
///
/// [Definition](https://willowprotocol.org/specs/data-model/index.html#PayloadDigest).
///
/// ## Implementation notes
///
/// The [`Default`] implementation **must** return the least element in the total order of [`PayloadDigest`].
pub trait PayloadDigest: Ord + Default + Clone + Debug {
    /// The state for hashing slices of bytes.
    type Hasher;

    /// Returns the initial state for hashing, i.e., the hash for the empty string.
    fn hasher() -> Self::Hasher;

    /// Returns the digest for the values written so far.
    ///
    /// Despite its name, the method does not reset the hasher’s internal state. Additional writes will continue from the current value. If you need to start a fresh hash value, you will have to create a new hasher.
    fn finish(hasher: &Self::Hasher) -> Self;

    /// Writes some data into the given Hasher.
    fn write(hasher: &mut Self::Hasher, bytes: &[u8]);
}

/// Determines whether this type (nominally an [`AuthorisationToken`](https://willowprotocol.org/specs/data-model/index.html#AuthorisationToken)) is able to prove write permission for a given [`Entry`].
///
/// ## Type parameters
///
/// - `N` - The type used for the [`Entry`]'s [`NamespaceId`].
/// - `S` - The type used for the [`Entry`]'s [`SubspaceId`].
/// - `PD` - The type used for the [`Entry`]'s [`PayloadDigest`].
pub trait AuthorisationToken<const MCL: usize, const MCC: usize, const MPL: usize, N, S, PD>:
    Clone
{
    /// Determines whether this type (nominally a [`AuthorisationToken`](https://willowprotocol.org/specs/data-model/index.html#AuthorisationToken)) is able to prove write permission for a given [`Entry`].
    fn is_authorised_write(&self, entry: &Entry<MCL, MCC, MPL, N, S, PD>) -> bool;
}