Expand description
§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.
Re-exports§
Structs§
- Attach
Document Disk Options - Options for attaching an existing document to a disk Peermerge
- Attach
Document Disk Options Builder - Builder for
AttachDocumentDiskOptions. - Attach
Document Memory Options - Options for attaching an existing document to an in-memory Peermerge
- Attach
Document Memory Options Builder - Builder for
AttachDocumentMemoryOptions. - Create
NewDocument Disk Options - Options for creating new disk document.
- Create
NewDocument Disk Options Builder - Builder for
CreateNewDocumentDiskOptions. - Create
NewDocument Memory Options - Options for creating new in-memory document.
- Create
NewDocument Memory Options Builder - Builder for
CreateNewDocumentMemoryOptions. - Document
Info - Information about a document
- Document
Sharing Info - Document sharing information
- Dynamic
Document Info - Dynamic document information. Can change over the normal course of the document.
- Feed
Disk Persistence - Main constructor.
- Feed
Memory Persistence - In-memory storage for random access
- Feed
Protocol - A Protocol stream.
- Name
Description - Name and optional description
- Open
Disk Options - Options for opening an existing peermerge
- Open
Disk Options Builder - Builder for
OpenDiskOptions. - Peermerge
- Peermerge is the main abstraction and a store for multiple documents.
- Peermerge
Disk Options - Disk Peermerge options
- Peermerge
Disk Options Builder - Builder for
PeermergeDiskOptions. - Peermerge
Memory Options - In-memory Peermerge options
- Peermerge
Memory Options Builder - Builder for
PeermergeMemoryOptions. - Protocol
Builder - Build a Protocol instance with options.
- Random
Access Disk - Main constructor.
- Random
Access Memory - In-memory storage for random access
- State
Event - State event from a document
- Static
Document Info - Static information about the document. Will never change over the course of the document’s lifetime.
- UrlDocument
Info - Document information parsed from a document URL. NB: This is a limited set of information compared to what is received when manipulating documents in a live peermerge, i.e. DocumentInfo. Most notably, the URL will not contain a full list of child documents because that list can grow infinitely and thus cause the URL to exceed the maximum character limit.
Enums§
- Access
Type - Access type to a document.
- Attach
Document Disk Options Builder Error - Error type for AttachDocumentDiskOptionsBuilder
- Attach
Document Memory Options Builder Error - Error type for AttachDocumentMemoryOptionsBuilder
- Create
NewDocument Disk Options Builder Error - Error type for CreateNewDocumentDiskOptionsBuilder
- Create
NewDocument Memory Options Builder Error - Error type for CreateNewDocumentMemoryOptionsBuilder
- Feed
Type - Type of feed.
- Open
Disk Options Builder Error - Error type for OpenDiskOptionsBuilder
- Peermerge
Disk Options Builder Error - Error type for PeermergeDiskOptionsBuilder
- Peermerge
Error - Common error type for the peermerge interface
- Peermerge
Memory Options Builder Error - Error type for PeermergeMemoryOptionsBuilder
- State
Event Content - Content of a StateEvent
Constants§
- DEFAULT_
MAX_ ENTRY_ DATA_ SIZE_ BYTES - Use the max size of 1 MiB also as the default value for a single data chunk in a feed.
- DEFAULT_
MAX_ WRITE_ FEED_ LENGTH - Use 2^8 as the default maximum length of a write feed. After this length is reach, a new write feed created which replaces the old.
- MAX_
ENTRY_ DATA_ SIZE_ BYTES - Use 1 MiB as the absolute max limit for a single data chunk in a feed.
Traits§
- Feed
Persistence - Type for a feed’s persistence
- IO
- Input/Output trait using AsyncRead/AsyncWrite
- Random
Access - Interface for reading from, writing to and deleting from a randomly accessible storage of bytes.
Functions§
- decode_
base64_ nopad - Decode with Base64 URL-compatible without padding. Convenience method to create byte arrays from automerge keys.
- encode_
base64_ nopad - Encode with Base64 URL-compatible without padding. Convenience method to create short strings from byte arrays to use as automerge keys. strings from byte arrays to use as automerge keys.
- get_
document_ info - Get document information from document URL and optional document secret.
- new_
uuid_ v4 - Generate new v4 UUID. Convenience method to generate UUIDs using just peermerge without importing the uuid crate and configuring WASM support.
Type Aliases§
- Automerge
Doc - Automerge document type, set to AutoCommit.
- Document
Id - Id of a document. Derived by hashing from FeedDiscoveryKey.
- Feed
Discovery Key - Discovery key of the feed. Derived by hashing from FeedPublicKey.
- Feed
Public Key - Public key of the feed.
- PeerId
- Id of a peer