Peermerge

Low level API for managing multi-writer JSON-like documents, without a central authority, with a P2P protocol.

Status

Pre-alpha

Licence

AGPLv3

lib.rs:

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, and communication between peers with hypercore-protocol. Optional support for 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: TCP/IP bindings to an existing peermerge
• peermerge-hub: configurable (tokio) runner that utilizes peermerge-tcp to host a proxy peermerge and adds back-up and logging
• peermerge-server: configurable 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 via the methods transact and transact_mut, for reading and writing, respectively.

Connecting to a peer is done via [AsyncRead]/[AsyncWrite] supported [FeedProtocol] passed onto either connect_protocol_disk or 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 from [tracing].

channel-writer

Export a convenient ChannelWriter wrapper and the bytes crate and .

Example

TODO

See also

Peermerge is heavily inspired by the original Javascript hypermerge package, which targeted now obsolete versions of both hypercore and automerge.