Struct discv5::Discv5

pub struct Discv5<P = DefaultProtocolId>
where
    P: ProtocolIdentity,
{ /* private fields */ }

The main Discv5 Service struct. This provides the user-level API for performing queries and interacting with the underlying service.

Implementations

impl<P: ProtocolIdentity> Discv5<P>

pub fn new( local_enr: Enr, enr_key: CombinedKey, config: Config ) -> Result<Self, &'static str>

pub async fn start(&mut self) -> Result<(), Error>

Starts the required tasks and begins listening on a given UDP SocketAddr.

pub fn shutdown(&mut self)

Terminates the service.

pub fn add_enr(&self, enr: Enr) -> Result<(), &'static str>

Adds a known ENR of a peer participating in Service to the routing table.

This allows pre-populating the Kademlia routing table with known addresses, so that they can be used immediately in following DHT operations involving one of these peers, without having to dial them upfront.

pub fn remove_node(&self, node_id: &NodeId) -> bool

Removes a node_id from the routing table.

This allows applications, for whatever reason, to remove nodes from the local routing table. Returns true if the node was in the table and false otherwise.

pub fn nodes_by_distance(&self, distances: Vec<u64>) -> Vec<Enr>

Returns a vector of closest nodes by the given distances.

pub fn disconnect_node(&self, node_id: &NodeId) -> bool

Mark a node in the routing table as Disconnected.

A Disconnected node will be present in the routing table and will be only used if there are no other Connected peers in the bucket. Returns true if node was in table and false otherwise.

pub fn connected_peers(&self) -> usize

Returns the number of connected peers that exist in the routing table.

pub fn metrics(&self) -> Metrics

Gets the metrics associated with the Server

pub fn raw_metrics() -> &'static METRICS

Exposes the raw reference to the underlying internal metrics.

pub fn local_enr(&self) -> Enr

Returns the local ENR of the node.

pub fn external_enr(&self) -> Arc<RwLock<Enr>>

Identical to Discv5::local_enr except that this exposes the Arc itself.

This is useful for synchronising views of the local ENR outside of Discv5.

pub fn kbuckets(&self) -> KBucketsTable<NodeId, Enr>

Returns the routing table of the discv5 service

pub fn find_enr(&self, node_id: &NodeId) -> Option<Enr>

Returns an ENR if one is known for the given NodeId.

pub fn send_ping( &self, enr: Enr ) -> impl Future<Output = Result<Pong, RequestError>> + 'static

Sends a PING request to a node.

pub fn ban_node(&self, node_id: &NodeId, duration_of_ban: Option<Duration>)

Bans a node from the server. This will remove the node from the routing table if it exists and block all incoming packets from the node until the timeout specified. Setting the timeout to None creates a permanent ban.

pub fn ban_node_remove(&self, node_id: &NodeId)

Removes a banned node from the banned list.

pub fn permit_node(&self, node_id: &NodeId)

Permits a node, allowing the node to bypass the packet filter.

pub fn permit_node_remove(&self, node_id: &NodeId)

Removes a node from the permit list.

pub fn ban_ip(&self, ip: IpAddr, duration_of_ban: Option<Duration>)

Bans an IP from the server. This will block all incoming packets from the IP.

pub fn ban_ip_remove(&self, ip: &IpAddr)

Removes a banned IP from the banned list.

pub fn permit_ip(&self, ip: IpAddr)

Permits an IP, allowing the all packets from the IP to bypass the packet filter.

pub fn permit_ip_remove(&self, ip: &IpAddr)

Removes an IP from the permit list.

pub fn update_local_enr_socket( &self, socket_addr: SocketAddr, is_tcp: bool ) -> bool

Updates the local ENR TCP/UDP socket.

pub fn enr_insert<T: Encodable>( &self, key: &str, value: &T ) -> Result<Option<Vec<u8>>, EnrError>

Allows application layer to insert an arbitrary field into the local ENR.

pub fn table_entries_id(&self) -> Vec<NodeId>

Returns an iterator over all ENR node IDs of nodes currently contained in the routing table.

pub fn table_entries_enr(&self) -> Vec<Enr>

Returns an iterator over all the ENR’s of nodes currently contained in the routing table.

pub fn table_entries(&self) -> Vec<(NodeId, Enr, NodeStatus)>

Returns an iterator over all the entries in the routing table.

pub fn with_kbuckets<F, T>(&self, f: F) -> T

where F: FnOnce(&Arc<RwLock<KBucketsTable<NodeId, Enr>>>) -> T,

Takes a closure parameterized by type Arc<RwLock<KBucketsTable<NodeId, Enr>>> as parameter. Caution: caller is responsible of dropping a lock taken on the kbuckets. For example, a read lock can be taken on the kbuckets to optimistically view the current keys in the kbuckets (optimistic since it doesn’t apply pending entries, which requires a write lock).

use std::str::FromStr;
use discv5::{ConfigBuilder, Discv5, ListenConfig, Enr, enr::CombinedKey};

let sk = CombinedKey::generate_secp256k1();
let enr = Enr::builder().build(&sk).unwrap();
let config = ConfigBuilder::new(ListenConfig::default()).build();
let discv5: Discv5 = Discv5::new(enr, sk, config).unwrap();

let entries =  discv5.with_kbuckets(|kbuckets| kbuckets
    .read()
    .iter_ref()
    .map(|entry| *entry.node.key.preimage())
    .collect::<Vec<_>>());

pub fn talk_req( &self, enr: Enr, protocol: Vec<u8>, request: Vec<u8> ) -> impl Future<Output = Result<Vec<u8>, RequestError>> + 'static

Request a TALK message from a node, identified via the ENR.

pub fn find_node_designated_peer( &self, enr: Enr, distances: Vec<u64> ) -> impl Future<Output = Result<Vec<Enr>, RequestError>> + 'static

Send a FINDNODE request for nodes that fall within the given set of distances, to the designated peer and wait for a response.

pub fn find_node( &self, target_node: NodeId ) -> impl Future<Output = Result<Vec<Enr>, QueryError>> + 'static

Runs an iterative FIND_NODE request.

This will return peers containing contactable nodes of the DHT closest to the requested NodeId.

Note: The async syntax is forgone here in order to create 'static futures, where the underlying sending channel is cloned.

pub fn find_node_predicate( &self, target_node: NodeId, predicate: Box<dyn Fn(&Enr) -> bool + Send>, target_peer_no: usize ) -> impl Future<Output = Result<Vec<Enr>, QueryError>> + 'static

Starts a FIND_NODE request.

This will return less than or equal to num_nodes ENRs which satisfy the predicate.

The predicate is a boxed function that takes an ENR reference and returns a boolean indicating if the record is applicable to the query or not.

Note: The async syntax is forgone here in order to create 'static futures, where the underlying sending channel is cloned.

Example

 let predicate = Box::new(|enr: &Enr| enr.ip().is_some());
 let target = NodeId::random();
 let result = discv5.find_node_predicate(target, predicate, 5).await;

pub fn event_stream( &self ) -> impl Future<Output = Result<Receiver<Event>, Error>> + 'static

Creates an event stream channel which can be polled to receive Discv5 events.

Trait Implementations

impl<P: ProtocolIdentity> Drop for Discv5<P>

fn drop(&mut self)

Executes the destructor for this type.