iroh-gossip (0.101.0)
Installation
[registries.forgejo]
index = "sparse+cargo add iroh-gossip@0.101.0 --registry forgejoAbout this package
iroh-gossip
This crate implements the iroh-gossip protocol.
It is based on epidemic broadcast trees to disseminate messages among a swarm of peers interested in a topic.
The implementation is based on the papers HyParView and PlumTree.
The crate is made up from two modules:
The proto module is the protocol implementation, as a state machine without any IO.
The net module implements networking logic for running iroh-gossip on iroh connections.
The net module is optional behind the net feature flag (enabled by default).
Getting Started
The iroh-gossip protocol was designed to be used in conjunction with iroh. Iroh is a networking library for making direct connections, these connections are how gossip messages are sent.
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.
Here is a basic example of how to set up iroh-gossip with iroh:
use iroh::{protocol::Router, Endpoint, EndpointId, endpoint::presets};
use iroh_gossip::{api::Event, Gossip, TopicId};
use n0_error::{Result, StdResultExt};
use n0_future::StreamExt;
#[tokio::main]
async fn main() -> Result<()> {
// create an iroh endpoint that includes the standard discovery mechanisms
// we've built at number0
let endpoint = Endpoint::bind(presets::N0).await?;
// build gossip protocol
let gossip = Gossip::builder().spawn(endpoint.clone());
// setup router
let router = Router::builder(endpoint)
.accept(iroh_gossip::ALPN, gossip.clone())
.spawn();
// gossip swarms are centered around a shared "topic id", which is a 32 byte identifier
let topic_id = TopicId::from_bytes([23u8; 32]);
// and you need some bootstrap peers to join the swarm
let bootstrap_peers = bootstrap_peers();
// then, you can subscribe to the topic and join your initial peers
let (sender, mut receiver) = gossip
.subscribe(topic_id, bootstrap_peers)
.await?
.split();
// you might want to wait until you joined at least one other peer:
receiver.joined().await?;
// then, you can broadcast messages to all other peers!
sender.broadcast(b"hello world this is a gossip message".to_vec().into()).await?;
// and read messages from others!
while let Some(event) = receiver.next().await {
match event? {
Event::Received(message) => {
println!("received a message: {:?}", std::str::from_utf8(&message.content));
}
_ => {}
}
}
// clean shutdown makes sure that other peers are notified that you went offline
router.shutdown().await.std_context("shutdown router")?;
Ok(())
}
fn bootstrap_peers() -> Vec<EndpointId> {
// insert your bootstrap peers here, or get them from your environment
vec![]
}
License
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 |
|---|---|
| blake3 | ^1.8 |
| bytes | ^1.7 |
| clap | ^4 |
| comfy-table | ^7.1.4 |
| data-encoding | ^2.6.0 |
| derive_more | ^2.0.1 |
| futures-concurrency | ^7.6.1 |
| hex | ^0.4.3 |
| humantime-serde | ^1.1.1 |
| indexmap | ^2.0 |
| iroh | ^1 |
| iroh-base | ^1 |
| iroh-metrics | ^1.0.1 |
| irpc | ^0.17.0 |
| n0-error | ^1 |
| n0-future | ^0.3 |
| noq | ^1 |
| postcard | ^1 |
| rand | ^0.10.1 |
| rayon | ^1.10.0 |
| serde | ^1.0.164 |
| serde_json | ^1 |
| tokio | ^1 |
| tokio-util | ^0.7.12 |
| toml | ^1.1.2 |
| tracing | ^0.1 |
| tracing-subscriber | ^0.3 |
| clap | ^4 |
| humantime-serde | ^1.1.1 |
| iroh | ^1 |
| n0-tracing-test | ^0.3 |
| rand | ^0.10 |
| serde-byte-array | ^0.1.2 |
| testresult | ^0.4.1 |
| tokio | ^1 |
| tracing-subscriber | ^0.3.20 |
| url | ^2.4.0 |