Feat： Add consistent hash and modulo hash load balance with their con…

…figuration (#158)

.gitignore

@@ -18,3 +18,4 @@ cmake-build-debug/
 build/
 *.pb.h
 *.pb.cc
+

LICENSE

@@ -454,6 +454,56 @@ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLI
 As an exception, if, as a result of your compiling your source code, portions of this Software are embedded into a machine-executable object form of such source code, you may redistribute such embedded portions in such object form without including the above copyright and permission notices.
 
 
+Open Source Software Licensed under the MIT:
+--------------------------------------------------------------------
+1. murmurhash3
+Copyright (C) 2011 - present, Austin Appleby
+
+
+Terms of the MIT:
+--------------------------------------------------------------------
+MurmurHash3 was written by Austin Appleby, and is placed in the public domain. The author hereby disclaims copyright to this source code.
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
+
+
+Open Source Software Licensed under the MIT:
+--------------------------------------------------------------------
+1. city
+Copyright (c) 2011 Google, Inc.
+
+
+Terms of the MIT:
+--------------------------------------------------------------------
+Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN HE SOFTWARE.
+
+CityHash, by Geoff Pike and Jyrki Alakuijala
+
+
+Open Source Software Licensed under the MIT:
+--------------------------------------------------------------------
+1. md5
+Copyright (C) 1991-2, RSA Data Security, Inc
+
+
+Terms of the MIT:
+--------------------------------------------------------------------
+License to copy and use this software is granted provided that it is identified as the "RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material mentioning or referencing this software
+or this function. License is also granted to make and use derivative works provided that such works are identified as "derived from the RSA Data Security, Inc. MD5 Message-Digest Algorithm" in all material mentioning or referencing the derived work.
+
+RSA Data Security, Inc. makes no representations concerning either the merchantability of this software or the suitability of this software for any particular purpose. It is provided "as is"
+without express or implied warranty of any kind.
+
+These notices must be retained in any copies of any part of this
+documentation and/or software.
+
+
 Open Source Software Licensed under the OpenSSL License and the original SSLeay License:
 --------------------------------------------------------------------
 1. openssl

docs/zh/hash_loadbalance.md

@@ -0,0 +1,81 @@
+# 哈希负载均衡插件使用
+
+## 使用哈希负载均衡插件
+
+要使用哈希负载均衡插件，需在yaml配置文件client:service:load_balance_name 下设置哈希负载均衡插件名字，并在plugins:loadbalance下配置对应插件的相关配置。
+
+以下是一个在yaml配置文件使用哈希负载均衡插件的例子。
+
+```
+client:
+  service:
+    - name: trpc.test.helloworld.Greeter
+      target: 127.0.0.1:11111,127.0.0.1:22222,127.0.0.1:33333      # Fullfill ip:port list here when use `direct` selector.(such as 23.9.0.1:90,34.5.6.7:90)
+      protocol: trpc                # Application layer protocol, eg: trpc/http/...
+      network: tcp                  # Network type, Support two types: tcp/udp
+      selector_name: direct         # Selector plugin, default `direct`, it is used when you want to access via ip:port
+      load_balance_name: consistent_hash   
+
+plugins:
+  loadbalance:
+    consistent_hash:
+      hash_nodes: 20		 
+      hash_args: [0]       
+      hash_func: murmur3   
+```
+
+## 默认负载均衡插件
+
+若没有在client端设置load_balance_name, 默认采用轮询负载均衡插件（trpc_polling_load_balance)，轮询负载均衡插件不需要在plugins下进行配置。
+
+## 哈希负载均衡插件
+
+如果用户在client端设置了hash值，将采用用户提供的hash值来进行路由选择。否则将使用插件的配置来生成hash值（生成hash值的函数见 哈希函数使用 章节）
+
+### 一致性哈希负载均衡插件（consistent_hash)
+
+以下配置值为默认值，若没对插件进行配置，将采用下面的默认值
+
+```
+plugins:
+	loadbalance:
+		consistent_hash:
+          hash_nodes: 160		#consistent hash中每个实际节点对应的虚拟节点数量
+          hash_args: [0]       #支持0-5选项，分别对应selectInfo中的信息.0：caller name 1: client ip 2：client port 3:info.name  4: callee name 5: info.loadbalance name
+          hash_func: murmur3  #支持murmur3，city，md5，bkdr，fnv1a
+```
+
+### 取模哈希负载均衡插件（modulo_hash)
+
+以下配置值为默认值，若没对插件进行配置，将采用下面的默认值
+
+```
+plugins:
+	loadbalance:
+        modulo_hash:
+          hash_args: [0]
+          hash_func: murmur3
+```
+
+### 哈希函数使用
+
+在哈希负载均衡插件中使用的哈希函数的定义在文件/trpc/naming/common/util/hash/hash_func.h
+
+文件提供的哈希函数如下：
+
+```
+//input为输入的键，hash_func为选择的hash函数，支持“murmur3”，“city”，“md5”，“bkdr”，“fnv1a”
+//返回64位哈希值
+std::uint64_t Hash(const std::string& input, const std::string& hash_func);
+
+//input为输入的键，hash_func为选择的hash函数，支持“murmur3”，“city”，“md5”，“bkdr”，“fnv1a”，num为模数
+//返回64位取模后的哈希值
+std::uint64_t Hash(const std::string& input, const std::string& hash_func, uint64_t num);
+
+//input为输入的键，hash_func为选择的hash函数，支持HashFuncName::MD5,HashFuncName::BKDR,HashFuncName::CITY,HashFuncName::BKDR,HashFuncName::MURMUR3,HashFuncName::FNV1A
+std::uint64_t Hash(const std::string& input, const HashFuncName& hash_func);
+
+//取模后的哈希值
+std::uint64_t Hash(const std::string& input, const HashFuncName& hash_func,uint64_t num);
+
+```

trpc/common/BUILD

@@ -137,7 +137,7 @@ cc_library(
         "//trpc/util/log/default:default_log",
         "//trpc/util:net_util",
         "//trpc/overload_control:trpc_overload_control",
-        "//trpc/naming/common/util/loadbalance:trpc_load_balance"
+        "//trpc/naming/common/util/loadbalance:trpc_load_balance",
     ] + select({
         "//trpc:trpc_include_rpcz": [
             "//trpc/rpcz:collector",

trpc/common/config/BUILD

@@ -316,6 +316,24 @@ cc_test(
     ],
 )
 
+cc_library(
+    name = "loadbalance_naming_conf",
+    srcs = ["loadbalance_naming_conf.cc"],
+    hdrs = ["loadbalance_naming_conf.h"],
+    deps = [
+        "//trpc/util/log:logging",
+        "@com_github_jbeder_yaml_cpp//:yaml-cpp",
+    ],
+)
+
+cc_library(
+    name = "loadbalance_naming_conf_parser",
+    hdrs = ["loadbalance_naming_conf_parser.h"],
+    deps = [
+        ":loadbalance_naming_conf",
+    ],
+)
+
 cc_library(
     name = "local_file_provider_conf",
     srcs = ["local_file_provider_conf.cc"],

trpc/common/config/loadbalance_naming_conf.cc

@@ -0,0 +1,30 @@
+//
+//
+// Tencent is pleased to support the open source community by making tRPC available.
+//
+// Copyright (C) 2024 THL A29 Limited, a Tencent company.
+// All rights reserved.
+//
+// If you have downloaded a copy of the tRPC source code from Tencent,
+// please note that tRPC source code is licensed under the  Apache 2.0 License,
+// A copy of the Apache 2.0 License is included in this file.
+//
+//
+
+#include "trpc/common/config/loadbalance_naming_conf.h"
+
+#include "trpc/util/log/logging.h"
+
+namespace trpc::naming {
+
+void LoadBalanceConfig::Display() const {
+  TRPC_FMT_DEBUG("-----LoadBalanceSelectorConfig begin-------");
+
+  TRPC_FMT_DEBUG("hash_nodes:{}", hash_nodes);
+  TRPC_FMT_DEBUG("hash_args size:{}", hash_args.size());
+  TRPC_FMT_DEBUG("hash_func:{}", hash_func);
+
+  TRPC_FMT_DEBUG("--------------------------------------");
+}
+
+}  // namespace trpc::naming

trpc/common/config/loadbalance_naming_conf.h

@@ -0,0 +1,36 @@
+//
+//
+// Tencent is pleased to support the open source community by making tRPC available.
+//
+// Copyright (C) 2024 THL A29 Limited, a Tencent company.
+// All rights reserved.
+//
+// If you have downloaded a copy of the tRPC source code from Tencent,
+// please note that tRPC source code is licensed under the  Apache 2.0 License,
+// A copy of the Apache 2.0 License is included in this file.
+//
+//
+
+#pragma once
+
+#include <cstdint>
+#include <string>
+#include <vector>
+
+namespace trpc::naming {
+
+/// @brief loadbalance plugin configuration
+struct LoadBalanceConfig {
+  /// @brief hash node number when consistent hash load balance algorithm is hash
+  uint32_t hash_nodes{160};
+  /// @brief hash content when load balance algorithm is hash,corresponding to SelectInfo
+  /// 0：caller name 1: client ip 2：client port 3:info.name  4: callee name 5: info.loadbalance name
+  std::vector<uint32_t> hash_args{0};
+  /// @brief hash function when load balance algorithm is hash
+  std::string hash_func{"murmur3"};
+
+  /// @brief Print out the logger configuration.
+  void Display() const;
+};
+
+}  // namespace trpc::naming

trpc/common/config/loadbalance_naming_conf_parser.h

@@ -0,0 +1,44 @@
+//
+//
+// Tencent is pleased to support the open source community by making tRPC available.
+//
+// Copyright (C) 2024 THL A29 Limited, a Tencent company.
+// All rights reserved.
+//
+// If you have downloaded a copy of the tRPC source code from Tencent,
+// please note that tRPC source code is licensed under the  Apache 2.0 License,
+// A copy of the Apache 2.0 License is included in this file.
+//
+//
+#pragma once
+
+#include "yaml-cpp/yaml.h"
+
+#include "trpc/common/config/loadbalance_naming_conf.h"
+
+namespace YAML {
+
+template <>
+struct convert<trpc::naming::LoadBalanceConfig> {
+  static YAML::Node encode(const trpc::naming::LoadBalanceConfig& config) {
+    YAML::Node node;
+    node["hash_nodes"] = config.hash_nodes;
+    node["hash_args"] = config.hash_args;
+    node["hash_func"] = config.hash_func;
+    return node;
+  }
+
+  static bool decode(const YAML::Node& node, trpc::naming::LoadBalanceConfig& config) {
+    if (node["hash_nodes"]) {
+      config.hash_nodes = node["hash_nodes"].as<uint32_t>();
+    }
+    if (node["hash_args"]) {
+      config.hash_args = node["hash_args"].as<std::vector<uint32_t>>();
+    }
+    if (node["hash_func"]) {
+      config.hash_func = node["hash_func"].as<std::string>();
+    }
+    return true;
+  }
+};
+}  // namespace YAML

trpc/common/trpc_plugin.cc

@@ -56,6 +56,7 @@
 #include "trpc/transport/common/ssl_helper.h"
 #include "trpc/util/log/default/default_log.h"
 #include "trpc/util/net_util.h"
+#include "trpc/naming/common/util/loadbalance/trpc_load_balance.h"
 
 namespace trpc {
 

trpc/naming/common/util/hash/BUILD

@@ -0,0 +1,49 @@
+# Description: trpc-cpp.
+
+licenses(["notice"])
+
+package(default_visibility = ["//visibility:public"])
+
+cc_library(
+    name = "hash_func",
+    srcs = ["hash_func.cc"],
+    hdrs = ["hash_func.h"],
+    visibility = [
+        "//visibility:public",
+    ],
+    deps = [
+        "//trpc/naming/common/util/hash:city",
+        "//trpc/naming/common/util/hash:md5",
+        "//trpc/naming/common/util/hash:murmurhash3",
+    ],
+)
+
+cc_library(
+    name = "murmurhash3",
+    srcs = ["murmurhash3.cc"],
+    hdrs = ["murmurhash3.h"],
+    visibility = [
+        "//visibility:public",
+    ],
+    deps = [],
+)
+
+cc_library(
+    name = "city",
+    srcs = ["city.cc"],
+    hdrs = ["city.h"],
+    visibility = [
+        "//visibility:public",
+    ],
+    deps = [],
+)
+
+cc_library(
+    name = "md5",
+    srcs = ["md5.cc"],
+    hdrs = ["md5.h"],
+    visibility = [
+        "//visibility:public",
+    ],
+    deps = [],
+)