peermerge 0.0.3

Manage JSON-like documents with multiple writers, without a central authority, using a P2P protocol
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144

//! ## Introduction
//!
//! Peermerge is a Rust crate for managing JSON-like documents with multiple writers without a
//! central authority. Concurrent writing is made possible with the CRDT implementation of
//! [automerge][automerge], and communication between peers with
//! [hypercore-protocol][hypercore-protocol]. Optional support for
//! [p2panda][p2panda] and other peer protocols, instead of hypercore, is planned in the
//! future.
//!
//! Peermerge can be built with WASM for browser support and uses either the `tokio` or
//! `async-std` runtimes.
//!
//! This crate exposes a low-level API that the following crates from the same family utilize:
//!
//! * [peermerge-tcp][peermerge-tcp]: TCP/IP bindings to an existing peermerge
//! * [peermerge-hub][peermerge-hub]: configurable (tokio) runner that utilizes peermerge-tcp
//!   to host a proxy peermerge and adds back-up and logging
//! * [peermerge-server][peermerge-server]: configurable [axum][axum] web server built on
//!   top of peermerge-hub, which adds websocket bindings and static HTML file serving.
//!
//! ## Design
//!
//! The main abstraction is [Peermerge], which is a repository that stores
//! documents. For a single peer (device or server) there usually isn't a
//! need to create and/or open more than one Peermerge instance.
//!
//! Peermerge is designed to be cheap to clone and sent to spawned threads, and data within
//! it can be either stored in memory or on disk. Disk storage is naturally more common,
//! but in-memory storage can also be useful for example for WASM builds where a peer (i.e.
//! browser) doesn't have a file system. (To prevent a new peer from being created on every
//! browser refresh, see `reattach_secrets`.)
//!
//! Peermerge exposes the full interface of automerge's
//! [AutoCommit][automerge-autocommit] via the methods [transact](crate::Peermerge::transact) and
//! [transact_mut](crate::Peermerge::transact_mut), for reading and writing, respectively.
//!
//! Connecting to a peer is done via [AsyncRead]/[AsyncWrite] supported [FeedProtocol] passed
//! onto either [connect_protocol_disk](crate::Peermerge::connect_protocol_disk) or
//! [connect_protocol_memory](crate::Peermerge::connect_protocol_memory).
//!
//! ## Features
//!
//! ### `hypercore-feed` (default, mandatory)
//!
//! Future-compatible, currently mandatory, feature to use the hypercore feed.
//!
//! ### `tokio-runtime` (default)
//!
//! Use the tokio runtime, on by default. Either this or `async-std-runtime` is mandatory.
//!
//! ### `async-std-runtime`
//!
//! Use the async-std runtime. Either this or `tokio-runtime` is mandatory.
//!
//! ### `wasm-bindgen` (default)
//!
//! Enable support for WASM compilation and runtime.
//!
//! ### `log`
//!
//! Enable support for [log][log] from [tracing].
//!
//! ### `channel-writer`
//!
//! Export a convenient `ChannelWriter` wrapper and the [bytes][bytes] crate and .
//!
//! ## Example
//!
//! TODO
//!
//! ## See also
//!
//! Peermerge is heavily inspired by the original Javascript [hypermerge][hypermerge] package,
//! which targeted now obsolete versions of both hypercore and automerge.
//!
//! [automerge]: https://crates.io/crates/automerge
//! [hypercore-protocol]: https://crates.io/crates/hypercore-protocol
//! [p2panda]: https://crates.io/crates/p2panda-rs
//! [peermerge-tcp]: https://crates.io/crates/peermerge-tcp
//! [peermerge-hub]: https://crates.io/crates/peermerge-hub
//! [peermerge-server]: https://crates.io/crates/peermerge-server
//! [axum]: https://crates.io/crates/axum
//! [automerge-autocommit]: automerge::AutoCommit
//! [log]: https://crates.io/crates/log
//! [bytes]: https://crates.io/crates/bytes
//! [hypermerge]: https://github.com/automerge/hypermerge

#![forbid(unsafe_code, nonstandard_style, future_incompatible)]
#![forbid(missing_debug_implementations)]
#![forbid(unreachable_pub, missing_docs)]

/// Module to host convenient ChannelWriter wrapper
#[cfg(feature = "channel-writer")]
pub mod channel_writer;
mod common;
mod core;
mod crdt;
mod document;
mod feeds;
mod options;

#[macro_use]
extern crate derive_builder;

// Custom types and traits
/// Public key of the feed.
pub type FeedPublicKey = [u8; 32];
/// Discovery key of the feed. Derived by hashing from FeedPublicKey.
pub type FeedDiscoveryKey = [u8; 32];
/// Id of a document. Derived by hashing from FeedDiscoveryKey.
pub type DocumentId = [u8; 32];
/// Id of a peer
pub type PeerId = [u8; 16];
use futures::{AsyncRead, AsyncWrite};
/// Input/Output trait using AsyncRead/AsyncWrite
pub trait IO: AsyncWrite + AsyncRead + Send + Unpin + 'static {}
impl<T> IO for T where T: AsyncWrite + AsyncRead + Send + Unpin + 'static {}

// Crate exports
pub use crate::common::constants::{
    DEFAULT_MAX_ENTRY_DATA_SIZE_BYTES, DEFAULT_MAX_WRITE_FEED_LENGTH, MAX_ENTRY_DATA_SIZE_BYTES,
};
pub use crate::common::{
    decode_base64_nopad, encode_base64_nopad, get_document_info, new_uuid_v4, AccessType,
    DocumentInfo, DocumentSharingInfo, DynamicDocumentInfo, FeedType, NameDescription,
    PeermergeError, StateEvent, StateEventContent, StaticDocumentInfo, UrlDocumentInfo,
};
pub use crate::core::Peermerge;
pub use crate::crdt::AutomergeDoc;
#[cfg(not(target_arch = "wasm32"))]
pub use feeds::FeedDiskPersistence;
pub use feeds::{FeedMemoryPersistence, FeedPersistence};
pub use feeds::{FeedProtocol, ProtocolBuilder};
pub use options::*;

// Related crates' re-exports
pub use automerge;
#[cfg(feature = "channel-writer")]
pub use bytes;
#[cfg(not(target_arch = "wasm32"))]
pub use random_access_disk::RandomAccessDisk;
pub use random_access_memory::RandomAccessMemory;
pub use random_access_storage::RandomAccess;
pub use uuid;