Doc: ensure connection to the correct node

openraft/src/docs/cluster_control/dynamic-membership.md

@@ -83,7 +83,7 @@ The initial argument should be set to [`ChangeMembers::SetNodes(BTreeMap<NodeId,
 
 ### Brain split
 
-When Updating node network addresses,
+When updating node network addresses,
 brain split could occur if the new address belongs to another node,
 leading to two elected leaders.
 
@@ -116,7 +116,31 @@ should be replaced with `ChangeMembers::RemoveNodes` and `Raft::add_learner` whe
 Do not use `ChangeMembers::SetNodes` unless you know what you are doing.
 
 
+### Ensure connection to the correct node
+
+Ensure that a connection to the right node is the responsibility
+of the [`RaftNetworkFactory`] and the [`RaftNetworkV2`] implementation.
+
+Connecting to a wrong node can lead to data inconsistency and even data loss.
+See: [brain split caused by wrong node address][`docs::brain-split`].
+
+Notably, the implementation should exercise additional care if one of the following conditions is met:
+
+* There is a chance that two cluster nodes have conflicting Node metadata.
+  For example, two nodes with the same hostname are added,
+  or one node is migrated to have the same hostname as another
+
+* The network cannot be trusted.
+  For example, a network adversary is present that might reroute Raft messages intended for one node to another.
+
+
+
 [`ChangeMembers::SetNodes`]: `crate::change_members::ChangeMembers::SetNodes`
 [`Raft::add_learner()`]: `crate::Raft::add_learner`
 [`Raft::change_membership()`]: `crate::Raft::change_membership`
 [`extended_membership`]: `crate::docs::data::extended_membership`
+
+[`RaftNetworkFactory`]:                 `crate::network::RaftNetworkFactory`
+[`RaftNetworkV2`]:                      `crate::network::v2::RaftNetworkV2`
+
+[`docs::brain-split`]:                  `crate::docs::cluster_control::dynamic_membership#brain-split`

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

@@ -253,6 +253,10 @@ Then use `Raft::add_learner(node_id, BasicNode::new("127.0.0.1"), ...)` to instr
 }
 ```
 
+###  Caution: ensure that a connection to the right node
+
+See: [Ensure connection to the correct node][`docs::connect-to-correct-node`]
+
 
 ## 5. Put everything together
 
@@ -419,3 +423,5 @@ Additionally, two test scripts for setting up a cluster are available:
 
 [`StoreBuilder`]:                       `crate::testing::StoreBuilder`
 [`Suite`]:                              `crate::testing::Suite`
+
+[`docs::connect-to-correct-node`]:      `crate::docs::cluster_control::dynamic_membership#ensure-connection-to-the-correct-node`

openraft/src/network/v1/network.rs

@@ -21,6 +21,10 @@ use crate::RaftTypeConfig;
 ///
 /// A single network instance is used to connect to a single target node. The network instance is
 /// constructed by the [`RaftNetworkFactory`](`crate::network::RaftNetworkFactory`).
+///
+/// [Ensure connection to correct node][correct-node]
+///
+/// [correct-node]: `crate::docs::cluster_control::dynamic_membership#ensure-connection-to-the-correct-node`
 #[add_async_trait]
 pub trait RaftNetwork<C>: OptionalSend + OptionalSync + 'static
 where C: RaftTypeConfig

openraft/src/network/v2/network.rs

@@ -35,7 +35,10 @@ use crate::Vote;
 /// Compatibility: [`RaftNetworkV2`] is automatically implemented for [`RaftNetwork`]
 /// implementations.
 ///
+/// [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`
 #[add_async_trait]
 pub trait RaftNetworkV2<C>: OptionalSend + OptionalSync + 'static
 where C: RaftTypeConfig