Crate atomic_lib

Expand description

atomic_lib helps you to get, store, serialize, parse and validate Atomic Data.

See the Atomic Data Docs for more information.

§Features

Two stores for Atomic Data:
- In-memory Store for getting / setting data. Useful for client applications.
- On disk [Db], powered by Sled. Useful for applications that persist Atomic Data, such as atomic-server.
serialize and parse tools for JSON-AD, plain JSON, RDF, Turtle, N-Triples and JSON-LD.
Resource with getters, setters and a .save function that creates Commits.
Value converts Atomic Data to Rust native types
Validate Atomic Schema
Commits (transactions / delta’s / changes / updates / versioning / history).
[plugins] system (although not very mature)
collections (pagination, sorting, filtering)
Querying (using triple pattern fragments) (see storelike::Query)
[plugins::invite] for sharing
hierarchy for authorization
[crate::endpoints::Endpoint] for custom API endpoints
[config::Config] files.

§Getting started

// Import the `Storelike` trait to get access to most functions
use atomic_lib::Storelike;

tokio::runtime::Builder::new_current_thread().enable_all().build().unwrap().block_on(async {
    // Start with initializing the in-memory store
    let store = atomic_lib::Store::init().await.unwrap();
    store.set_base_url("http://localhost");
    // Pre-load the default Atomic Data Atoms (from atomicdata.dev),
    // this is not necessary, but will probably make your project a bit faster
    store.populate().await.unwrap();
    // We can create a new Resource, linked to the store.
    // Note that since this store only exists in memory, it's data cannot be accessed from the internet.
    // Let's make a new Property instance! Let's create "age".
    let mut new_property = atomic_lib::Resource::new_instance("https://atomicdata.dev/classes/Property", &store).await.unwrap();
    // And add a description for that Property
    new_property.set_shortname("description", "the age of a person", &store).await.unwrap();
    // A subject URL for the new resource has been created automatically.
    let subject = new_property.get_subject().clone();
    // Now we need to make sure these changes are also applied to the store.
    // In order to change things in the store, we should use Commits,
    // which are signed pieces of data that contain state changes.
    // Because these are signed, we need an Agent, which has a private key to sign Commits.
    let agent = store.create_agent(Some("my_agent")).await.unwrap();
    store.set_default_agent(agent);
    let _fails   = new_property.save_locally(&store).await;
    // But.. when we commit, we get an error!
    // Because we haven't set all the properties required for the Property class.
    // We still need to set `shortname` and `datatype`.
    new_property.set_shortname("shortname", "age", &store).await.unwrap()
      .set_shortname("datatype", atomic_lib::urls::INTEGER, &store).await.unwrap()
      .save_locally(&store).await.unwrap();
    // Now the changes to the resource applied to the store, and we can fetch the newly created resource!
    let fetched_new_resource = store.get_resource(&subject).await.unwrap();
    assert!(fetched_new_resource.get_shortname("description", &store).await.unwrap().to_string() == "the age of a person");
});

Re-exports§

pub use atoms::Atom;
pub use commit::Commit;
pub use errors::AtomicError;
pub use errors::AtomicErrorType;
pub use resources::Resource;
pub use store::Store;
pub use storelike::Storelike;
pub use subject::DidKind;
pub use subject::Subject;
pub use values::Value;

Modules§

agents: Logic for Agents Agents are actors (such as users) that can edit content. https://docs.atomicdata.dev/commits/concepts.html
aggregate: Statistics computed over every row a query matches — not just the page it returns.
atoms: The smallest units of data, consisting of a Subject, a Property and a Value
authentication: Check signatures in authentication headers, find the correct agent. Authorization is done in Hierarchies
client: Client
collections: Collections are dynamic resources that refer to multiple resources. They are constructed using a Query
commit: Describe changes / mutations to data
datatype: DataTypes constrain values of Atoms
errors: Mostly contains implementations for Error types.
expression: Values computed from a row rather than stored on it — a duration, an amount, a days-since, a next-due date.
genesis: Self-verifying genesis certificate.
hierarchy: The Hierarchy model describes how Resources are structured in a tree-like shape. It deals with authorization (read / write permissions, rights, grants) See
history: Resource version history (time-travel reads), backed by the resource’s Loro oplog. This is the versioning story: every edit is a Loro change, so the history is already in the document and needs no separate log to replay.
mapping: Because writing full URLs is error prone and time consuming, we map URLs to shortnames. These are often user-specific. This section provides tools to store, share and resolve these Mappings.
metrics: Application-level metrics for atomic_lib, exported via OpenTelemetry. All functions compile to no-ops when the telemetry feature is disabled.
parse: Parsing / deserialization / decoding
populate: Populating a Store means adding resources to it. Some of these are the core Atomic Data resources, such as the Property class. These base models are required for having a functioning store.
resources: A Resource is a set of Atoms that share a URL. Has methods for saving resources and getting properties inside them.
schema: Structs and models at the core of Atomic Schema (Class, Property, Datatype).
serialize: Serialization / formatting / encoding (JSON, RDF, N-Triples)
store: In-memory store of Atomic data. This provides many methods for finding, changing, serializing and parsing Atomic Data.
storelike: The Storelike Trait contains many useful methods for maniupulting / retrieving data.
subject
sync: Sync protocol — transport-agnostic drive synchronization.
test_utils
urls: Contains some of the most important Atomic Data URLs.
utils: Helper functions for dealing with URLs
validate: Validate the Store and create a ValidationReport. Might be deprecated soon, as Validation hasn’t been necessary since parsing has built-in data validation.
values: A value is the part of an Atom that contains the actual information.
vault: Shared crypto for client-side envelope encryption: a random DEK encrypts the protected secret once, wrapped independently per enrolled credential (a generated recovery code today; a WebAuthn PRF wrapper is a planned addition). Consumed today by atomic-saas’s recovery-secret backup (planning/BACKUP_SECURITY.md); the same module is the intended home for the drive-level Cloud Vault key material later (planning/CLOUD_VAULT_ARCHITECTURE.md, Phase 0).

Crate atomic_lib

Crate atomic_lib Copy item path

§Features

§Getting started

Re-exports§

Modules§

Crate atomic_lib