Trait Store

pub trait Store<const MCL: usize, const MCC: usize, const MPL: usize, N, S, PD, AT> {
    type Error: Display + Error + PartialEq;

    // Required methods
    fn namespace_id(&self) -> &N;
    fn ingest_entry(
        &self,
        authorised_entry: AuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>,
        prevent_pruning: bool,
        origin: EntryOrigin,
    ) -> impl Future<Output = Result<EntryIngestionSuccess<MCL, MCC, MPL, N, S, PD, AT>, EntryIngestionError<Self::Error>>>;
    fn append_payload<Producer, PayloadSourceError>(
        &self,
        subspace_id: &S,
        path: &Path<MCL, MCC, MPL>,
        expected_digest: Option<PD>,
        payload_source: &mut Producer,
    ) -> impl Future<Output = Result<PayloadAppendSuccess, PayloadAppendError<PayloadSourceError, Self::Error>>>
       where Producer: BulkProducer<Item = u8, Error = PayloadSourceError>;
    fn forget_entry(
        &self,
        subspace_id: &S,
        path: &Path<MCL, MCC, MPL>,
        expected_digest: Option<PD>,
    ) -> impl Future<Output = Result<(), ForgetEntryError<Self::Error>>>;
    fn forget_area(
        &self,
        area: &Area<MCL, MCC, MPL, S>,
        protected: Option<&Area<MCL, MCC, MPL, S>>,
    ) -> impl Future<Output = Result<usize, Self::Error>>;
    fn forget_payload(
        &self,
        subspace_id: &S,
        path: &Path<MCL, MCC, MPL>,
        expected_digest: Option<PD>,
    ) -> impl Future<Output = Result<(), ForgetPayloadError<Self::Error>>>;
    fn forget_area_payloads(
        &self,
        area: &Area<MCL, MCC, MPL, S>,
        protected: Option<&Area<MCL, MCC, MPL, S>>,
    ) -> impl Future<Output = Result<usize, Self::Error>>;
    fn flush(&self) -> impl Future<Output = Result<(), Self::Error>>;
    fn payload(
        &self,
        subspace_id: &S,
        path: &Path<MCL, MCC, MPL>,
        expected_digest: Option<PD>,
    ) -> impl Future<Output = Result<Option<impl BulkProducer<Item = u8, Final = (), Error = Self::Error>>, PayloadError<Self::Error>>>;
    fn entry(
        &self,
        subspace_id: &S,
        path: &Path<MCL, MCC, MPL>,
        ignore: QueryIgnoreParams,
    ) -> impl Future<Output = Result<Option<LengthyAuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>>, Self::Error>>;
    fn query_area(
        &self,
        area: &Area<MCL, MCC, MPL, S>,
        ignore: QueryIgnoreParams,
    ) -> impl Future<Output = Result<impl Producer<Item = LengthyAuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>, Final = ()>, Self::Error>>;
    fn subscribe_area(
        &self,
        area: &Area<MCL, MCC, MPL, S>,
        ignore: QueryIgnoreParams,
    ) -> impl Future<Output = impl Producer<Item = StoreEvent<MCL, MCC, MPL, N, S, PD, AT>, Final = (), Error = Self::Error>>;
}

A Store is a set of AuthorisedEntry belonging to a single namespace, and a (possibly partial) corresponding set of payloads.

Required Associated Types

type Error: Display + Error + PartialEq

Required Methods

fn namespace_id(&self) -> &N

Returns the namespace which all of this store’s AuthorisedEntry belong to.

fn ingest_entry( &self, authorised_entry: AuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>, prevent_pruning: bool, origin: EntryOrigin, ) -> impl Future<Output = Result<EntryIngestionSuccess<MCL, MCC, MPL, N, S, PD, AT>, EntryIngestionError<Self::Error>>>

Attempts to ingest an AuthorisedEntry into the Store.

Will fail if the entry belonged to a different namespace than the store’s, or if the prevent_pruning param is true and an ingestion would have triggered prefix pruning.

fn append_payload<Producer, PayloadSourceError>( &self, subspace_id: &S, path: &Path<MCL, MCC, MPL>, expected_digest: Option<PD>, payload_source: &mut Producer, ) -> impl Future<Output = Result<PayloadAppendSuccess, PayloadAppendError<PayloadSourceError, Self::Error>>>

where Producer: BulkProducer<Item = u8, Error = PayloadSourceError>,

Attempts to append part of a payload for an entry at a given SubspaceId-Path-pair.

Will report an error if:

• There is no entry for the given SubspaceId-Path pair.
• The payload digest of the entry at the given subspace_id and path is not equal to the supplied expected_digest (if one was supplied).
• The payload source produced more bytes than were expected for this payload.
• The payload source yielded an error.
• The final payload’s digest did not match the expected digest
• Something else went wrong, e.g. there was no space for the payload on disk.

This method does not and cannot verify the integrity of partial payloads. This means that arbitrary (and possibly malicious) payloads smaller than the expected size will be stored unless partial verification is implemented upstream (e.g. as part of a sync protocol).

fn forget_entry( &self, subspace_id: &S, path: &Path<MCL, MCC, MPL>, expected_digest: Option<PD>, ) -> impl Future<Output = Result<(), ForgetEntryError<Self::Error>>>

Locally forgets an entry with a given Path and subspace id, returning the forgotten entry, or an error if no entry with that path and subspace ID are held by this store. If an expected_digest is supplied and the entry turns out to not have that digest, then this method does nothing and reports an ForgetEntryError::WrongEntry error.

If the entry in question is the last remaining reference in the store to a particular crate::PayloadDigest, that payload will be forgotten from the store (if present).

Forgetting is not the same as pruning! Subsequent joins with other Stores may bring the forgotten entry back.

fn forget_area( &self, area: &Area<MCL, MCC, MPL, S>, protected: Option<&Area<MCL, MCC, MPL, S>>, ) -> impl Future<Output = Result<usize, Self::Error>>

Locally forgets all AuthorisedEntry included by a given crate::grouping::Area, returning the number of forgotten entries.

If forgetting many entries causes no there to be no remaining references to certain payload digests, those payloads will be removed (if present).

If protected is Some, then all entries included by that Area will be prevented from being forgotten, even though they are included by area.

Forgetting is not the same as pruning! Subsequent joins with other Stores may bring the forgotten entries back.

fn forget_payload( &self, subspace_id: &S, path: &Path<MCL, MCC, MPL>, expected_digest: Option<PD>, ) -> impl Future<Output = Result<(), ForgetPayloadError<Self::Error>>>

Locally forgets the corresponding payload of the entry with a given path and subspace, panics if no entry with that path and subspace ID is held by this store. If an expected_digest is supplied and the entry turns out to not have that digest, then this method does nothing and reports a ForgetPayloadError::WrongEntry error.

Forgetting is not the same as pruning! Subsequent joins with other Stores may bring the forgotten payload back.

fn forget_area_payloads( &self, area: &Area<MCL, MCC, MPL, S>, protected: Option<&Area<MCL, MCC, MPL, S>>, ) -> impl Future<Output = Result<usize, Self::Error>>

Locally forgets all payloads with corresponding [‘AuthorisedEntry’] included by a given crate::grouping::Area, returning a count of forgotten payloads. Payloads corresponding to entries outside of the given area param will be be prevented from being forgotten.

If protected is Some, then all payloads corresponding to entries included by that Area will be prevented from being forgotten, even though they are included by area.

Forgetting is not the same as pruning! Subsequent joins with other Stores may bring the forgotten payloads back.

fn flush(&self) -> impl Future<Output = Result<(), Self::Error>>

Forces persistence of all previous mutations

fn payload( &self, subspace_id: &S, path: &Path<MCL, MCC, MPL>, expected_digest: Option<PD>, ) -> impl Future<Output = Result<Option<impl BulkProducer<Item = u8, Final = (), Error = Self::Error>>, PayloadError<Self::Error>>>

Returns a ufotofu::Producer of bytes for the payload corresponding to the given subspace id and path. If an expected_digest is supplied and the entry turns out to not have that digest, then this method does nothing and reports a PayloadError::WrongEntry error.

fn entry( &self, subspace_id: &S, path: &Path<MCL, MCC, MPL>, ignore: QueryIgnoreParams, ) -> impl Future<Output = Result<Option<LengthyAuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>>, Self::Error>>

Returns a LengthyAuthorisedEntry with the given Path and subspace ID, if present.

fn query_area( &self, area: &Area<MCL, MCC, MPL, S>, ignore: QueryIgnoreParams, ) -> impl Future<Output = Result<impl Producer<Item = LengthyAuthorisedEntry<MCL, MCC, MPL, N, S, PD, AT>, Final = ()>, Self::Error>>

Queries which entries are included by an Area, returning a producer of LengthyAuthorisedEntry produced in an arbitrary order decided by the store implementation.

fn subscribe_area( &self, area: &Area<MCL, MCC, MPL, S>, ignore: QueryIgnoreParams, ) -> impl Future<Output = impl Producer<Item = StoreEvent<MCL, MCC, MPL, N, S, PD, AT>, Final = (), Error = Self::Error>>

Subscribes to events concerning entries included by an crate::grouping::Area, returning a producer of StoreEvents which occurred since the moment of calling this function.

Dyn Compatibility

This trait is not dyn compatible.

In older versions of Rust, dyn compatibility was called "object safety", so this trait is not object safe.

Implementors