Crate iroh_gossip

Crate iroh_gossip 

Source
Expand description

§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};
use iroh_gossip::{api::Event, Gossip, TopicId};
use n0_future::StreamExt;
use n0_snafu::ResultExt;

#[tokio::main]
async fn main() -> n0_snafu::Result<()> {
    // create an iroh endpoint that includes the standard discovery mechanisms
    // we've built at number0
    let endpoint = Endpoint::bind().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.e()?;
    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

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. Broadcast messages to peers subscribed to a topic

The crate is designed to be used from the iroh crate, which provides a high level interface, but can also be used standalone.

Re-exports§

pub use net::Gossip;net
pub use proto::TopicId;

Modules§

apinet or rpc
Public API for using iroh-gossip
metrics
Metrics for iroh-gossip
netnet
Networking for the iroh-gossip protocol
proto
Implementation of the iroh-gossip protocol, as an IO-less state machine

Constants§

ALPNnet
ALPN protocol name