willow-data-model 0.7.0

use core::{fmt::Debug, ops::RangeBounds};

use anyhash::Hasher;
use derive_more::{Display, Error};
use ufotofu::prelude::*;

use crate::prelude::*;

/// The most basic trait describing storage for [`Entry`](Entries).
///
/// A `Store` is a collection of entries such that none of them would [prefix-prune](https://willowprotocol.org/specs/data-model/index.html#prefix_pruning) each other.
///
/// This trait provides only a very basic set of operations: creation of new entries, querying individual entries and all entries within an [`Area`], local deletion, and accessing (subslices of) payloads. More specialised operations are provided by subtraits.
///
/// Stores must implement [`Clone`], and the expectation is that cloning is cheap and that changes on one clone also affect all other clones. You perform concurrent operations on a store by cloning it and then performing the operations on different clones.
///
/// Important: persistent stores are not required to persist mutations immediately. Call the [`Store::flush`] method to ensure that an operation is persisted.
pub trait Store<const MCL: usize, const MCC: usize, const MPL: usize, N, S, PD, AT>: Clone {
    /// The type of errors the store implementation might yield on any operation.
    type InternalError;

    /// Creates an [`AuthorisedEntry`] with the given data and payload, and atomically inserts the payload and entry into the store.
    ///
    /// If the new entry would be prefix-pruned immediately by a newer entry already in the store, this method returns `Ok(None)`. If the new entry prefix-prunes older entries in the store, those older entries are automatically removed.
    ///
    /// If the producer does not error, it must yield exactly `payload_length` many items and then the final `()` — otherwise, this method panics.
    async fn create_entry<Data, P, H>(
        &mut self,
        data: &Data,
        payload_producer: P,
        payload_length: u64,
        ingredients: &AT::Ingredients,
    ) -> Result<
        Option<AuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>>,
        CreateEntryError<Self::InternalError, P::Error, AT::CreationError>,
    >
    where
        Data: ?Sized + Namespaced<N> + Coordinatelike<MCL, MCC, MPL, S>,
        P: BulkProducer<Item = u8, Final = ()>,
        H: Default + Hasher<PD>,
        AT: AuthorisationToken<MCL, MCC, MPL, N, S, PD> + Debug,
        N: Debug,
        S: Debug,
        PD: Debug;

    /// Creates an [`Entry`] with the given data and payload, and atomically inserts the payload and entry into the store, unless it would prune one or more older entries.
    ///
    /// If the new entry would be prefix-pruned immediately by a newer entry already in the store, this method returns `Ok(None)`. If the new entry prefix-prunes older entries in the store, the store remains unchanged
    ///
    /// If the producer does not error, it must yield exactly `payload_length` many items and then the final `()` — otherwise, this method panics.
    async fn create_entry_nondestructive<Data, P, H>(
        &mut self,
        data: &Data,
        payload_producer: P,
        payload_length: u64,
        ingredients: &AT::Ingredients,
    ) -> Result<
        NondestructiveInsert<MCL, MCC, MPL, N, S, PD, AT>,
        CreateEntryError<Self::InternalError, P::Error, AT::CreationError>,
    >
    where
        Data: ?Sized + Namespaced<N> + Coordinatelike<MCL, MCC, MPL, S>,
        P: BulkProducer<Item = u8, Final = ()>,
        H: Default + Hasher<PD>,
        AT: AuthorisationToken<MCL, MCC, MPL, N, S, PD> + Debug,
        N: Debug,
        S: Debug,
        PD: Debug;

    /// Inserts a given [`AuthorisedEntry`] into the store.
    ///
    /// If the new entry would be prefix-pruned immediately by a newer entry already in the store, this method returns `Ok(false)`, otherwise `Ok(true)`. If the new entry prefix-prunes older entries in the store, those older entries are automatically removed.
    async fn insert_entry(
        &mut self,
        entry: AuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>,
    ) -> Result<bool, Self::InternalError>;

    /// Removes an entry and its payload from the store. Return `Ok(true)` if data was actually removed, and `Ok(false)` if there was no matching entry in the first place.
    ///
    /// If the `expected_digest` is `Some(pd)`, then the addressed entry is only forgotten if its payload digest is `pd`. If the payload digest does not match, the method returns `Ok(false)`.
    ///
    /// Forgetting is not the same as [pruning](https://willowprotocol.org/specs/data-model/index.html#prefix_pruning)! Subsequent [joins](https://willowprotocol.org/specs/data-model/index.html#store_join) with other [`Store`]s may bring the forgotten entry back.
    async fn forget_entry<K>(
        &mut self,
        namespace_id: &N,
        key: &K,
        expected_digest: Option<PD>,
    ) -> Result<bool, Self::InternalError>
    where
        K: Keylike<MCL, MCC, MPL, S>,
        PD: PartialEq;

    /// Removes all entries and their payloads in some [`Area`] from the store.
    ///
    /// Forgetting is not the same as [pruning](https://willowprotocol.org/specs/data-model/index.html#prefix_pruning)! Subsequent [joins](https://willowprotocol.org/specs/data-model/index.html#store_join) with other [`Store`]s may bring forgotten entries back.
    async fn forget_area(
        &mut self,
        namespace_id: &N,
        area: &Area<MCL, MCC, MPL, S>,
    ) -> Result<(), Self::InternalError>;

    /// Removes all entries and their payloads in some namespace from the store.
    ///
    /// Forgetting is not the same as [pruning](https://willowprotocol.org/specs/data-model/index.html#prefix_pruning)! Subsequent [joins](https://willowprotocol.org/specs/data-model/index.html#store_join) with other [`Store`]s may bring forgotten entries back.
    async fn forget_namespace(&mut self, namespace_id: &N) -> Result<(), Self::InternalError>;

    /// Gets an entry (or `None` if there is none) together with a producer its payload (more specifically, the indicated `payload_slice`).
    ///
    /// If the `expected_digest` is `Some(pd)`, then the addressed entry is only returned if its payload digest is `pd`. If the payload digest does not match, the method returns `Ok(None)`.
    ///
    /// If the start of the indicated payload slice is strictly greater than its end, or if its start is strictly greater than the length of the stored payload, the behaviour of this method is unspecified.
    async fn get_entry<K, Slice>(
        &mut self,
        namespace_id: &N,
        key: &K,
        expected_digest: Option<PD>,
        payload_slice: &Slice,
    ) -> Result<
        Option<(
            AuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>,
            impl BulkProducer<Item = u8, Final = (), Error = PayloadProducerError<Self::InternalError>>,
        )>,
        Self::InternalError,
    >
    where
        K: Keylike<MCL, MCC, MPL, S>,
        Slice: RangeBounds<u64>;

    /// Returns a producer of all entries in some [`Area`] from the store.
    async fn get_area(
        &mut self,
        namespace_id: N,
        area: Area<MCL, MCC, MPL, S>,
    ) -> impl Producer<
        Item = AuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>,
        Final = (),
        Error = Self::InternalError,
    >;

    /// Flushes all prior operations. If the backing storage is persistent, all mutations up to that point will have been successfully persisted after a successful flush.
    async fn flush(&mut self) -> Result<(), Self::InternalError>;
}

/// The possible successful outcomes of non-destructively inserting an [`AuthorisedEntry`] into a [`Store`].
#[derive(Debug, PartialEq, Eq, PartialOrd, Ord, Hash, Clone)]
pub enum NondestructiveInsert<const MCL: usize, const MCC: usize, const MPL: usize, N, S, PD, AT> {
    /// Inserted the entry, and no other data was pruned.
    Success(AuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>),
    /// Inserting an entry would have pruned old entries, so instead the store was not modified at all.
    Prevented,
    /// The inserted entry would be pruned by a newer entry in the store, so it was not inserted in the first place.
    Outdated,
}

/// The errors that can be encountered when producing a payload.
#[derive(Debug, Display, Error, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy)]
pub enum PayloadProducerError<StoreError> {
    /// The store implementation encountered an internal error.
    #[display("store error")]
    StoreError(StoreError),
    /// The entry payload has been pruned or was forgotten.
    #[display("payload was removed")]
    PayloadWasRemoved,
}

/// The errors that can be encountered when creating an entry (from a producer emitting the payload).
#[derive(Debug, Display, Error, PartialEq, Eq, PartialOrd, Ord, Hash, Clone, Copy)]
pub enum CreateEntryError<StoreError, ProducerError, AuthorisationTokenError> {
    /// The store implementation encountered an internal error.
    #[display("store error")]
    StoreError(StoreError),
    /// The payload producer produced a different number of bytes than the claimed length.
    #[display("incorrect payload length")]
    IncorrectPayloadLength,
    /// The payload producer emitted an error.
    #[display("producer error")]
    ProducerError(ProducerError),
    /// Could not create an authorisation token for the created entry.
    #[display("authorisation token error")]
    AuthorisationTokenError(AuthorisationTokenError),
}

// TODO Traits for a future hierarchy:
//
// -Bab-based payload interaction
// - Area-based summaries
// - 3dRange-based queries (also summaries, possibly in subtrait)
// - subscriptions