Struct libp2p_kad::Kademlia

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

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_names(&self) -> &[Cow<'static, [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) -> QueryIdwhere
    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_closest_local_peers<'a, K: Clone>(
    &'a mut self,
    key: &'a Key<K>
) -> impl Iterator<Item = Key<PeerId>> + 'a

Returns closest peers to the given key; takes peers from local routing table only.

pub fn get_record(&mut self, key: Key) -> 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
) -> QueryIdwhere
    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 needs to 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, there is no automatic storing of records performed, and this method must be used to ensure the standard Kademlia procedure of “caching” (i.e. storing) a found record at the closest node to the key that did not return it.

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 ConnectionHandler = 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::ConnectionHandler

Creates a new ConnectionHandler 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 on_connection_handler_event(
    &mut self,
    source: PeerId,
    connection: ConnectionId,
    event: KademliaHandlerEvent<QueryId>
)

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

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

Polls for things that swarm should do.

fn on_swarm_event(&mut self, event: FromSwarm<'_, Self::ConnectionHandler>)

Informs the behaviour about an event from the Swarm.

fn inject_connection_established(
    &mut self,
    peer_id: &PeerId,
    connection_id: &ConnectionId,
    endpoint: &ConnectedPoint,
    failed_addresses: Option<&Vec<Multiaddr, Global>>,
    other_established: usize
)

👎Deprecated since 0.40.2: Handle FromSwarm::ConnectionEstablished in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

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

fn inject_connection_closed(
    &mut self,
    peer_id: &PeerId,
    connection_id: &ConnectionId,
    endpoint: &ConnectedPoint,
    handler: <Self::ConnectionHandler as IntoConnectionHandler>::Handler,
    remaining_established: usize
)

👎Deprecated since 0.40.2: Handle FromSwarm::ConnectionClosed in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

Informs the behaviour about a closed connection to a peer.

fn inject_address_change(
    &mut self,
    peer_id: &PeerId,
    connection_id: &ConnectionId,
    old: &ConnectedPoint,
    new: &ConnectedPoint
)

👎Deprecated since 0.40.2: Handle FromSwarm::AddressChange in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

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

fn inject_event(
    &mut self,
    peer_id: PeerId,
    connection: ConnectionId,
    event: <<Self::ConnectionHandler as IntoConnectionHandler>::Handler as ConnectionHandler>::OutEvent
)

👎Deprecated since 0.40.2: Implement NetworkBehaviour::on_connection_handler_event instead. The default implementation of this inject_* method delegates to it.

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

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

👎Deprecated since 0.40.2: Handle InEvent::DialFailure in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

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

fn inject_listen_failure(
    &mut self,
    local_addr: &Multiaddr,
    send_back_addr: &Multiaddr,
    handler: Self::ConnectionHandler
)

👎Deprecated since 0.40.2: Handle FromSwarm::ListenFailure in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

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

fn inject_new_listener(&mut self, id: ListenerId)

👎Deprecated since 0.40.2: Handle FromSwarm::NewListener in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

Indicates to the behaviour that a new listener was created.

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

👎Deprecated since 0.40.2: Handle FromSwarm::NewListenAddr in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

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

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

👎Deprecated since 0.40.2: Handle FromSwarm::ExpiredListenAddr in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

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

fn inject_listener_error(&mut self, id: ListenerId, err: &(dyn Error + 'static))

👎Deprecated since 0.40.2: Handle FromSwarm::ListenerError in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

A listener experienced an error.

fn inject_listener_closed(&mut self, id: ListenerId, reason: Result<(), &Error>)

👎Deprecated since 0.40.2: Handle FromSwarm::ListenerClosed in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

A listener closed.

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

👎Deprecated since 0.40.2: Handle FromSwarm::NewExternalAddr in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

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

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

👎Deprecated since 0.40.2: Handle FromSwarm::ExpiredExternalAddr in NetworkBehaviour::on_swarm_event instead. The default implementation of this inject_* method delegates to it.

Indicates to the behaviour that an external address was removed.