From f40144dc27e7c100240e503952b7c09c62d3b26f Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?=E2=80=9Cramfox=E2=80=9D?= <“kasey@n0.computer”> Date: Fri, 6 Dec 2024 17:37:36 -0500 Subject: [PATCH 1/4] add "Getting Started" section to the README and add the readme to the docs --- README.md | 54 ++++++++++++++++++++++++++++++++++++++++++++++++++++++ src/lib.rs | 1 + 2 files changed, 55 insertions(+) diff --git a/README.md b/README.md index 88678606..b6b7ce9b 100644 --- a/README.md +++ b/README.md @@ -29,6 +29,60 @@ the whole store with all replicas to a single file. [paper]: https://arxiv.org/abs/2212.13567 +# Getting Started + +The entry into the `iroh-docs` protocol is the `Docs` struct, which uses an [`Engine`](https://docs.rs/iroh-docs/latest/iroh_docs/engine/struct.Engine.html) to power the protocol. + +`Docs` was designed to be used in conjunction with `iroh`. [Iroh](https://docs.rs/iroh) is a networking library for making direct connections, these connections are peers send sync messages and transfer data. + +Iroh provides a [`Router`](https://docs.rs/iroh/latest/iroh/protocol/struct.Router.html) that takes an [`Endpoint`](https://docs.rs/iroh/latest/iroh/endpoint/struct.Endpoint.html) 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`](https://docs.rs/iroh-blobs) and [`iroh-gossip`](https://docs.rs/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`: + +```rust +use iroh::{protocol::Router, Endpoint}; +use iroh_blobs::{net_protocol::Blobs, util::local_pool::LocalPool, ALPN as BLOBS_ALPN}; +use iroh_gossip::{net::Gossip, ALPN as GOSSIP_ALPN}; +use iroh_docs::{protocol::Docs, ALPN as DOCS_ALPN}; + +#[tokio::main] +async fn main() -> Result<(), std::fmt::Error> { + // create an iroh endpoint that includes the standard discovery mechanisms + // we've built at number0 + let endpoint = Endpoint::builder().discovery_n0().bind().await.unwrap(); + + // create a router builder, we will add the + // protocols to this builder and then spawn + // the router + let builder = Router::builder(endpoint); + + // build the blobs protocol + let local_pool = LocalPool::default(); + let blobs = Blobs::memory().build(local_pool.handle(), builder.endpoint()); + + // build the gossip protocol + let gossip = Gossip::builder().spawn(builder.endpoint().clone()).await.unwrap(); + + // build the docs protocol + let docs = Docs::memory().spawn(blobs.clone(), gossip.clone()).await.unwrap(); + + // setup router + let router = builder + .accept(BLOBS_ALPN, blobs) + .accept(GOSSIP_ALPN, gossip)) + .accept(DOCS_ALPN, docs.clone()) + .spawn() + .await + .unwrap(); + + // do fun stuff with docs! + + Ok(()) +} + +``` # License diff --git a/src/lib.rs b/src/lib.rs index f5ee94de..e4dc865f 100644 --- a/src/lib.rs +++ b/src/lib.rs @@ -1,3 +1,4 @@ +#![doc = include_str!("../README.md")] //! Multi-dimensional key-value documents with an efficient synchronization protocol //! //! The crate operates on [Replicas](Replica). A replica contains an unlimited number of From 6a1d95b89323f9ec9f09bd6d115daa0aec58d457 Mon Sep 17 00:00:00 2001 From: Ruediger Klaehn Date: Wed, 11 Dec 2024 11:35:33 +0200 Subject: [PATCH 2/4] Duplicate example in examples and correct README.md --- README.md | 19 ++++++++----------- examples/setup.rs | 39 +++++++++++++++++++++++++++++++++++++++ 2 files changed, 47 insertions(+), 11 deletions(-) create mode 100644 examples/setup.rs diff --git a/README.md b/README.md index b6b7ce9b..1d0f6ee0 100644 --- a/README.md +++ b/README.md @@ -44,14 +44,14 @@ Here is a basic example of how to set up `iroh-docs` with `iroh`: ```rust use iroh::{protocol::Router, Endpoint}; use iroh_blobs::{net_protocol::Blobs, util::local_pool::LocalPool, ALPN as BLOBS_ALPN}; -use iroh_gossip::{net::Gossip, ALPN as GOSSIP_ALPN}; use iroh_docs::{protocol::Docs, ALPN as DOCS_ALPN}; +use iroh_gossip::{net::Gossip, ALPN as GOSSIP_ALPN}; #[tokio::main] -async fn main() -> Result<(), std::fmt::Error> { +async fn main() -> anyhow::Result<()> { // create an iroh endpoint that includes the standard discovery mechanisms // we've built at number0 - let endpoint = Endpoint::builder().discovery_n0().bind().await.unwrap(); + let endpoint = Endpoint::builder().discovery_n0().bind().await?; // create a router builder, we will add the // protocols to this builder and then spawn @@ -63,25 +63,22 @@ async fn main() -> Result<(), std::fmt::Error> { let blobs = Blobs::memory().build(local_pool.handle(), builder.endpoint()); // build the gossip protocol - let gossip = Gossip::builder().spawn(builder.endpoint().clone()).await.unwrap(); + let gossip = Gossip::builder().spawn(builder.endpoint().clone()).await?; // build the docs protocol - let docs = Docs::memory().spawn(blobs.clone(), gossip.clone()).await.unwrap(); + let docs = Docs::memory().spawn(&blobs, &gossip).await?; // setup router let router = builder .accept(BLOBS_ALPN, blobs) - .accept(GOSSIP_ALPN, gossip)) - .accept(DOCS_ALPN, docs.clone()) + .accept(GOSSIP_ALPN, gossip) + .accept(DOCS_ALPN, docs) .spawn() - .await - .unwrap(); + .await?; // do fun stuff with docs! - Ok(()) } - ``` # License diff --git a/examples/setup.rs b/examples/setup.rs new file mode 100644 index 00000000..3d98ec20 --- /dev/null +++ b/examples/setup.rs @@ -0,0 +1,39 @@ +use iroh::{protocol::Router, Endpoint}; +use iroh_blobs::{net_protocol::Blobs, util::local_pool::LocalPool, 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::builder().discovery_n0().bind().await?; + + // create a router builder, we will add the + // protocols to this builder and then spawn + // the router + let builder = Router::builder(endpoint); + + // build the blobs protocol + let local_pool = LocalPool::default(); + let blobs = Blobs::memory().build(local_pool.handle(), builder.endpoint()); + + // build the gossip protocol + let gossip = Gossip::builder().spawn(builder.endpoint().clone()).await?; + + // build the docs protocol + let docs = Docs::memory().spawn(&blobs, &gossip).await?; + + // setup router + let router = builder + .accept(BLOBS_ALPN, blobs) + .accept(GOSSIP_ALPN, gossip) + .accept(DOCS_ALPN, docs) + .spawn() + .await?; + + // do fun stuff with docs! + drop(router); + + Ok(()) +} From b4344901e4cfc85e8dcbe029be5fc6a03437decd Mon Sep 17 00:00:00 2001 From: Ruediger Klaehn Date: Wed, 11 Dec 2024 11:45:57 +0200 Subject: [PATCH 3/4] add deny exemption so we can continue --- deny.toml | 1 + 1 file changed, 1 insertion(+) diff --git a/deny.toml b/deny.toml index 6f93301f..472c0f24 100644 --- a/deny.toml +++ b/deny.toml @@ -34,6 +34,7 @@ license-files = [ ignore = [ "RUSTSEC-2024-0370", # unmaintained, no upgrade available "RUSTSEC-2024-0384", # unmaintained, no upgrade available + "RUSTSEC-2024-0421", # todo: remove when iroh gets updated ] [sources] From 47324f48047152e510bc51ec9053dff3944c4189 Mon Sep 17 00:00:00 2001 From: Ruediger Klaehn Date: Wed, 11 Dec 2024 12:39:45 +0200 Subject: [PATCH 4/4] remove setup example again --- examples/setup.rs | 39 --------------------------------------- 1 file changed, 39 deletions(-) delete mode 100644 examples/setup.rs diff --git a/examples/setup.rs b/examples/setup.rs deleted file mode 100644 index 3d98ec20..00000000 --- a/examples/setup.rs +++ /dev/null @@ -1,39 +0,0 @@ -use iroh::{protocol::Router, Endpoint}; -use iroh_blobs::{net_protocol::Blobs, util::local_pool::LocalPool, 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::builder().discovery_n0().bind().await?; - - // create a router builder, we will add the - // protocols to this builder and then spawn - // the router - let builder = Router::builder(endpoint); - - // build the blobs protocol - let local_pool = LocalPool::default(); - let blobs = Blobs::memory().build(local_pool.handle(), builder.endpoint()); - - // build the gossip protocol - let gossip = Gossip::builder().spawn(builder.endpoint().clone()).await?; - - // build the docs protocol - let docs = Docs::memory().spawn(&blobs, &gossip).await?; - - // setup router - let router = builder - .accept(BLOBS_ALPN, blobs) - .accept(GOSSIP_ALPN, gossip) - .accept(DOCS_ALPN, docs) - .spawn() - .await?; - - // do fun stuff with docs! - drop(router); - - Ok(()) -}