Struct noosphere_fs::SphereFs

pub struct SphereFs<S, K>where
    S: Storage,
    K: KeyMaterial + Clone + 'static,{ /* private fields */ }

SphereFs: An FS-like abstraction over Noosphere content.

A sphere implements a flat namespace that maps strings to CIDs, which in turn refer to the sphere owner’s content. However, it is not particularly convenient for users to think of their content as organized around these primitives. The SphereFs interface offers a familiar, relatively high-level interface for operation on sphere content.

Implementations

impl<S, K> SphereFs<S, K>where S: Storage, K: KeyMaterial + Clone + 'static,

pub fn identity(&self) -> &str

Get the DID identity of the sphere that this FS view is reading from and writing to

pub fn revision(&self) -> &Cid

The CID revision of the sphere that this FS view is reading from and writing to

pub fn to_sphere(&self) -> Sphere<S::BlockStore>

Get a data view into the sphere at the current revision

pub async fn latest( sphere_identity: &Did, author: &Author<K>, db: &SphereDb<S> ) -> Result<SphereFs<S, K>>

Create an FS view into the latest revision found in the provided sphere reference storage

pub async fn at( sphere_identity: &Did, sphere_revision: &Cid, author: &Author<K>, db: &SphereDb<S> ) -> Result<SphereFs<S, K>>

Create an FS view into the sphere data at a specific revision; note that writes to this view will “fork” history and update the sphere reference to point to the fork.

pub async fn rewind(&mut self) -> Result<Option<Cid>>

Rewind the view to point to the version of the sphere just prior to this one in the edit chronology. If there was a previous version to rewind to then the returned Option has the CID of the revision, otherwise if the current version is the oldest one it is None.

pub async fn exists(&self, slug: &str) -> Result<bool>

Returns true if the content identitifed by slug exists in the sphere at the current revision.

pub async fn read( &self, slug: &str ) -> Result<Option<SphereFile<impl AsyncRead>>>

Read a file that is associated with a given slug at the revision of the sphere that this view is pointing to. Note that “contents” are AsyncRead, and content bytes won’t be read until contents is polled.

pub async fn write<R: AsyncRead + Unpin>( &mut self, slug: &str, content_type: &str, value: R, additional_headers: Option<Vec<(String, String)>> ) -> Result<Cid>

Write to a slug in the sphere. In order to commit the change to the sphere, you must call save. You can buffer multiple writes before saving.

The returned CID is a link to the memo for the newly added content.

pub async fn link( &mut self, slug: &str, content_type: &str, body_cid: &Cid, additional_headers: Option<Vec<(String, String)>> ) -> Result<Cid>

Similar to write, but instead of generating blocks from some provided bytes, the caller provides a CID of an existing DAG in storage. That CID is used as the body of a Memo that is written to the specified slug, and the CID of the memo is returned.

pub async fn remove(&mut self, slug: &str) -> Result<Option<Cid>>

Unlinks a slug from the content space. Note that this does not remove the blocks that were previously associated with the content found at the given slug, because they will still be available at an earlier revision of the sphere. In order to commit the change, you must save. Note that this call is a no-op if there is no matching slug linked in the sphere.

The returned value is the CID previously associated with the slug, if any.

pub async fn save( &mut self, additional_headers: Option<Vec<(String, String)>> ) -> Result<Cid>

Commits a series of writes to the sphere. In addition to commiting new content to the sphere and block storage, this method:

• Creates a new revision based on the one that this FS view points to
• Signs the new revision with provided key material
• Updates this FS view to point to the new revision

The new revision CID of the sphere is returned.

pub async fn list(&self) -> BTreeSet<String>

Get a BTreeSet whose members are all the slugs that have values as of this version of the sphere. Note that the full space of slugs may be very large; for a more space-efficient approach, use SphereFs::stream or SphereFs::into_stream to incrementally access all slugs in the sphere.

This method is forgiving of missing or corrupted data, and will yield an incomplete set of links in the case that some or all links are not able to be accessed.

pub async fn changes(&self, since: Option<&Cid>) -> BTreeSet<String>

Get a BTreeSet whose members are all the slugs whose values have changed at least once since the provided version of the sphere (exclusive of the provided version; use None to get all slugs changed since the beginning of the sphere’s history).

This method is forgiving of missing or corrupted history, and will yield an incomplete set of changes in the case that some or all changes are not able to be accessed.

Note that this operation will scale in memory consumption and duration proportionally to the size of the sphere and the length of its history. For a more efficient method of accessing changes, consider using SphereFs::change_stream instead.

pub fn stream<'a>( &'a self ) -> impl Stream<Item = Result<(String, SphereFile<impl AsyncRead + 'a>)>>

Get a stream that yields every slug in the namespace along with its corresponding SphereFile. This is useful for iterating over sphere content incrementally without having to load the entire index into memory at once.

pub fn into_stream( self ) -> impl Stream<Item = Result<(String, SphereFile<impl AsyncRead>)>>

Same as stream, but consumes the SphereFs. This is useful in cases where it would otherwise be necessary to borrow a reference to SphereFs for a static lifetime.

pub fn change_stream<'a>( &'a self, since: Option<&'a Cid> ) -> impl Stream<Item = Result<(Cid, BTreeSet<String>)>> + 'a

Get a stream that yields the set of slugs that changed at each revision of the backing sphere, up to but excluding an optional CID. To stream the entire history, pass None as the parameter.

Trait Implementations

impl<S, K> Clone for SphereFs<S, K>where S: Storage, K: KeyMaterial + Clone + 'static,

fn clone(&self) -> Self

Returns a copy of the value.

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

Performs copy-assignment from source.