Struct AddressBook 

pub struct AddressBook { /* private fields */ }

Manage node information, bootstraps and their associated transport addresses and topics.

Example

To help an application to bootstrap into the network, it is possible to manually add node information and manage associated topics for nodes directly on the address book using AddressBook::insert_node_info:

let address_book = AddressBook::builder().spawn().await?;

let bootstrap_node = {
    let node_id = "c0f3ce745cee96e1e9c01a20746cd503bb2199c2459d8ff8697f5edb30569101"
        .parse()
        .expect("valid hex-encoded Ed25519 public key");
    let relay_url = "https://my.relay.org".parse().expect("valid relay url");

    let endpoint_addr = iroh::EndpointAddr::new(node_id)
       .with_relay_url(relay_url);

    NodeInfo::from(endpoint_addr).bootstrap()
};

address_book.insert_node_info(bootstrap_node).await?;

Topic Discovery and Resolving Transport Info

The address book itself is populated with transport information and associated node topics by two “discovery” services:

1. MdnsDiscovery: Resolve addresses of nearby devices on the local-area network.
2. Discovery: Resolve addresses and confidentially exchange topics using random-walk strategy, exploring the network.

Implementations

impl AddressBook

pub fn builder() -> Builder

pub async fn node_info( &self, node_id: NodeId, ) -> Result<Option<NodeInfo>, AddressBookError>

Returns information about a node.

Returns None if no information was found for this node.

pub async fn insert_node_info( &self, node_info: NodeInfo, ) -> Result<bool, AddressBookError>

Inserts or updates node information into address book.

Use this method if adding node information from a local configuration or trusted, external source, etc.

Returns true if entry got newly inserted or false if existing entry was updated. Previous entries are simply overwritten. Entries with attached transport information get checked against authenticity and throw an error otherwise.

pub async fn insert_transport_info( &self, node_id: NodeId, transport_info: TransportInfo, ) -> Result<bool, AddressBookError>

Inserts or updates attached transport info for a node. Use this method if adding transport information from an untrusted source.

Transport information is usually exchanged as part of a discovery protocol and should be considered untrusted.

This method checks if the given information is authentic and uses a timestamp to apply a “last write wins” rule. It retuns true if the given entry overwritten the previous one or false if the previous entry is already the latest.

Local data of the node information stay untouched if they already exist, only the “transports” aspect gets inserted / updated.

pub async fn node_infos_by_topics( &self, topics: impl IntoIterator<Item = TopicId>, ) -> Result<Vec<NodeInfo>, AddressBookError>

pub async fn set_topics( &self, node_id: NodeId, topics: impl IntoIterator<Item = TopicId>, ) -> Result<(), AddressBookError>

pub async fn add_topic( &self, node_id: NodeId, topic: TopicId, ) -> Result<(), AddressBookError>

pub async fn remove_topic( &self, node_id: NodeId, topic: TopicId, ) -> Result<(), AddressBookError>

pub async fn watch_node_info( &self, node_id: NodeId, updates_only: UpdatesOnly, ) -> Result<WatcherReceiver<Option<NodeInfo>>, AddressBookError>

Subscribes to channel informing us about node info changes for a specific node.

pub async fn watch_topic( &self, topic_id: TopicId, updates_only: UpdatesOnly, ) -> Result<WatcherReceiver<HashSet<NodeId>>, AddressBookError>

Subscribes to channel informing us about changes of the set of nodes interested in a topic.

pub async fn watch_node_topics( &self, node_id: NodeId, updates_only: UpdatesOnly, ) -> Result<WatcherReceiver<HashSet<TopicId>>, AddressBookError>

Subscribes to channel informing us about topic changes for a particular node.

pub async fn report( &self, node_id: NodeId, connection_outcome: ConnectionOutcome, ) -> Result<(), AddressBookError>

Report outcomes of incoming or outgoing connections.

This helps measuring the “quality” of nodes which will be recorded in the address book.

Trait Implementations

impl ChildActor for AddressBook

fn on_start( &self, supervisor: ActorCell, thread_pool: ThreadLocalActorSpawner, ) -> ChildActorFut<'_>

impl Clone for AddressBook

fn clone(&self) -> AddressBook

Returns a duplicate of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.