Crate noosphere_sphere 

This crate implements content, petname and other forms of acccess to spheres. If you have storage and network primitives on your platform, you can initialize a SphereContext and use it to work with and synchronize spheres, as well as traverse the broader Noosphere data graph.

In order to initialize a SphereContext, you need a Did (like an ID) for a Sphere, a Storage primitive and an Author (which represents whoever or whatever is trying to access the Sphere inquestion).

Once you have a SphereContext, you can begin reading from, writing to and traversing the Noosphere content graph.

sphere_context.write("foo", "text/plain", "bar".as_ref(), None).await?;
sphere_context.save(None).await?;

You can also use a SphereContext to access petnames in the sphere:

sphere_context.set_petname("cdata", Some("did:key:example".into())).await?;
sphere_context.save(None).await?;

Re-exports

pub use metadata::*;

Modules

metadata

These constants represent the metadata keys used when a SphereContext is is initialized. Since these represent somewhat free-form key/values in the storage layer, we are make a best effort to document them here.

Structs

BodyChunkDecoder

Helper to easily decode a linked list of BodyChunkIpld as a byte stream

GatewaySyncStrategy

The default synchronization strategy is a git-like fetch->rebase->push flow. It depends on the corresponding history of a “counterpart” sphere that is owned by a gateway server. As revisions are pushed to the gateway server, it updates its own sphere to point to the tip of the latest lineage of the user’s. When a new change needs to be synchronized, the latest history of the counterpart sphere is first fetched, and the local changes are rebased on the counterpart sphere’s reckoning of the authoritative lineage of the user’s sphere. Finally, after the rebase, the reconciled local lineage is pushed to the gateway.

SphereContext

A SphereContext is an accessor construct over locally replicated sphere data. It embodies both the storage layer that contains the sphere’s data as the information needed to verify a user’s intended level of access to it (e.g., local key material and ucan::Ucan-based authorization). Additionally, the SphereContext maintains a reference to an API Client that may be initialized as the network becomes available.

SphereCursor

A SphereCursor is a structure that enables reading from and writing to a SphereContext at specific versions of the associated sphere’s history. There are times when you may wish to be able to use the convenience implementation of traits built on HasSphereContext, but to always be sure of what version you are using them on (such as when traversing sphere history). That is when you would use a SphereCursor, which can wrap any implementor of HasSphereContext and mount it to a specific version of the sphere.

SphereFile

A descriptor for contents that is stored in a sphere.

SphereWalker

A SphereWalker makes it possible to convert anything that implements HasSphereContext into an async Stream over sphere content, allowing incremental iteration over both the breadth of content at any version, or the depth of changes over a range of history.

Enums

SyncError

Different classes of error that may occur during synchronization with a gateway

SyncRecovery

Recovery strategies for cases when gateway synchronization fails but may be able to recover gracefully (e.g., when the gateway reports a conflict).

Traits

AsyncFileBody

A type that may be used as the contents field in a SphereFile

HasConditionalSendSync

HasMutableSphereContext

Any container that can provide mutable access to a SphereContext should implement HasMutableSphereContext. The most common example of something that may implement this trait is Arc<Mutex<SphereContext<_, _>>>. Implementors of this trait will automatically implement other traits that provide convenience methods for modifying the contents, petnames and other aspects of a sphere.

HasSphereContext

Any container that can provide non-mutable access to a SphereContext should implement HasSphereContext. The most common example of something that may implement this trait is an Arc<SphereContext<_, _>>. Implementors of this trait will automatically implement other traits that provide convience methods for accessing different parts of the sphere, such as content and petnames.

SphereAuthorityRead

Anything that can read the authority section from a sphere should implement SphereAuthorityRead. A blanket implementation is provided for anything that implements HasSphereContext.

SphereAuthorityWrite

Any type which implements SphereAuthorityWrite is able to manipulate the [AuthorityIpld] section of a sphere. This includes authorizing other keys and revoking prior authorizations.

SphereContentRead

Anything that can read content from a sphere should implement SphereContentRead. A blanket implementation is provided for anything that implements HasSphereContext.

SphereContentWrite

Anything that can write content to a sphere should implement SphereContentWrite. A blanket implementation is provided for anything that implements HasMutableSphereContext.

SpherePetnameRead

Anything that provides read access to petnames in a sphere should implement SpherePetnameRead. A blanket implementation is provided for any container that implements HasSphereContext.

SpherePetnameWrite

Anything that can write petnames to a sphere should implement SpherePetnameWrite. A blanket implementation is provided for anything that implements HasMutableSphereContext

SphereReplicaRead

Implementors are able to traverse from one sphere to the next via the address book entries found in those spheres

SphereSync

Implementors of SphereSync are able to sychronize with a Noosphere gateway

Functions

car_stream

Takes a list of roots and a stream of blocks (pairs of Cid and corresponding Vec), and produces an async byte stream that yields a valid CARv1

memo_body_stream

Stream all the blocks required to read the sphere at a given version (making no assumptions of what historical data may already be available to the reader).

memo_history_stream

Stream all the blocks required to reconstruct the history of a sphere since a given point in time (or else the beginning of the history).

walk_versioned_map_changes_and

Given a VersionedMap and BlockStore, visit the VersionedMap’s changelog; then, invoke the provided callback with each entry associated with an ‘add’ operation in the changelog

walk_versioned_map_elements

Given a VersionedMap, visit its changelog and all of its underlying entries

walk_versioned_map_elements_and

Given a VersionedMap and BlockStore, visit the VersionedMap’s changelog and all of its underlying entries, invoking a callback for each entry

Type Aliases

SphereContextKey

The type of any KeyMaterial that is used within a SphereContext