iroh-docs (0.101.0)
Installation
[registries.forgejo]
index = "sparse+cargo add iroh-docs@0.101.0 --registry forgejoAbout this package
iroh-docs
Multi-dimensional key-value documents with an efficient synchronization protocol.
The crate operates on Replicas. A replica contains an unlimited number of Entries. Each entry is identified by a key, its author, and the replica's namespace. Its value is the 32-byte BLAKE3 hash of the entry's content data, the size of this content data, and a timestamp. The content data itself is not stored or transferred through a replica.
All entries in a replica are signed with two keypairs:
- The Namespace key, as a token of write capability. The public key is the NamespaceId, which also serves as the unique identifier for a replica.
- The Author key, as a proof of authorship. Any number of authors may be created, and their semantic meaning is application-specific. The public key of an author is the [AuthorId].
Replicas can be synchronized between peers by exchanging messages. The synchronization algorithm is based on a technique called range-based set reconciliation, based on this paper by Aljoscha Meyer:
Range-based set reconciliation is a simple approach to efficiently compute the union of two sets over a network, based on recursively partitioning the sets and comparing fingerprints of the partitions to probabilistically detect whether a partition requires further work.
The crate exposes a generic storage interface with in-memory and persistent, file-based
implementations. The latter makes use of [redb], an embedded key-value store, and persists
the whole store with all replicas to a single file.
Getting Started
The entry into the iroh-docs protocol is the Docs struct, which uses an Engine to power the protocol.
Docs was designed to be used in conjunction with iroh. Iroh is a networking library for making direct connections, these connections are peers send sync messages and transfer data.
Iroh provides a Router that takes an Endpoint and any protocols needed for the application. Similar to a router in webserver library, it runs a loop accepting incoming connections and routes them to the specific protocol handler, based on ALPN.
Docs is a "meta protocol" that relies on the iroh-blobs and iroh-gossip protocols. Setting up Docs will require setting up Blobs and Gossip as well.
Here is a basic example of how to set up iroh-docs with iroh:
use iroh::{endpoint::presets, protocol::Router, Endpoint};
use iroh_blobs::{BlobsProtocol, store::mem::MemStore, ALPN as BLOBS_ALPN};
use iroh_docs::{protocol::Docs, ALPN as DOCS_ALPN};
use iroh_gossip::{net::Gossip, ALPN as GOSSIP_ALPN};
#[tokio::main]
async fn main() -> anyhow::Result<()> {
// create an iroh endpoint that includes the standard discovery mechanisms
// we've built at number0
let endpoint = Endpoint::bind(presets::N0).await?;
// build the blobs protocol
let blobs = MemStore::default();
// build the gossip protocol
let gossip = Gossip::builder().spawn(endpoint.clone());
// build the docs protocol
let docs = Docs::memory()
.spawn(endpoint.clone(), (*blobs).clone(), gossip.clone())
.await?;
// create a router builder, we will add the
// protocols to this builder and then spawn
// the router
let builder = Router::builder(endpoint.clone());
// setup router
let _router = builder
.accept(BLOBS_ALPN, BlobsProtocol::new(&blobs, None))
.accept(GOSSIP_ALPN, gossip)
.accept(DOCS_ALPN, docs)
.spawn();
// do fun stuff with docs!
Ok(())
}
License
Copyright 2026 N0, INC.
This project is licensed under either of
- Apache License, Version 2.0, (LICENSE-APACHE or http://www.apache.org/licenses/LICENSE-2.0)
- MIT license (LICENSE-MIT or http://opensource.org/licenses/MIT)
at your option.
Contribution
Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in this project by you, as defined in the Apache-2.0 license, shall be dual licensed as above, without any additional terms or conditions.
Dependencies
| ID | Version |
|---|---|
| anyhow | ^1 |
| async-channel | ^2.3.1 |
| blake3 | ^1.8 |
| bytes | ^1.7 |
| derive_more | ^2.0.1 |
| futures-buffered | ^0.2.4 |
| hex | ^0.4 |
| iroh | ^1 |
| iroh-blobs | ^0.103 |
| iroh-gossip | ^0.101.0 |
| iroh-metrics | ^1 |
| iroh-tickets | ^1 |
| irpc | ^0.17 |
| n0-error | ^1 |
| n0-future | ^0.3.1 |
| noq | ^1 |
| num_enum | ^0.7 |
| postcard | ^1 |
| rand | ^0.10 |
| redb | ^4.1 |
| redb_v3 | ^3.1 |
| self_cell | ^1.0.3 |
| serde | ^1.0.164 |
| serde-error | ^0.1.3 |
| strum | ^0.28 |
| tempfile | ^3.4 |
| thiserror | ^2 |
| tokio | ^1 |
| tokio-stream | ^0.1 |
| tokio-util | ^0.7.12 |
| tracing | ^0.1 |
| data-encoding | ^2.6.0 |
| iroh | ^1 |
| nested_enum_utils | ^0.2 |
| parking_lot | ^0.12.3 |
| proptest | ^1.2.0 |
| rand | ^0.10 |
| tempfile | ^3.4 |
| test-strategy | ^0.4 |
| testdir | ^0.10 |
| testresult | ^0.4.1 |
| tokio | ^1 |
| tracing-subscriber | ^0.3.20 |
| tracing-test | ^0.2.5 |
| cfg_aliases | ^0.2.1 |