radicle_cob/
lib.rs

1// Copyright © 2021 The Radicle Link Contributors
2
3#![warn(clippy::unwrap_used)]
4//! # Collaborative Objects
5//!
6//! Collaborative objects are graphs of CRDTs.
7//!
8//! ## Basic Types
9//!
10//! The basic types that are found in `radicle-cob` are:
11//!   * [`CollaborativeObject`] -- the computed object itself.
12//!   * [`ObjectId`] -- the content-address for a single collaborative object.
13//!   * [`TypeName`] -- the name for a collection of collaborative objects.
14//!   * [`History`] -- the traversable history of the changes made to
15//!     a single collaborative object.
16//!
17//! ## CRU Interface (No Delete)
18//!
19//! The main entry for manipulating [`CollaborativeObject`]s is by
20//! using the CRU like functions:
21//!   * [`create`]
22//!   * [`get`]
23//!   * [`list`]
24//!   * [`update`]
25//!
26//! ## Storage
27//!
28//! The storing of collaborative objects is based on a git
29//! backend. The previously mentioned functions all accept a [`Store`]
30//! as parameter. The `Store` itself is an accumulation of different
31//! storage capabilities:
32//!   * [`object::Storage`]
33//!   * [`change::Storage`] -- **Note**: there is already an
34//!     implementation for this for [`git2::Repository`] for convenience.
35//!
36//! ## Resource
37//!
38//! The [`create`] and [`update`] functions take a `Resource`. It
39//! represents the type of resource the collaborative objects are
40//! relating to, for example a software project.
41//!
42//! ## History Traversal
43//!
44//! The [`History`] of a [`CollaborativeObject`] -- accessed via
45//! [`CollaborativeObject::history`] -- has a method
46//! [`History::traverse`] which provides a way of inspecting each
47//! [`Entry`] and building up a final value.
48//!
49//! This traversal is also the point at which the [`Entry::author`]
50//! and [`Entry::resource`] can be retrieved to apply any kind of
51//! filtering logic. For example, a specific `author`'s change may be
52//! egregious, spouting terrible libel about Radicle. It is at this
53//! point that the `actor`'s change can be filtered out from the
54//! final product of the traversal.
55
56#[cfg(test)]
57extern crate qcheck;
58#[cfg(test)]
59#[macro_use(quickcheck)]
60extern crate qcheck_macros;
61
62extern crate radicle_crypto as crypto;
63extern crate radicle_git_ext as git_ext;
64
65mod backend;
66pub use backend::git;
67
68mod change_graph;
69mod trailers;
70
71pub mod change;
72pub use change::store::{Contents, Embed, EntryId, Manifest, Version};
73pub use change::Entry;
74
75pub mod history;
76pub use history::History;
77
78pub mod signatures;
79use signatures::ExtendedSignature;
80
81pub mod type_name;
82pub use type_name::TypeName;
83
84pub mod object;
85pub use object::{
86    create, get, info, list, remove, update, CollaborativeObject, Create, Evaluate, ObjectId,
87    Update, Updated,
88};
89
90#[cfg(test)]
91#[allow(clippy::unwrap_used)]
92mod test;
93
94#[cfg(test)]
95#[allow(clippy::unwrap_used)]
96mod tests;
97
98/// The `Store` is an aggregation of the different types of storage
99/// traits required for editing [`CollaborativeObject`]s.
100///
101/// The backing store being used is expected to be a `git` backend.
102///
103/// To get started using this trait, you must implement the following
104/// for the specific `git` storage:
105///
106///   * [`object::Storage`]
107///
108/// **Note**: [`change::Storage`] is already implemented for
109/// [`git2::Repository`]. It is expected that the underlying storage
110/// for `object::Storage` will also be `git2::Repository`, but if not
111/// please open an issue to change the definition of `Store` :)
112pub trait Store
113where
114    Self: object::Storage
115        + change::Storage<
116            StoreError = git::change::error::Create,
117            LoadError = git::change::error::Load,
118            ObjectId = git_ext::Oid,
119            Parent = git_ext::Oid,
120            Signatures = ExtendedSignature,
121        >,
122{
123}
radicle_cob/lib.rs

radicle_cob/
lib.rs
