iroh_docs/lib.rs
1#![doc = include_str!("../README.md")]
2//! Multi-dimensional key-value documents with an efficient synchronization protocol
3//!
4//! The crate operates on [Replicas](Replica). A replica contains an unlimited number of
5//! [Entries][Entry]. Each entry is identified by a key, its author, and the replica's
6//! namespace. Its value is the [32-byte BLAKE3 hash](iroh_blobs::Hash)
7//! of the entry's content data, the size of this content data, and a timestamp.
8//! The content data itself is not stored or transferred through a replica.
9//!
10//! All entries in a replica are signed with two keypairs:
11//!
12//! * The [`NamespaceSecret`] key, as a token of write capability. The public key is the
13//! [`NamespaceId`], which also serves as the unique identifier for a replica.
14//! * The [Author] key, as a proof of authorship. Any number of authors may be created, and
15//! their semantic meaning is application-specific. The public key of an author is the [AuthorId].
16//!
17//! Replicas can be synchronized between peers by exchanging messages. The synchronization algorithm
18//! is based on a technique called *range-based set reconciliation*, based on [this paper][paper] by
19//! Aljoscha Meyer:
20//!
21//! > Range-based set reconciliation is a simple approach to efficiently compute the union of two
22//! > sets over a network, based on recursively partitioning the sets and comparing fingerprints of
23//! > the partitions to probabilistically detect whether a partition requires further work.
24//!
25//! The crate exposes a [generic storage interface](store::Store). There is an implementation
26//! of this interface, [store::fs::Store], that can be used either
27//! [in-memory](store::fs::Store::memory) or in
28//! [persistent, file-based](store::fs::Store::persistent) mode.
29//!
30//! Both modes make use of [`redb`], an embedded key-value store. When used
31//! in-memory, the store is backed by a `Vec<u8>`. When used in persistent mode,
32//! the store is backed by a single file on disk.
33//!
34//! [paper]: https://arxiv.org/abs/2212.13567
35#![deny(missing_docs, rustdoc::broken_intra_doc_links)]
36#![cfg_attr(iroh_docsrs, feature(doc_auto_cfg))]
37
38pub mod metrics;
39#[cfg(feature = "net")]
40pub mod net;
41#[cfg(feature = "engine")]
42pub mod protocol;
43#[cfg(feature = "net")]
44mod ticket;
45
46#[cfg(feature = "engine")]
47pub mod engine;
48#[cfg(feature = "rpc")]
49pub mod rpc;
50
51#[cfg(feature = "cli")]
52pub mod cli;
53
54pub mod actor;
55pub mod store;
56pub mod sync;
57
58mod heads;
59mod keys;
60mod ranger;
61
62#[cfg(feature = "net")]
63#[doc(inline)]
64pub use net::ALPN;
65
66#[cfg(feature = "net")]
67pub use self::ticket::DocTicket;
68pub use self::{heads::*, keys::*, sync::*};