Struct noosphere_storage::SphereDb

pub struct SphereDb<S>where
    S: Storage,{ /* private fields */ }

A SphereDb is a high-level storage primitive for Noosphere’s APIs. It takes a Storage and implements BlockStore and KeyValueStore, orchestrating writes so that as blocks are stored, links are also extracted and tracked separately, and also hosting metadata information such as sphere version records and other purely local configuration

Implementations

impl<S> SphereDb<S>where
    S: Storage,

pub async fn new(storage: &S) -> Result<SphereDb<S>>

pub async fn persist(&mut self, memory_store: &MemoryStore) -> Result<()>

Given a MemoryStore, store copies of all the blocks found within in the storage that backs this SphereDb.

pub async fn set_version(&mut self, identity: &str, version: &Cid) -> Result<()>

Record the tip of a local sphere lineage as a Cid

pub async fn get_version(&self, identity: &str) -> Result<Option<Cid>>

Get the most recently recorded tip of a local sphere lineage

pub async fn require_version(&self, identity: &str) -> Result<Cid>

Get the most recently recorded tip of a local sphere lineage, returning an error if no version has ever been recorded

pub async fn get_block_links(&self, cid: &Cid) -> Result<Option<Vec<Cid>>>

Get all links referenced by a block given its Cid

pub fn query_links<'a, F, P>(
    &'a self,
    cid: &'a Cid,
    predicate: P
) -> impl Stream<Item = Result<Cid>> + 'awhere
    F: Future<Output = Result<bool>>,
    P: Fn(&Cid) -> F + Send + Sync + 'static,

Given a Cid root and a predicate function, stream all links that are referenced by the root or its descendants (recursively). The predicate function is called with each Cid before it is yielded by the stream. If the predicate returns true, the Cid is yielded and its referenced links are queued to be yielded later by the stream. If the predicate returns false, the Cid is skipped and by extension so are its referenced links.

pub fn stream_links<'a>(
    &'a self,
    cid: &'a Cid
) -> impl Stream<Item = Result<Cid>> + 'a

Stream all links that are referenced from the given root Cid or its DAG descendants (recursively).

pub fn stream_blocks<'a>(
    &'a self,
    cid: &'a Cid
) -> impl Stream<Item = Result<(Cid, Vec<u8>)>> + 'a

Stream all the blocks in the DAG starting at the given root Cid.

pub fn to_block_store(&self) -> S::BlockStore

Get an owned copy of the underlying primitive BlockStore for this SphereDb

Trait Implementations

impl<S> BlockStore for SphereDb<S>where
    S: Storage,

fn put_links<'life0, 'life1, 'life2, 'async_trait, C>(
    &'life0 mut self,
    cid: &'life1 Cid,
    block: &'life2 [u8]
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    C: Codec + Default + 'async_trait,
    Ipld: References<C>,
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,

Given a CID and a block, store the links (any Cid that is part of the encoded data) in a suitable location for later retrieval. This method is optional, and its default implementation is a no-op. It should be implemented when possible to enable optimized traversal of a DAG given its root.

fn put_block<'life0, 'life1, 'life2, 'async_trait>(
    &'life0 mut self,
    cid: &'life1 Cid,
    block: &'life2 [u8]
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,
    'life2: 'async_trait,

Given a block and its Cid, persist the block in storage.

fn get_block<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cid: &'life1 Cid
) -> Pin<Box<dyn Future<Output = Result<Option<Vec<u8>>>> + Send + 'async_trait>>where
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Given the Cid of a block, retrieve the block bytes from storage.

fn put<'life0, 'async_trait, C, T>(
    &'life0 mut self,
    data: T
) -> Pin<Box<dyn Future<Output = Result<Cid>> + Send + 'async_trait>>where
    C: Codec + Default + 'async_trait,
    T: Encode<C> + BlockStoreSend + 'async_trait,
    Ipld: References<C>,
    Self: Send + 'async_trait,
    'life0: 'async_trait,

Given some data structure that implements Encode for a given Codec, encode it as a block and persist it to storage for later retrieval by Cid.

fn get<'life0, 'life1, 'async_trait, C, T>(
    &'life0 self,
    cid: &'life1 Cid
) -> Pin<Box<dyn Future<Output = Result<Option<T>>> + Send + 'async_trait>>where
    C: Codec + Default + 'async_trait,
    T: Decode<C> + 'async_trait,
    Self: Sync + 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Given the Cid of a block that refers to a type that implements Decode for some Codec, retrieve the block, decode it as the type and return the result.

fn save<'life0, 'async_trait, C, T>(
    &'life0 mut self,
    data: T
) -> Pin<Box<dyn Future<Output = Result<Cid>> + Send + 'async_trait>>where
    C: Codec + Default + 'async_trait,
    T: Serialize + BlockStoreSend + 'async_trait,
    Ipld: Encode<C> + References<C>,
    Self: Send + 'async_trait,
    'life0: 'async_trait,

Given some data structure that implements Serialize, convert it to an IPLD-compatible representation, encode it as a block with the desired Codec and persist it to the storage backend by its Cid

fn load<'life0, 'life1, 'async_trait, C, T>(
    &'life0 self,
    cid: &'life1 Cid
) -> Pin<Box<dyn Future<Output = Result<T>> + Send + 'async_trait>>where
    C: Codec + Default + 'async_trait,
    T: DeserializeOwned + BlockStoreSend + 'async_trait,
    u64: From<C>,
    Ipld: Decode<C>,
    Self: Sync + 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Given a Cid that refers to some data structure that implements [Deserialize], read the block bytes from storage, decode it as IPLD using the specified Codec and and deserialize it to the intended data structure, returning the result.

fn require_block<'life0, 'life1, 'async_trait>(
    &'life0 self,
    cid: &'life1 Cid
) -> Pin<Box<dyn Future<Output = Result<Vec<u8>>> + Send + 'async_trait>>where
    Self: Sync + 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Same as load, but returns an error if no block is found locally for the given Cid

impl<S> Clone for SphereDb<S>where
    S: Storage + Clone,
    S::BlockStore: Clone,
    S::KeyValueStore: Clone,

fn clone(&self) -> SphereDb<S>

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl<S> KeyValueStore for SphereDb<S>where
    S: Storage,

fn set_key<'life0, 'async_trait, K, V>(
    &'life0 mut self,
    key: K,
    value: V
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    K: AsRef<[u8]> + BlockStoreSend + 'async_trait,
    V: Serialize + BlockStoreSend + 'async_trait,
    Self: 'async_trait,
    'life0: 'async_trait,

Given some key that can be realized as bytes, persist a serializable value to storage so that it can later be retrieved by that key

fn unset_key<'life0, 'async_trait, K>(
    &'life0 mut self,
    key: K
) -> Pin<Box<dyn Future<Output = Result<()>> + Send + 'async_trait>>where
    K: AsRef<[u8]> + BlockStoreSend + 'async_trait,
    Self: 'async_trait,
    'life0: 'async_trait,

Given some key that can be realized as bytes, unset the value stored against that key (if any)

fn get_key<'life0, 'async_trait, K, V>(
    &'life0 self,
    key: K
) -> Pin<Box<dyn Future<Output = Result<Option<V>>> + Send + 'async_trait>>where
    K: AsRef<[u8]> + BlockStoreSend + 'async_trait,
    V: DeserializeOwned + BlockStoreSend + 'async_trait,
    Self: 'async_trait,
    'life0: 'async_trait,

Given some key that can be realized as bytes, retrieve some data that can be deserialized as the intended data structure

fn require_key<'life0, 'async_trait, K, V>(
    &'life0 self,
    key: K
) -> Pin<Box<dyn Future<Output = Result<V>> + Send + 'async_trait>>where
    K: AsRef<[u8]> + KeyValueStoreSend + Display + 'async_trait,
    V: DeserializeOwned + KeyValueStoreSend + 'async_trait,
    Self: Sync + 'async_trait,
    'life0: 'async_trait,

Same as get_key, but returns an error if no value is found to be stored against the key

impl<S> UcanStore<RawCodec> for SphereDb<S>where
    S: Storage,

fn read<'life0, 'life1, 'async_trait, T>(
    &'life0 self,
    cid: &'life1 Cid
) -> Pin<Box<dyn Future<Output = Result<Option<T>>> + Send + 'async_trait>>where
    T: 'async_trait + Decode<RawCodec>,
    Self: 'async_trait,
    'life0: 'async_trait,
    'life1: 'async_trait,

Read a value from the store by CID, returning a Result<Option<…>> that unwraps to None if no value is found, otherwise Some

fn write<'life0, 'async_trait, T>(
    &'life0 mut self,
    token: T
) -> Pin<Box<dyn Future<Output = Result<Cid>> + Send + 'async_trait>>where
    T: 'async_trait + Encode<RawCodec> + UcanStoreConditionalSend + Debug,
    Self: 'async_trait,
    'life0: 'async_trait,

Write a value to the store, receiving a Result that wraps the values CID if the write was successful