From d752e92b3035e154f6215379775e74dabf6a0cb1 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E5=BC=A0=E7=82=8E=E6=B3=BC?= <drdr.xp@gmail.com>
Date: Sat, 15 Jun 2024 12:30:00 +0800
Subject: [PATCH] Doc: ensure connection to the correct node

---
 .../cluster_control/dynamic-membership.md     | 26 ++++++++++++++++++-
 .../docs/getting_started/getting-started.md   |  6 +++++
 openraft/src/network/v1/network.rs            |  4 +++
 openraft/src/network/v2/network.rs            |  3 +++
 4 files changed, 38 insertions(+), 1 deletion(-)

diff --git a/openraft/src/docs/cluster_control/dynamic-membership.md b/openraft/src/docs/cluster_control/dynamic-membership.md
index ed2aa49d0..1b210578f 100644
--- a/openraft/src/docs/cluster_control/dynamic-membership.md
+++ b/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`
diff --git a/openraft/src/docs/getting_started/getting-started.md b/openraft/src/docs/getting_started/getting-started.md
index a1d7348ac..9475f6c0f 100644
--- a/openraft/src/docs/getting_started/getting-started.md
+++ b/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`
\ No newline at end of file
diff --git a/openraft/src/network/v1/network.rs b/openraft/src/network/v1/network.rs
index 58f31c739..c9a4e726c 100644
--- a/openraft/src/network/v1/network.rs
+++ b/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
diff --git a/openraft/src/network/v2/network.rs b/openraft/src/network/v2/network.rs
index 56e1e7d8c..1f5cece13 100644
--- a/openraft/src/network/v2/network.rs
+++ b/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