Struct libp2p_kad::Kademlia

pub struct Kademlia<TStore> { /* fields omitted */ }

Kademlia is a NetworkBehaviour that implements the libp2p Kademlia protocol.

Implementations

impl<TStore> Kademlia<TStore> where
    for<'a> TStore: RecordStore<'a>,
    TStore: Send + 'static, 

pub fn new(id: PeerId, store: TStore) -> Self

Creates a new Kademlia network behaviour with a default configuration.

pub fn protocol_name(&self) -> &[u8]

Get the protocol name of this kademlia instance.

pub fn with_config(id: PeerId, store: TStore, config: KademliaConfig) -> Self

Creates a new Kademlia network behaviour with the given configuration.

pub fn iter_queries(&self) -> impl Iterator<Item = QueryRef<'_>>

Gets an iterator over immutable references to all running queries.

pub fn iter_queries_mut(&mut self) -> impl Iterator<Item = QueryMut<'_>>

Gets an iterator over mutable references to all running queries.

pub fn query(&self, id: &QueryId) -> Option<QueryRef<'_>>

Gets an immutable reference to a running query, if it exists.

pub fn query_mut<'a>(&'a mut self, id: &QueryId) -> Option<QueryMut<'a>>

Gets a mutable reference to a running query, if it exists.

pub fn add_address(
    &mut self,
    peer: &PeerId,
    address: Multiaddr
) -> RoutingUpdate

Adds a known listen address of a peer participating in the DHT to the routing table.

Explicitly adding addresses of peers serves two purposes:

1. In order for a node to join the DHT, it must know about at least one other node of the DHT.

2. When a remote peer initiates a connection and that peer is not yet in the routing table, the Kademlia behaviour must be informed of an address on which that peer is listening for connections before it can be added to the routing table from where it can subsequently be discovered by all peers in the DHT.

If the routing table has been updated as a result of this operation, a KademliaEvent::RoutingUpdated event is emitted.

pub fn remove_address(
    &mut self,
    peer: &PeerId,
    address: &Multiaddr
) -> Option<EntryView<Key<PeerId>, Addresses>>

Removes an address of a peer from the routing table.

If the given address is the last address of the peer in the routing table, the peer is removed from the routing table and Some is returned with a view of the removed entry. The same applies if the peer is currently pending insertion into the routing table.

If the given peer or address is not in the routing table, this is a no-op.

pub fn remove_peer(
    &mut self,
    peer: &PeerId
) -> Option<EntryView<Key<PeerId>, Addresses>>

Removes a peer from the routing table.

Returns None if the peer was not in the routing table, not even pending insertion.

pub fn kbuckets(
    &mut self
) -> impl Iterator<Item = KBucketRef<'_, Key<PeerId>, Addresses>>

Returns an iterator over all non-empty buckets in the routing table.

pub fn kbucket<K>(
    &mut self,
    key: K
) -> Option<KBucketRef<'_, Key<PeerId>, Addresses>> where
    K: Into<Key<K>> + Clone, 

Returns the k-bucket for the distance to the given key.

Returns None if the given key refers to the local key.

pub fn get_closest_peers<K>(&mut self, key: K) -> QueryId where
    K: Into<Key<K>> + Into<Vec<u8>> + Clone, 

Initiates an iterative query for the closest peers to the given key.

The result of the query is delivered in a [KademliaEvent::OutboundQueryCompleted{QueryResult::GetClosestPeers}].

pub fn get_record(&mut self, key: &Key, quorum: Quorum) -> QueryId

Performs a lookup for a record in the DHT.

The result of this operation is delivered in a [KademliaEvent::OutboundQueryCompleted{QueryResult::GetRecord}].

pub fn put_record(
    &mut self,
    record: Record,
    quorum: Quorum
) -> Result<QueryId, Error>

Stores a record in the DHT, locally as well as at the nodes closest to the key as per the xor distance metric.

Returns Ok if a record has been stored locally, providing the QueryId of the initial query that replicates the record in the DHT. The result of the query is eventually reported as a [KademliaEvent::OutboundQueryCompleted{QueryResult::PutRecord}].

The record is always stored locally with the given expiration. If the record’s expiration is None, the common case, it does not expire in local storage but is still replicated with the configured record TTL. To remove the record locally and stop it from being re-published in the DHT, see Kademlia::remove_record.

After the initial publication of the record, it is subject to (re-)replication and (re-)publication as per the configured intervals. Periodic (re-)publication does not update the record’s expiration in local storage, thus a given record with an explicit expiration will always expire at that instant and until then is subject to regular (re-)replication and (re-)publication.

pub fn put_record_to<I>(
    &mut self,
    record: Record,
    peers: I,
    quorum: Quorum
) -> QueryId where
    I: ExactSizeIterator<Item = PeerId>, 

Stores a record at specific peers, without storing it locally.

The given Quorum is understood in the context of the total number of distinct peers given.

If the record’s expiration is None, the configured record TTL is used.

Note: This is not a regular Kademlia DHT operation. It may be used to selectively update or store a record to specific peers for the purpose of e.g. making sure these peers have the latest “version” of a record or to “cache” a record at further peers to increase the lookup success rate on the DHT for other peers.

In particular, if lookups are performed with a quorum > 1 multiple possibly different records may be returned and the standard Kademlia procedure of “caching” (i.e. storing) a found record at the closest node to the key that did not return it cannot be employed transparently. In that case, client code can explicitly choose which record to store at which peers for analogous write-back caching or for other reasons.

pub fn remove_record(&mut self, key: &Key)

Removes the record with the given key from local storage, if the local node is the publisher of the record.

Has no effect if a record for the given key is stored locally but the local node is not a publisher of the record.

This is a local operation. However, it also has the effect that the record will no longer be periodically re-published, allowing the record to eventually expire throughout the DHT.

pub fn store_mut(&mut self) -> &mut TStore

Gets a mutable reference to the record store.

pub fn bootstrap(&mut self) -> Result<QueryId, NoKnownPeers>

Bootstraps the local node to join the DHT.

Bootstrapping is a multi-step operation that starts with a lookup of the local node’s own ID in the DHT. This introduces the local node to the other nodes in the DHT and populates its routing table with the closest neighbours.

Subsequently, all buckets farther from the bucket of the closest neighbour are refreshed by initiating an additional bootstrapping query for each such bucket with random keys.

Returns Ok if bootstrapping has been initiated with a self-lookup, providing the QueryId for the entire bootstrapping process. The progress of bootstrapping is reported via [KademliaEvent::OutboundQueryCompleted{QueryResult::Bootstrap}] events, with one such event per bootstrapping query.

Returns Err if bootstrapping is impossible due an empty routing table.

Note: Bootstrapping requires at least one node of the DHT to be known. See Kademlia::add_address.

pub fn start_providing(&mut self, key: Key) -> Result<QueryId, Error>

Establishes the local node as a provider of a value for the given key.

This operation publishes a provider record with the given key and identity of the local node to the peers closest to the key, thus establishing the local node as a provider.

Returns Ok if a provider record has been stored locally, providing the QueryId of the initial query that announces the local node as a provider.

The publication of the provider records is periodically repeated as per the configured interval, to renew the expiry and account for changes to the DHT topology. A provider record may be removed from local storage and thus no longer re-published by calling Kademlia::stop_providing.

In contrast to the standard Kademlia push-based model for content distribution implemented by Kademlia::put_record, the provider API implements a pull-based model that may be used in addition or as an alternative. The means by which the actual value is obtained from a provider is out of scope of the libp2p Kademlia provider API.

The results of the (repeated) provider announcements sent by this node are reported via [KademliaEvent::OutboundQueryCompleted{QueryResult::StartProviding}].

pub fn stop_providing(&mut self, key: &Key)

Stops the local node from announcing that it is a provider for the given key.

This is a local operation. The local node will still be considered as a provider for the key by other nodes until these provider records expire.

pub fn get_providers(&mut self, key: Key) -> QueryId

Performs a lookup for providers of a value to the given key.

The result of this operation is delivered in a reported via [KademliaEvent::OutboundQueryCompleted{QueryResult::GetProviders}].

Trait Implementations

impl<TStore> NetworkBehaviour for Kademlia<TStore> where
    for<'a> TStore: RecordStore<'a>,
    TStore: Send + 'static, 

type ProtocolsHandler = KademliaHandlerProto<QueryId>

Handler for all the protocols the network behaviour supports.

type OutEvent = KademliaEvent

Event generated by the NetworkBehaviour and that the swarm will report back.

fn new_handler(&mut self) -> Self::ProtocolsHandler

Creates a new ProtocolsHandler for a connection with a peer.

fn addresses_of_peer(&mut self, peer_id: &PeerId) -> Vec<Multiaddr>

Addresses that this behaviour is aware of for this specific peer, and that may allow reaching the peer.

fn inject_connection_established(
    &mut self,
    peer_id: &PeerId,
    _: &ConnectionId,
    _: &ConnectedPoint,
    errors: Option<&Vec<Multiaddr>>
)

Informs the behaviour about a newly established connection to a peer.

fn inject_connected(&mut self, peer: &PeerId)

Indicate to the behaviour that we connected to the node with the given peer id.

fn inject_address_change(
    &mut self,
    peer: &PeerId,
    _: &ConnectionId,
    old: &ConnectedPoint,
    new: &ConnectedPoint
)

Informs the behaviour that the ConnectedPoint of an existing connection has changed.

fn inject_dial_failure(
    &mut self,
    peer_id: Option<PeerId>,
    _: Self::ProtocolsHandler,
    error: &DialError
)

Indicates to the behaviour that the dial to a known or unknown node failed.

fn inject_disconnected(&mut self, id: &PeerId)

Indicates to the behaviour that we disconnected from the node with the given peer id.

fn inject_event(
    &mut self,
    source: PeerId,
    connection: ConnectionId,
    event: KademliaHandlerEvent<QueryId>
)

Informs the behaviour about an event generated by the handler dedicated to the peer identified by peer_id. for the behaviour.

fn inject_new_listen_addr(&mut self, _id: ListenerId, addr: &Multiaddr)

Indicates to the behaviour that we have started listening on a new multiaddr.

fn inject_expired_listen_addr(&mut self, _id: ListenerId, addr: &Multiaddr)

Indicates to the behaviour that a multiaddr we were listening on has expired, which means that we are no longer listening in it.

fn inject_new_external_addr(&mut self, addr: &Multiaddr)

Indicates to the behaviour that we have discovered a new external address for us.

fn poll(
    &mut self,
    cx: &mut Context<'_>,
    parameters: &mut impl PollParameters
) -> Poll<NetworkBehaviourAction<Self::OutEvent, Self::ProtocolsHandler>>

Polls for things that swarm should do.

fn inject_connection_closed(
    &mut self,
    &PeerId,
    &ConnectionId,
    &ConnectedPoint,
    <Self::ProtocolsHandler as IntoProtocolsHandler>::Handler
)

Informs the behaviour about a closed connection to a peer.

fn inject_listen_failure(
    &mut self,
    _local_addr: &Multiaddr,
    _send_back_addr: &Multiaddr,
    _handler: Self::ProtocolsHandler
)

Indicates to the behaviour that an error happened on an incoming connection during its initial handshake.

fn inject_new_listener(&mut self, _id: ListenerId)

Indicates to the behaviour that a new listener was created.

fn inject_listener_error(
    &mut self,
    _id: ListenerId,
    _err: &(dyn Error + 'static)
)

A listener experienced an error.

fn inject_listener_closed(
    &mut self,
    _id: ListenerId,
    _reason: Result<(), &Error>
)

A listener closed.

fn inject_expired_external_addr(&mut self, _addr: &Multiaddr)

Indicates to the behaviour that an external address was removed.