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 git_ref_format_core as fmt;
63extern crate radicle_crypto as crypto;
64extern crate radicle_dag as dag;
65extern crate radicle_git_metadata as metadata;
66extern crate radicle_oid as oid;
67
68mod backend;
69
70#[cfg(all(any(test, feature = "test"), feature = "git2"))]
71pub use backend::git;
72
73#[cfg(feature = "stable-commit-ids")]
74pub use backend::stable;
75
76mod change_graph;
77mod trailers;
78
79pub mod change;
80pub use change::store::{Contents, Embed, EntryId, Manifest, Version};
81pub use change::Entry;
82
83pub mod history;
84pub use history::History;
85
86pub mod signatures;
87use signatures::ExtendedSignature;
88
89pub mod type_name;
90pub use type_name::TypeName;
91
92pub mod object;
93pub use object::{
94    create, get, info, list, remove, update, CollaborativeObject, Create, Evaluate, ObjectId,
95    Update, Updated,
96};
97
98#[cfg(test)]
99#[allow(clippy::unwrap_used)]
100mod test;
101
102#[cfg(test)]
103#[allow(clippy::unwrap_used)]
104mod tests;
105
106/// The `Store` is an aggregation of the different types of storage
107/// traits required for editing [`CollaborativeObject`]s.
108///
109/// The backing store being used is expected to be a `git` backend.
110///
111/// To get started using this trait, you must implement the following
112/// for the specific `git` storage:
113///
114///   * [`object::Storage`]
115///
116pub trait Store
117where
118    Self: object::Storage
119        + change::Storage<ObjectId = oid::Oid, Parent = oid::Oid, Signatures = ExtendedSignature>,
120{
121}
radicle_cob/lib.rs

radicle_cob/
lib.rs
