docs: refine docs for feature-flag adapt-network-v1

Complete the pseudo code to produce the conflict.
Add doc in the feature-flags section in `docs` crate.
Add link to this feature-flags for `RaftNetworkV2` doc.

Author: drmingdrmer

openraft/Cargo.toml

@@ -74,10 +74,17 @@ type-alias = []
 # Provide basic compatible types
 compat = []
 
-# Enable this feature to automatically implement `RaftNetworkV2` for `RaftNetworkV1` implementations.
+# Enable this feature to automatically implement `RaftNetworkV2` for `RaftNetwork` 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.
+# conflicting if the application tries to implement `RaftNetworkV2<T>` where `T`
+# is a generic type. For example a conflict in application with this feature on:
+# ```
+# pub trait RaftTypeConfigExt: openraft::RaftTypeConfig {}
+# pub struct NetworkConnection2 {}
+# impl<T> RaftNetworkV2<T> for NetworkConnection2
+# where T: RaftTypeConfigExt + Send + Sync + 'static {/*...*/}
+# ```
 adapt-network-v1 = []
 
 # Disallows applications to share a raft instance with multiple threads.
@@ -122,4 +129,4 @@ no-default-features = false
 #
 # Sort modules by appearance order for crate `docs`.
 # https://doc.rust-lang.org/rustdoc/unstable-features.html#--sort-modules-by-appearance-control-how-items-on-module-pages-are-sorted
-# rustdoc-args = ["-Z", "unstable-options", "--sort-modules-by-appearance"]
+# rustdoc-args = ["-Z", "unstable-options", "--sort-modules-by-appearance"]

openraft/src/docs/feature_flags/feature-flags-toc.md

@@ -1,8 +1,10 @@
+- [feature-flag `adapt-network-v1`](#feature-flag-adapt-network-v1)
 - [feature-flag `bench`](#feature-flag-bench)
 - [feature-flag `bt`](#feature-flag-bt)
 - [feature-flag `compat`](#feature-flag-compat)
 - [feature-flag `serde`](#feature-flag-serde)
 - [feature-flag `single-term-leader`](#feature-flag-single-term-leader)
 - [feature-flag `singlethreaded`](#feature-flag-singlethreaded)
+- [feature-flag `tokio-rt`](#feature-flag-tokio-rt)
 - [feature-flag `tracing-log`](#feature-flag-tracing-log)
 - [feature-flag `type-alias`](#feature-flag-type-alias)

openraft/src/docs/feature_flags/feature-flags.md

@@ -1,5 +1,33 @@
 
-By default openraft enables no features.
+By default openraft enables `["tokio-rt", "adapt-network-v1"]`.
+
+
+## feature-flag `adapt-network-v1`
+
+When implementing [`RaftNetworkV2<T>`][`RaftNetworkV2`] for a generic type parameter `T`, you might
+encounter a compiler error about conflicting implementations. This happens
+because Openraft provides a blanket implementation that adapts `RaftNetwork`
+implementations to [`RaftNetworkV2`]. For example:
+
+```rust,ignore
+pub trait RaftTypeConfigExt: openraft::RaftTypeConfig {}
+pub struct YourNetworkType {}
+impl<T: RaftTypeConfigExt> RaftNetworkV2<T> for YourNetworkType {}
+```
+
+You might encounter the following error:
+
+```text
+conflicting implementations of trait `RaftNetworkV2<_>` for type `YourNetworkType`
+conflicting implementation in crate `openraft`:
+- impl<C, V1> RaftNetworkV2<C> for V1
+```
+
+If you encounter this error, you can disable the feature `adapt-network-v1` to
+remvoe the default implementation for [`RaftNetworkV2`].
+
+[`RaftNetworkV2`]: crate::network::v2::RaftNetworkV2
+
 
 ## feature-flag `bench`
 
@@ -35,6 +63,7 @@ Read more about how it is implemented in:
 [`leader_id`](crate::docs::data::leader_id)
 and [`vote`](crate::docs::data::vote).
 
+
 ## feature-flag `singlethreaded`
 
 Removes `Send` and `Sync` bounds from `AppData`, `AppDataResponse`, `RaftEntry`, `SnapshotData`
@@ -45,6 +74,13 @@ If the feature is enabled, affected asynchronous trait methods will not require
 In order to use the feature, `AsyncRuntime::spawn` should invoke `tokio::task::spawn_local` or equivalents.
 
 
+## feature-flag `tokio-rt`
+
+Using `tokio` as the default runtime implementation.
+With this feature disabled, application should implement and set the
+async-runtime to `AsyncRuntime` mannually in [`RaftTypeconfig`] implementation.
+
+
 ## feature-flag `tracing-log`
 
 Enables "log" feature in `tracing` crate, to let tracing events

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

@@ -80,7 +80,7 @@ pub struct TypeConfig {}
 impl openraft::RaftTypeConfig for TypeConfig {
     type D            = Request;
     type R            = Response;
-    
+
     // Following are absent in `declare_raft_types` and filled with default values:
     type NodeId       = u64;
     type Node         = openraft::impls::BasicNode;
@@ -91,7 +91,7 @@ impl openraft::RaftTypeConfig for TypeConfig {
 }
 ```
 
-> In the above `TypeConfig` declaration, 
+> In the above `TypeConfig` declaration,
 > - `NodeId` is the identifier of a node in the cluster, which implements [`NodeId`] trait.
 > - `Node` is the node type that contains the node's address, etc., which implements [`Node`] trait.
 > - `Entry` is the log entry type that will be stored in the raft log,
@@ -233,17 +233,29 @@ 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.
+> ### Trouble shooting: implementation conflicts
+>
+> When implementing `RaftNetworkV2<T>` for a generic type parameter `T`, you might
+> encounter a compiler error about conflicting implementations. This happens
+> because Openraft provides a blanket implementation that adapts `RaftNetwork`
+> implementations to `RaftNetworkV2`. For example:
+>
+> ```rust,ignore
+> pub trait RaftTypeConfigExt: openraft::RaftTypeConfig {}
+> pub struct YourNetworkType {}
+> impl<T: RaftTypeConfigExt> RaftNetworkV2<T> for YourNetworkType {}
+> ```
+>
+> You might encounter the following error:
+>
+> ```text
+> conflicting implementations of trait `RaftNetworkV2<_>` for type `YourNetworkType`
+> conflicting implementation in crate `openraft`:
+> - impl<C, V1> RaftNetworkV2<C> for V1
+> ```
+>
+> If you encounter this error, you can disable the feature `adapt-network-v1` to
+> remvoe the default implementation for `RaftNetworkV2`.
 
 
 ### Implement [`RaftNetworkFactory`].
@@ -416,7 +428,7 @@ Additionally, two test scripts for setting up a cluster are available:
 [`Entry`]:                              `crate::entry::Entry`
 [`docs::Vote`]:                         `crate::docs::data::Vote`
 [`Vote`]:                               `crate::vote::Vote`
-[`LogState`]:                           `crate::storage::LogState` 
+[`LogState`]:                           `crate::storage::LogState`
 
 [`RaftLogReader`]:                      `crate::storage::RaftLogReader`
 [`try_get_log_entries()`]:              `crate::storage::RaftLogReader::try_get_log_entries`

openraft/src/network/v2/network.rs

@@ -35,12 +35,14 @@ use crate::RaftTypeConfig;
 /// and introduces `full_snapshot()` method that let application fully customize snapshot transmit.
 ///
 /// Compatibility: [`RaftNetworkV2`] is automatically implemented for [`RaftNetwork`]
-/// implementations.
+/// implementations. If it conflicts with your application, disable [`adapt-network-v1`] feature
+/// flag.
 ///
 /// [Ensure connection to correct node][correct-node]
 ///
 /// [`RaftNetwork`]: crate::network::v1::RaftNetwork
 /// [correct-node]: `crate::docs::cluster_control::dynamic_membership#ensure-connection-to-the-correct-node`
+/// [`adapt-network-v1`]: `crate::docs::feature_flags#adapt-network-v1`
 #[since(version = "0.10.0")]
 #[add_async_trait]
 pub trait RaftNetworkV2<C>: OptionalSend + OptionalSync + 'static