feat(kad): make implementation modules private

Similar to #3494, make implementation modules private for Kademlia (`kad`).

Resolves #3608.

Pull-Request: #3738.

.github/workflows/ci.yml

@@ -62,6 +62,8 @@ jobs:
       - name: Check if we compile without any features activated
         run: cargo build --package ${{ matrix.crate }} --no-default-features
 
+      - run: cargo clean
+
       - name: Check if crate has been released
         id: check-released
         run: |

protocols/kad/CHANGELOG.md

@@ -1,8 +1,10 @@
 ## 0.43.2 - unreleased
 
 - Export pub enum `RoutingUpdate`. See [PR 3739].
+- Deprecate `handler`, `kbucket`, `protocol`, `record` modules to make them private. See [PR 3738].
 
 [PR 3739]: https://github.com/libp2p/rust-libp2p/pull/3739
+[PR 3738]: https://github.com/libp2p/rust-libp2p/pull/3738
 
 ## 0.43.1
 

protocols/kad/src/behaviour/test.rs

@@ -22,8 +22,8 @@
 
 use super::*;
 
-use crate::kbucket::Distance;
-use crate::record::{store::MemoryStore, Key};
+use crate::kbucket_priv::Distance;
+use crate::record_priv::{store::MemoryStore, Key};
 use crate::{K_VALUE, SHA_256_MH};
 use futures::{executor::block_on, future::poll_fn, prelude::*};
 use futures_timer::Delay;
@@ -234,10 +234,10 @@ fn bootstrap() {
 
 #[test]
 fn query_iter() {
-    fn distances<K>(key: &kbucket::Key<K>, peers: Vec<PeerId>) -> Vec<Distance> {
+    fn distances<K>(key: &kbucket_priv::Key<K>, peers: Vec<PeerId>) -> Vec<Distance> {
         peers
             .into_iter()
-            .map(kbucket::Key::from)
+            .map(kbucket_priv::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::Key::from(search_target);
+        let search_target_key = kbucket_priv::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::Key::new(ok.key);
+                            let key = kbucket_priv::Key::new(ok.key);
                             assert_eq!(expected_distances, distances(&key, ok.peers));
                             return Poll::Ready(());
                         }
@@ -445,7 +445,7 @@ fn get_record_not_found() {
         .map(|(_addr, swarm)| swarm)
         .collect::<Vec<_>>();
 
-    let target_key = record::Key::from(random_multihash());
+    let target_key = record_priv::Key::from(random_multihash());
     let qid = swarms[0].behaviour_mut().get_record(target_key.clone());
 
     block_on(poll_fn(move |ctx| {
@@ -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::Key::new(r.key.clone());
+                let key = kbucket_priv::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::Key::from(*id1)
+                    kbucket_priv::Key::from(*id1)
                         .distance(&key)
-                        .cmp(&kbucket::Key::from(*id2).distance(&key))
+                        .cmp(&kbucket_priv::Key::from(*id2).distance(&key))
                 });
 
                 let expected = expected
@@ -862,7 +862,7 @@ fn get_record_many() {
 /// network where X is equal to the configured replication factor.
 #[test]
 fn add_provider() {
-    fn prop(keys: Vec<record::Key>, seed: Seed) {
+    fn prop(keys: Vec<record_priv::Key>, seed: Seed) {
         let mut rng = StdRng::from_seed(seed.0);
         let replication_factor =
             NonZeroUsize::new(rng.gen_range(1..(K_VALUE.get() / 2) + 1)).unwrap();
@@ -992,11 +992,11 @@ fn add_provider() {
                     .map(Swarm::local_peer_id)
                     .cloned()
                     .collect::<Vec<_>>();
-                let kbucket_key = kbucket::Key::new(key);
+                let kbucket_key = kbucket_priv::Key::new(key);
                 expected.sort_by(|id1, id2| {
-                    kbucket::Key::from(*id1)
+                    kbucket_priv::Key::from(*id1)
                         .distance(&kbucket_key)
-                        .cmp(&kbucket::Key::from(*id2).distance(&kbucket_key))
+                        .cmp(&kbucket_priv::Key::from(*id2).distance(&kbucket_key))
                 });
 
                 let expected = expected
@@ -1379,7 +1379,7 @@ fn network_behaviour_on_address_change() {
 
 #[test]
 fn get_providers_single() {
-    fn prop(key: record::Key) {
+    fn prop(key: record_priv::Key) {
         let (_, mut single_swarm) = build_node();
         single_swarm
             .behaviour_mut()
@@ -1432,7 +1432,7 @@ fn get_providers_single() {
 }
 
 fn get_providers_limit<const N: usize>() {
-    fn prop<const N: usize>(key: record::Key) {
+    fn prop<const N: usize>(key: record_priv::Key) {
         let mut swarms = build_nodes(3);
 
         // Let first peer know of second peer and second peer know of third peer.

protocols/kad/src/handler.rs → protocols/kad/src/handler_priv.rs

@@ -22,7 +22,7 @@ use crate::protocol::{
     KadInStreamSink, KadOutStreamSink, KadPeer, KadRequestMsg, KadResponseMsg,
     KademliaProtocolConfig,
 };
-use crate::record::{self, Record};
+use crate::record_priv::{self, Record};
 use either::Either;
 use futures::prelude::*;
 use futures::stream::SelectAll;
@@ -255,7 +255,7 @@ pub enum KademliaHandlerEvent<TUserData> {
     /// this key.
     GetProvidersReq {
         /// The key for which providers are requested.
-        key: record::Key,
+        key: record_priv::Key,
         /// Identifier of the request. Needs to be passed back when answering.
         request_id: KademliaRequestId,
     },
@@ -281,15 +281,15 @@ pub enum KademliaHandlerEvent<TUserData> {
     /// The peer announced itself as a provider of a key.
     AddProvider {
         /// The key for which the peer is a provider of the associated value.
-        key: record::Key,
+        key: record_priv::Key,
         /// The peer that is the provider of the value for `key`.
         provider: KadPeer,
     },
 
     /// Request to get a value from the dht records
     GetRecord {
         /// Key for which we should look in the dht
-        key: record::Key,
+        key: record_priv::Key,
         /// Identifier of the request. Needs to be passed back when answering.
         request_id: KademliaRequestId,
     },
@@ -314,7 +314,7 @@ pub enum KademliaHandlerEvent<TUserData> {
     /// Response to a request to store a record.
     PutRecordRes {
         /// The key of the stored record.
-        key: record::Key,
+        key: record_priv::Key,
         /// The value of the stored record.
         value: Vec<u8>,
         /// The user data passed to the `PutValue`.
@@ -403,7 +403,7 @@ pub enum KademliaHandlerIn<TUserData> {
     /// this key.
     GetProvidersReq {
         /// Identifier being searched.
-        key: record::Key,
+        key: record_priv::Key,
         /// Custom user data. Passed back in the out event when the results arrive.
         user_data: TUserData,
     },
@@ -426,15 +426,15 @@ pub enum KademliaHandlerIn<TUserData> {
     /// succeeded.
     AddProvider {
         /// Key for which we should add providers.
-        key: record::Key,
+        key: record_priv::Key,
         /// Known provider for this key.
         provider: KadPeer,
     },
 
     /// Request to retrieve a record from the DHT.
     GetRecord {
         /// The key of the record.
-        key: record::Key,
+        key: record_priv::Key,
         /// Custom data. Passed back in the out event when the results arrive.
         user_data: TUserData,
     },
@@ -459,7 +459,7 @@ pub enum KademliaHandlerIn<TUserData> {
     /// Response to a `PutRecord`.
     PutRecordRes {
         /// Key of the value that was put.
-        key: record::Key,
+        key: record_priv::Key,
         /// Value that was put.
         value: Vec<u8>,
         /// Identifier of the request that was made by the remote.

protocols/kad/src/jobs.rs

@@ -61,7 +61,7 @@
 //! > to the size of all stored records. As a job runs, the records are moved
 //! > out of the job to the consumer, where they can be dropped after being sent.
 
-use crate::record::{self, store::RecordStore, ProviderRecord, Record};
+use crate::record_priv::{self, store::RecordStore, ProviderRecord, Record};
 use futures::prelude::*;
 use futures_timer::Delay;
 use instant::Instant;
@@ -134,7 +134,7 @@ pub struct PutRecordJob {
     next_publish: Option<Instant>,
     publish_interval: Option<Duration>,
     record_ttl: Option<Duration>,
-    skipped: HashSet<record::Key>,
+    skipped: HashSet<record_priv::Key>,
     inner: PeriodicJob<vec::IntoIter<Record>>,
 }
 
@@ -166,7 +166,7 @@ impl PutRecordJob {
 
     /// Adds the key of a record that is ignored on the current or
     /// next run of the job.
-    pub fn skip(&mut self, key: record::Key) {
+    pub fn skip(&mut self, key: record_priv::Key) {
         self.skipped.insert(key);
     }
 
@@ -327,7 +327,7 @@ impl AddProviderJob {
 #[cfg(test)]
 mod tests {
     use super::*;
-    use crate::record::store::MemoryStore;
+    use crate::record_priv::store::MemoryStore;
     use futures::{executor::block_on, future::poll_fn};
     use quickcheck::*;
     use rand::Rng;

protocols/kad/src/kbucket/key.rs → protocols/kad/src/kbucket_priv/key.rs

@@ -18,7 +18,7 @@
 // FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER
 // DEALINGS IN THE SOFTWARE.
 
-use crate::record;
+use crate::record_priv;
 use libp2p_core::multihash::Multihash;
 use libp2p_identity::PeerId;
 use sha2::digest::generic_array::{typenum::U32, GenericArray};
@@ -113,8 +113,8 @@ impl From<Vec<u8>> for Key<Vec<u8>> {
     }
 }
 
-impl From<record::Key> for Key<record::Key> {
-    fn from(k: record::Key) -> Self {
+impl From<record_priv::Key> for Key<record_priv::Key> {
+    fn from(k: record_priv::Key) -> Self {
         Key::new(k)
     }
 }

protocols/kad/src/lib.rs

@@ -38,10 +38,37 @@
 #![allow(dead_code)]
 #![cfg_attr(docsrs, feature(doc_cfg, doc_auto_cfg))]
 
-pub mod handler;
-pub mod kbucket;
-pub mod protocol;
-pub mod record;
+mod handler_priv;
+#[deprecated(
+    note = "The `handler` module will be made private in the future and should not be depended on."
+)]
+pub mod handler {
+    pub use super::handler_priv::*;
+}
+
+mod kbucket_priv;
+#[deprecated(
+    note = "The `kbucket` module will be made private in the future and should not be depended on."
+)]
+pub mod kbucket {
+    pub use super::kbucket_priv::*;
+}
+
+mod protocol_priv;
+#[deprecated(
+    note = "The `protocol` module will be made private in the future and should not be depended on."
+)]
+pub mod protocol {
+    pub use super::protocol_priv::*;
+}
+
+mod record_priv;
+#[deprecated(
+    note = "The `record` module will be made private in the future and should not be depended on."
+)]
+pub mod record {
+    pub use super::record_priv::*;
+}
 
 mod addresses;
 mod behaviour;
@@ -69,9 +96,10 @@ pub use behaviour::{
     Kademlia, KademliaBucketInserts, KademliaCaching, KademliaConfig, KademliaEvent,
     KademliaStoreInserts, ProgressStep, Quorum,
 };
+pub use kbucket_priv::{EntryView, KBucketRef, Key as KBucketKey};
 pub use protocol::KadConnectionType;
 pub use query::QueryId;
-pub use record::{store, ProviderRecord, Record};
+pub use record_priv::{store, Key as RecordKey, ProviderRecord, Record};
 
 use std::num::NonZeroUsize;