feat: Put RaftNetworkV2 impl for RaftNetwork behind a feature

Make the default implementation `impl<T: RaftNetwork> RaftNetworkV2 for T`
optional via the new feature flag `adapt-network-v1`. This prevents conflicts
when applications implement `RaftNetworkV2` generically, while still providing
an upgrade path for applications transitioning from `RaftNetwork` to
`RaftNetworkV2`.

Author: maackle

openraft/Cargo.toml

@@ -42,7 +42,7 @@ serde_json         = { workspace = true }
 
 
 [features]
-default = ["tokio-rt"]
+default = ["tokio-rt", "adapt-network-v1"]
 
 # Enable the default Tokio runtime
 tokio-rt = ["dep:tokio"]
@@ -74,6 +74,12 @@ type-alias = []
 # Provide basic compatible types
 compat = []
 
+# Enable this feature to automatically implement `RaftNetworkV2` for `RaftNetworkV1` implementations.
+# This helps to migrate to `RaftNetworkV2` without changing your existing implementation.
+# However, if this is enabled, the blanket implementation of `RaftNetworkV2` may result in
+# conflicting implementations in certain cases.
+adapt-network-v1 = []
+
 # Disallows applications to share a raft instance with multiple threads.
 singlethreaded = ["openraft-macros/singlethreaded"]
 

openraft/src/docs/getting_started/getting-started.md

@@ -233,6 +233,19 @@ When the server receives a Raft RPC, it simply passes it to its `raft` instance
 For a real-world implementation, you may want to use [Tonic gRPC](https://github.com/hyperium/tonic) to handle gRPC-based communication between Raft nodes. The [databend-meta](https://github.com/databendlabs/databend/blob/6603392a958ba8593b1f4b01410bebedd484c6a9/metasrv/src/network.rs#L89) project provides an excellent real-world example of a Tonic gRPC-based Raft network implementation.
 
 
+Note: when implementing `RaftNetworkV2<T>` where `T` is a supertype of `RaftTypeConfig` (for instance, `impl<T: MySuperType> RaftNetworkV2<T> for YourNetworkType<T>`), the compiler may complain with the following error:
+
+```text
+conflicting implementations of trait `RaftNetworkV2<_>` for type `YourNetworkType<_>`
+conflicting implementation in crate `openraft`:
+- impl<C, V1> RaftNetworkV2<C> for V1
+  where C: RaftTypeConfig, V1: RaftNetwork<C>, <C as RaftTypeConfig>::SnapshotData: tokio::io::async_read::AsyncRead, <C as RaftTypeConfig>::SnapshotData: tokio::io::async_write::AsyncWrite, <C as RaftTypeConfig>::SnapshotData: tokio::io::async_seek::AsyncSeek, <C as RaftTypeConfig>::SnapshotData: Unpin;
+downstream crates may implement trait `openraft::RaftNetwork<_>` for type `YourNetworkType<_>`
+```
+
+If so, you will want to disable the feature `adapt-network-v1`, which will remove forward compatibility for V1 implementations, but will also fix this error.
+
+
 ### Implement [`RaftNetworkFactory`].
 
 [`RaftNetworkFactory`] is a singleton responsible for creating [`RaftNetworkV2`] instances for each replication target node.

openraft/src/network/v2/mod.rs

@@ -1,4 +1,4 @@
-#[cfg(feature = "tokio-rt")]
+#[cfg(all(feature = "tokio-rt", feature = "adapt-network-v1"))]
 mod adapt_v1;
 mod network;