Trait Discovery

Source

pub trait Discovery:
    Debug
    + Send
    + Sync {
    // Provided methods
    fn publish(&self, _info: &AddrInfo) { ... }
    fn resolve(
        &self,
        _endpoint: Endpoint,
        _node_id: NodeId,
    ) -> Option<BoxStream<Result<DiscoveryItem>>> { ... }
    fn subscribe(&self) -> Option<BoxStream<DiscoveryItem>> { ... }
}

Expand description

Node discovery for super::Endpoint.

This trait defines publishing and resolving addressing information for a NodeId. This enables connecting to other nodes with only knowing the NodeId, by using this Discovery system to look up the actual addressing information. It is common for implementations to require each node to publish their own information before it can be looked up by other nodes.

The published addressing information can include both a RelayUrl and/or direct addresses.

To allow for discovery, the super::Endpoint will call publish whenever discovery information changes. If a discovery mechanism requires a periodic refresh, it should start its own task.

Provided Methods§

Source

fn publish(&self, _info: &AddrInfo)

Publishes the given AddrInfo to the discovery mechanism.

This is fire and forget, since the Endpoint can not wait for successful publishing. If publishing is async, the implementation should start it’s own task.

This will be called from a tokio task, so it is safe to spawn new tasks. These tasks will be run on the runtime of the super::Endpoint.

Source

fn resolve( &self, _endpoint: Endpoint, _node_id: NodeId, ) -> Option<BoxStream<Result<DiscoveryItem>>>

Resolves the AddrInfo for the given NodeId.

Once the returned BoxStream is dropped, the service should stop any pending work.

Subscribe to all addresses that get passively discovered.

An implementation may choose to defer emitting passively discovered nodes until the stream is actually polled. To avoid missing discovered nodes, poll the stream as soon as possible.

If you do not regularly poll the stream, you may miss discovered nodes.

Any discovery systems that only discover when explicitly resolving a specific NodeId do not need to implement this method. Any nodes or addresses that are discovered by calling resolve should NOT be added to the subscribe stream.

Discovery systems that are capable of receiving information about NodeIds and their AddrInfos without explicitly calling resolve, i.e., systems that do “passive” discovery, should implement this method. If subscribe is called multiple times, the passively discovered addresses should be sent on all streams.

The crate::endpoint::Endpoint will subscribe to the discovery system and add the discovered addresses to the internal address book as they arrive on this stream.