feat(kad): remove deprecated public modules

This patch removes the 3 out of 4 deprecated public modules. I've left `store` for now because we made some mistakes in declaring that. The items within `store` still need to be publicly visible but I haven't yet figured out a good way of exporting / naming them. Thus, I've left that to a follow-up PR.

Related: #3647.

Pull-Request: #3896.

Author: thomaseizinger

misc/metrics/src/identify.rs

@@ -148,7 +148,7 @@ impl super::Recorder<libp2p_identify::Event> for Metrics {
                                 libp2p_identify::PROTOCOL_NAME,
                                 libp2p_identify::PUSH_PROTOCOL_NAME,
                                 #[cfg(feature = "kad")]
-                                libp2p_kad::protocol::DEFAULT_PROTO_NAME,
+                                libp2p_kad::PROTOCOL_NAME,
                                 #[cfg(feature = "ping")]
                                 libp2p_ping::PROTOCOL_NAME,
                                 #[cfg(feature = "relay")]

protocols/kad/CHANGELOG.md

@@ -3,7 +3,11 @@
 - Raise MSRV to 1.65.
   See [PR 3715].
 
+- Remove deprecated public modules `handler`, `protocol` and `kbucket`.
+  See [PR 3896].
+
 [PR 3715]: https://github.com/libp2p/rust-libp2p/pull/3715
+[PR 3896]: https://github.com/libp2p/rust-libp2p/pull/3896
 
 ## 0.43.3
 

protocols/kad/src/behaviour.rs

@@ -22,7 +22,7 @@
 
 use super::*;
 
-use crate::kbucket_priv::Distance;
+use crate::kbucket::Distance;
 use crate::record_priv::{store::MemoryStore, Key};
 use crate::{K_VALUE, SHA_256_MH};
 use futures::{executor::block_on, future::poll_fn, prelude::*};
@@ -234,10 +234,10 @@ fn bootstrap() {
 
 #[test]
 fn query_iter() {
-    fn distances<K>(key: &kbucket_priv::Key<K>, peers: Vec<PeerId>) -> Vec<Distance> {
+    fn distances<K>(key: &kbucket::Key<K>, peers: Vec<PeerId>) -> Vec<Distance> {
         peers
             .into_iter()
-            .map(kbucket_priv::Key::from)
+            .map(kbucket::Key::from)
             .map(|k| k.distance(key))
             .collect()
     }
@@ -253,7 +253,7 @@ fn query_iter() {
         // Ask the first peer in the list to search a random peer. The search should
         // propagate forwards through the list of peers.
         let search_target = PeerId::random();
-        let search_target_key = kbucket_priv::Key::from(search_target);
+        let search_target_key = kbucket::Key::from(search_target);
         let qid = swarms[0].behaviour_mut().get_closest_peers(search_target);
 
         match swarms[0].behaviour_mut().query(&qid) {
@@ -290,7 +290,7 @@ fn query_iter() {
                             assert_eq!(swarm_ids[i], expected_swarm_id);
                             assert_eq!(swarm.behaviour_mut().queries.size(), 0);
                             assert!(expected_peer_ids.iter().all(|p| ok.peers.contains(p)));
-                            let key = kbucket_priv::Key::new(ok.key);
+                            let key = kbucket::Key::new(ok.key);
                             assert_eq!(expected_distances, distances(&key, ok.peers));
                             return Poll::Ready(());
                         }
@@ -653,17 +653,17 @@ fn put_record() {
                 assert_eq!(r.expires, expected.expires);
                 assert_eq!(r.publisher, Some(*swarms[0].local_peer_id()));
 
-                let key = kbucket_priv::Key::new(r.key.clone());
+                let key = kbucket::Key::new(r.key.clone());
                 let mut expected = swarms
                     .iter()
                     .skip(1)
                     .map(Swarm::local_peer_id)
                     .cloned()
                     .collect::<Vec<_>>();
                 expected.sort_by(|id1, id2| {
-                    kbucket_priv::Key::from(*id1)
+                    kbucket::Key::from(*id1)
                         .distance(&key)
-                        .cmp(&kbucket_priv::Key::from(*id2).distance(&key))
+                        .cmp(&kbucket::Key::from(*id2).distance(&key))
                 });
 
                 let expected = expected
@@ -992,11 +992,11 @@ fn add_provider() {
                     .map(Swarm::local_peer_id)
                     .cloned()
                     .collect::<Vec<_>>();
-                let kbucket_key = kbucket_priv::Key::new(key);
+                let kbucket_key = kbucket::Key::new(key);
                 expected.sort_by(|id1, id2| {
-                    kbucket_priv::Key::from(*id1)
+                    kbucket::Key::from(*id1)
                         .distance(&kbucket_key)
-                        .cmp(&kbucket_priv::Key::from(*id2).distance(&kbucket_key))
+                        .cmp(&kbucket::Key::from(*id2).distance(&kbucket_key))
                 });
 
                 let expected = expected

protocols/kad/src/behaviour/test.rs

@@ -84,7 +84,7 @@ const NUM_BUCKETS: usize = 256;
 
 /// A `KBucketsTable` represents a Kademlia routing table.
 #[derive(Debug, Clone)]
-pub struct KBucketsTable<TKey, TVal> {
+pub(crate) struct KBucketsTable<TKey, TVal> {
     /// The key identifying the local peer that owns the routing table.
     local_key: TKey,
     /// The buckets comprising the routing table.
@@ -154,7 +154,7 @@ where
     /// The given `pending_timeout` specifies the duration after creation of
     /// a [`PendingEntry`] after which it becomes eligible for insertion into
     /// a full bucket, replacing the least-recently (dis)connected node.
-    pub fn new(local_key: TKey, pending_timeout: Duration) -> Self {
+    pub(crate) fn new(local_key: TKey, pending_timeout: Duration) -> Self {
         KBucketsTable {
             local_key,
             buckets: (0..NUM_BUCKETS)
@@ -165,13 +165,13 @@ where
     }
 
     /// Returns the local key.
-    pub fn local_key(&self) -> &TKey {
+    pub(crate) fn local_key(&self) -> &TKey {
         &self.local_key
     }
 
     /// Returns an `Entry` for the given key, representing the state of the entry
     /// in the routing table.
-    pub fn entry<'a>(&'a mut self, key: &'a TKey) -> Entry<'a, TKey, TVal> {
+    pub(crate) fn entry<'a>(&'a mut self, key: &'a TKey) -> Entry<'a, TKey, TVal> {
         let index = BucketIndex::new(&self.local_key.as_ref().distance(key));
         if let Some(i) = index {
             let bucket = &mut self.buckets[i.get()];
@@ -188,7 +188,7 @@ where
     ///
     /// The buckets are ordered by proximity to the `local_key`, i.e. the first
     /// bucket is the closest bucket (containing at most one key).
-    pub fn iter(&mut self) -> impl Iterator<Item = KBucketRef<'_, TKey, TVal>> + '_ {
+    pub(crate) fn iter(&mut self) -> impl Iterator<Item = KBucketRef<'_, TKey, TVal>> + '_ {
         let applied_pending = &mut self.applied_pending;
         self.buckets.iter_mut().enumerate().map(move |(i, b)| {
             if let Some(applied) = b.apply_pending() {
@@ -204,7 +204,7 @@ where
     /// Returns the bucket for the distance to the given key.
     ///
     /// Returns `None` if the given key refers to the local key.
-    pub fn bucket<K>(&mut self, key: &K) -> Option<KBucketRef<'_, TKey, TVal>>
+    pub(crate) fn bucket<K>(&mut self, key: &K) -> Option<KBucketRef<'_, TKey, TVal>>
     where
         K: AsRef<KeyBytes>,
     {
@@ -232,13 +232,16 @@ where
     /// buckets are updated accordingly. The fact that a pending entry was applied is
     /// recorded in the `KBucketsTable` in the form of `AppliedPending` results, which must be
     /// consumed by calling this function.
-    pub fn take_applied_pending(&mut self) -> Option<AppliedPending<TKey, TVal>> {
+    pub(crate) fn take_applied_pending(&mut self) -> Option<AppliedPending<TKey, TVal>> {
         self.applied_pending.pop_front()
     }
 
     /// Returns an iterator over the keys closest to `target`, ordered by
     /// increasing distance.
-    pub fn closest_keys<'a, T>(&'a mut self, target: &'a T) -> impl Iterator<Item = TKey> + 'a
+    pub(crate) fn closest_keys<'a, T>(
+        &'a mut self,
+        target: &'a T,
+    ) -> impl Iterator<Item = TKey> + 'a
     where
         T: AsRef<KeyBytes>,
     {
@@ -256,7 +259,7 @@ where
 
     /// Returns an iterator over the nodes closest to the `target` key, ordered by
     /// increasing distance.
-    pub fn closest<'a, T>(
+    pub(crate) fn closest<'a, T>(
         &'a mut self,
         target: &'a T,
     ) -> impl Iterator<Item = EntryView<TKey, TVal>> + 'a
@@ -286,7 +289,7 @@ where
     ///
     /// The number of nodes between the local node and the target are
     /// calculated by backtracking from the target towards the local key.
-    pub fn count_nodes_between<T>(&mut self, target: &T) -> usize
+    pub(crate) fn count_nodes_between<T>(&mut self, target: &T) -> usize
     where
         T: AsRef<KeyBytes>,
     {
@@ -460,7 +463,7 @@ where
     }
 }
 
-/// A reference to a bucket in a [`KBucketsTable`].
+/// A reference to a bucket.
 pub struct KBucketRef<'a, TKey, TVal> {
     index: BucketIndex,
     bucket: &'a mut KBucket<TKey, TVal>,
@@ -471,7 +474,7 @@ where
     TKey: Clone + AsRef<KeyBytes>,
     TVal: Clone,
 {
-    /// Returns the minimum inclusive and maximum inclusive [`Distance`] for
+    /// Returns the minimum inclusive and maximum inclusive distance for
     /// this bucket.
     pub fn range(&self) -> (Distance, Distance) {
         self.index.range()

protocols/kad/src/handler_priv.rs renamed to protocols/kad/src/handler.rs

@@ -26,8 +26,7 @@
 //! > of the `KBucketsTable` and in particular the public `Entry` API.
 
 use super::*;
-pub use crate::K_VALUE;
-
+pub(crate) use crate::K_VALUE;
 /// A `PendingNode` is a `Node` that is pending insertion into a `KBucket`.
 #[derive(Debug, Clone)]
 pub(crate) struct PendingNode<TKey, TVal> {
@@ -130,7 +129,7 @@ pub(crate) struct KBucket<TKey, TVal> {
 /// The result of inserting an entry into a bucket.
 #[must_use]
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub enum InsertResult<TKey> {
+pub(crate) enum InsertResult<TKey> {
     /// The entry has been successfully inserted.
     Inserted,
     /// The entry is pending insertion because the relevant bucket is currently full.
@@ -152,12 +151,12 @@ pub enum InsertResult<TKey> {
 /// The result of applying a pending node to a bucket, possibly
 /// replacing an existing node.
 #[derive(Debug, Clone, PartialEq, Eq)]
-pub struct AppliedPending<TKey, TVal> {
+pub(crate) struct AppliedPending<TKey, TVal> {
     /// The key of the inserted pending node.
-    pub inserted: Node<TKey, TVal>,
+    pub(crate) inserted: Node<TKey, TVal>,
     /// The node that has been evicted from the bucket to make room for the
     /// pending node, if any.
-    pub evicted: Option<Node<TKey, TVal>>,
+    pub(crate) evicted: Option<Node<TKey, TVal>>,
 }
 
 impl<TKey, TVal> KBucket<TKey, TVal>

protocols/kad/src/kbucket_priv.rs renamed to protocols/kad/src/kbucket.rs

@@ -21,7 +21,7 @@
 //! The `Entry` API for quering and modifying the entries of a `KBucketsTable`
 //! representing the nodes participating in the Kademlia DHT.
 
-pub use super::bucket::{AppliedPending, InsertResult, Node, NodeStatus, K_VALUE};
+pub(crate) use super::bucket::{AppliedPending, InsertResult, Node, NodeStatus, K_VALUE};
 pub use super::key::*;
 
 use super::*;
@@ -74,7 +74,7 @@ impl<TKey: AsRef<KeyBytes>, TVal> AsRef<KeyBytes> for EntryView<TKey, TVal> {
 
 /// A reference into a single entry of a `KBucketsTable`.
 #[derive(Debug)]
-pub enum Entry<'a, TPeerId, TVal> {
+pub(crate) enum Entry<'a, TPeerId, TVal> {
     /// The entry is present in a bucket.
     Present(PresentEntry<'a, TPeerId, TVal>, NodeStatus),
     /// The entry is pending insertion in a bucket.
@@ -115,7 +115,7 @@ where
     ///
     /// Returns `None` if the entry is neither present in a bucket nor
     /// pending insertion into a bucket.
-    pub fn view(&'a mut self) -> Option<EntryRefView<'a, TKey, TVal>> {
+    pub(crate) fn view(&'a mut self) -> Option<EntryRefView<'a, TKey, TVal>> {
         match self {
             Entry::Present(entry, status) => Some(EntryRefView {
                 node: NodeRefView {
@@ -140,7 +140,7 @@ where
     /// Returns `None` if the `Key` used to construct this `Entry` is not a valid
     /// key for an entry in a bucket, which is the case for the `local_key` of
     /// the `KBucketsTable` referring to the local node.
-    pub fn key(&self) -> Option<&TKey> {
+    pub(crate) fn key(&self) -> Option<&TKey> {
         match self {
             Entry::Present(entry, _) => Some(entry.key()),
             Entry::Pending(entry, _) => Some(entry.key()),
@@ -153,7 +153,7 @@ where
     ///
     /// Returns `None` if the entry is absent from any bucket or refers to the
     /// local node.
-    pub fn value(&mut self) -> Option<&mut TVal> {
+    pub(crate) fn value(&mut self) -> Option<&mut TVal> {
         match self {
             Entry::Present(entry, _) => Some(entry.value()),
             Entry::Pending(entry, _) => Some(entry.value()),
@@ -165,8 +165,7 @@ where
 
 /// An entry present in a bucket.
 #[derive(Debug)]
-pub struct PresentEntry<'a, TKey, TVal>(EntryRef<'a, TKey, TVal>);
-
+pub(crate) struct PresentEntry<'a, TKey, TVal>(EntryRef<'a, TKey, TVal>);
 impl<'a, TKey, TVal> PresentEntry<'a, TKey, TVal>
 where
     TKey: Clone + AsRef<KeyBytes>,
@@ -177,12 +176,12 @@ where
     }
 
     /// Returns the key of the entry.
-    pub fn key(&self) -> &TKey {
+    pub(crate) fn key(&self) -> &TKey {
         self.0.key
     }
 
     /// Returns the value associated with the key.
-    pub fn value(&mut self) -> &mut TVal {
+    pub(crate) fn value(&mut self) -> &mut TVal {
         &mut self
             .0
             .bucket
@@ -192,12 +191,12 @@ where
     }
 
     /// Sets the status of the entry to the provided [`NodeStatus`].
-    pub fn update(&mut self, status: NodeStatus) {
+    pub(crate) fn update(&mut self, status: NodeStatus) {
         self.0.bucket.update(self.0.key, status);
     }
 
     /// Removes the entry from the bucket.
-    pub fn remove(self) -> EntryView<TKey, TVal> {
+    pub(crate) fn remove(self) -> EntryView<TKey, TVal> {
         let (node, status, _pos) = self
             .0
             .bucket
@@ -209,8 +208,7 @@ where
 
 /// An entry waiting for a slot to be available in a bucket.
 #[derive(Debug)]
-pub struct PendingEntry<'a, TKey, TVal>(EntryRef<'a, TKey, TVal>);
-
+pub(crate) struct PendingEntry<'a, TKey, TVal>(EntryRef<'a, TKey, TVal>);
 impl<'a, TKey, TVal> PendingEntry<'a, TKey, TVal>
 where
     TKey: Clone + AsRef<KeyBytes>,
@@ -221,12 +219,12 @@ where
     }
 
     /// Returns the key of the entry.
-    pub fn key(&self) -> &TKey {
+    pub(crate) fn key(&self) -> &TKey {
         self.0.key
     }
 
     /// Returns the value associated with the key.
-    pub fn value(&mut self) -> &mut TVal {
+    pub(crate) fn value(&mut self) -> &mut TVal {
         self.0
             .bucket
             .pending_mut()
@@ -235,13 +233,13 @@ where
     }
 
     /// Updates the status of the pending entry.
-    pub fn update(self, status: NodeStatus) -> PendingEntry<'a, TKey, TVal> {
+    pub(crate) fn update(self, status: NodeStatus) -> PendingEntry<'a, TKey, TVal> {
         self.0.bucket.update_pending(status);
         PendingEntry::new(self.0.bucket, self.0.key)
     }
 
     /// Removes the pending entry from the bucket.
-    pub fn remove(self) -> EntryView<TKey, TVal> {
+    pub(crate) fn remove(self) -> EntryView<TKey, TVal> {
         let pending = self.0.bucket.remove_pending().expect(
             "We can only build a PendingEntry if the entry is pending insertion
                     into the bucket; QED",
@@ -254,8 +252,7 @@ where
 
 /// An entry that is not present in any bucket.
 #[derive(Debug)]
-pub struct AbsentEntry<'a, TKey, TVal>(EntryRef<'a, TKey, TVal>);
-
+pub(crate) struct AbsentEntry<'a, TKey, TVal>(EntryRef<'a, TKey, TVal>);
 impl<'a, TKey, TVal> AbsentEntry<'a, TKey, TVal>
 where
     TKey: Clone + AsRef<KeyBytes>,
@@ -266,12 +263,12 @@ where
     }
 
     /// Returns the key of the entry.
-    pub fn key(&self) -> &TKey {
+    pub(crate) fn key(&self) -> &TKey {
         self.0.key
     }
 
     /// Attempts to insert the entry into a bucket.
-    pub fn insert(self, value: TVal, status: NodeStatus) -> InsertResult<TKey> {
+    pub(crate) fn insert(self, value: TVal, status: NodeStatus) -> InsertResult<TKey> {
         self.0.bucket.insert(
             Node {
                 key: self.0.key.clone(),