[automatic failover] feat: Add MultiDbClient with multi-endpoint failover and circuit breaker support (#4300)

* feat: introduce ResilientRedisClient with multi-endpoint failover support

Add ResilientRedisClient extending UnifiedJedis with automatic failover
capabilities across multiple weighted Redis endpoints. Includes circuit
breaker pattern, health monitoring, and configurable retry logic for
high-availability Redis deployments.

* format

* mark ResilientRedisClientTest as integration one

* fix test
  - make sure endpoint is healthy before activating it

* Rename ResilientClient to align with design

 - ResilientClient -> MultiDbClient (builder, tests, etc)

* Rename setActiveEndpoint to setActiveDatabaseEndpoint

* Rename clusterSwitchListener to databaseSwitchListener

* Rename multiClusterConfig to multiDbConfig

* fix api doc's error

* fix compilation error after rebase

* format

* fix example in javadoc

* Update ActiveActiveFailoverTest scenariou test to use builder's

# Conflicts:
#	src/test/java/redis/clients/jedis/scenario/ActiveActiveFailoverTest.java

* rename setActiveDatabaseEndpoint -. setActiveDatabase

* is healthy throw exception if cluster does not exists

* format

Author: ggivo

pom.xml

@@ -491,6 +491,9 @@
 						<include>src/main/java/redis/clients/jedis/MultiClusterClientConfig.java</include>
 						<include>src/main/java/redis/clients/jedis/HostAndPort.java</include>
 						<include>**/builders/*.java</include>
+						<include>**/MultiDb*.java</include>
+						<include>**/ClientTestUtil.java</include>
+						<include>**/ReflectionTestUtil.java</include>
 					</includes>
 				</configuration>
 				<executions>

src/main/java/redis/clients/jedis/MultiClusterClientConfig.java

@@ -2,6 +2,7 @@
 
 import io.github.resilience4j.circuitbreaker.CallNotPermittedException;
 import java.time.Duration;
+import java.util.ArrayList;
 import java.util.Arrays;
 import java.util.List;
 
@@ -450,8 +451,10 @@ public static interface StrategySupplier {
    * @see Builder#Builder(ClusterConfig[])
    */
   public MultiClusterClientConfig(ClusterConfig[] clusterConfigs) {
+
     if (clusterConfigs == null || clusterConfigs.length < 1) throw new JedisValidationException(
         "ClusterClientConfigs are required for MultiClusterPooledConnectionProvider");
+
     for (ClusterConfig clusterConfig : clusterConfigs) {
       if (clusterConfig == null)
         throw new IllegalArgumentException("ClusterClientConfigs must not contain null elements");
@@ -634,6 +637,20 @@ public boolean isFastFailover() {
     return fastFailover;
   }
 
+  /**
+   * Creates a new Builder instance for configuring MultiClusterClientConfig.
+   * <p>
+   * At least one cluster configuration must be added to the builder before calling build(). Use the
+   * endpoint() methods to add cluster configurations.
+   * </p>
+   * @return new Builder instance
+   * @throws JedisValidationException if clusterConfigs is null or empty
+   * @see Builder#Builder(ClusterConfig[])
+   */
+  public static Builder builder() {
+    return new Builder();
+  }
+
   /**
    * Creates a new Builder instance for configuring MultiClusterClientConfig.
    * @param clusterConfigs array of cluster configurations defining available Redis endpoints
@@ -751,6 +768,7 @@ public HostAndPort getHostAndPort() {
      * @return new Builder instance
      * @throws IllegalArgumentException if hostAndPort or clientConfig is null
      */
+    // TODO : Replace HostAndPort with Endpoint
     public static Builder builder(HostAndPort hostAndPort, JedisClientConfig clientConfig) {
       return new Builder(hostAndPort, clientConfig);
     }
@@ -974,7 +992,7 @@ public ClusterConfig build() {
   public static class Builder {
 
     /** Array of cluster configurations defining available Redis endpoints. */
-    private ClusterConfig[] clusterConfigs;
+    private final List<ClusterConfig> clusterConfigs = new ArrayList<>();
 
     // ============ Retry Configuration Fields ============
     /** Maximum number of retry attempts including the initial call. */
@@ -1033,17 +1051,20 @@ public static class Builder {
     /** Delay in milliseconds between failover attempts. */
     private int delayInBetweenFailoverAttempts = DELAY_IN_BETWEEN_FAILOVER_ATTEMPTS_DEFAULT;
 
+    /**
+     * Constructs a new Builder with the specified cluster configurations.
+     */
+    public Builder() {
+    }
+
     /**
      * Constructs a new Builder with the specified cluster configurations.
      * @param clusterConfigs array of cluster configurations defining available Redis endpoints
      * @throws JedisValidationException if clusterConfigs is null or empty
      */
     public Builder(ClusterConfig[] clusterConfigs) {
 
-      if (clusterConfigs == null || clusterConfigs.length < 1) throw new JedisValidationException(
-          "ClusterClientConfigs are required for MultiClusterPooledConnectionProvider");
-
-      this.clusterConfigs = clusterConfigs;
+      this(Arrays.asList(clusterConfigs));
     }
 
     /**
@@ -1052,7 +1073,47 @@ public Builder(ClusterConfig[] clusterConfigs) {
      * @throws JedisValidationException if clusterConfigs is null or empty
      */
     public Builder(List<ClusterConfig> clusterConfigs) {
-      this(clusterConfigs.toArray(new ClusterConfig[0]));
+      this.clusterConfigs.addAll(clusterConfigs);
+    }
+
+    /**
+     * Adds a pre-configured endpoint configuration.
+     * <p>
+     * This method allows adding a fully configured ClusterConfig instance, providing maximum
+     * flexibility for advanced configurations including custom health check strategies, connection
+     * pool settings, etc.
+     * </p>
+     * @param clusterConfig the pre-configured cluster configuration
+     * @return this builder
+     */
+    public Builder endpoint(ClusterConfig clusterConfig) {
+      this.clusterConfigs.add(clusterConfig);
+      return this;
+    }
+
+    /**
+     * Adds a Redis endpoint with custom client configuration.
+     * <p>
+     * This method allows specifying endpoint-specific configuration such as authentication, SSL
+     * settings, timeouts, etc. This configuration will override the default client configuration
+     * for this specific endpoint.
+     * </p>
+     * @param endpoint the Redis server endpoint
+     * @param weight the weight for this endpoint (higher values = higher priority)
+     * @param clientConfig the client configuration for this endpoint
+     * @return this builder
+     */
+    public Builder endpoint(Endpoint endpoint, float weight, JedisClientConfig clientConfig) {
+      // Convert Endpoint to HostAndPort for ClusterConfig
+      // TODO : Refactor ClusterConfig to accept Endpoint directly
+      HostAndPort hostAndPort = (endpoint instanceof HostAndPort) ? (HostAndPort) endpoint
+          : new HostAndPort(endpoint.getHost(), endpoint.getPort());
+
+      ClusterConfig clusterConfig = ClusterConfig.builder(hostAndPort, clientConfig).weight(weight)
+          .build();
+
+      this.clusterConfigs.add(clusterConfig);
+      return this;
     }
 
     // ============ Retry Configuration Methods ============
@@ -1453,7 +1514,9 @@ public Builder delayInBetweenFailoverAttempts(int delayInBetweenFailoverAttempts
      * @return a new MultiClusterClientConfig instance with the configured settings
      */
     public MultiClusterClientConfig build() {
-      MultiClusterClientConfig config = new MultiClusterClientConfig(this.clusterConfigs);
+
+      MultiClusterClientConfig config = new MultiClusterClientConfig(
+          this.clusterConfigs.toArray(new ClusterConfig[0]));
 
       // Copy retry configuration
       config.retryMaxAttempts = this.retryMaxAttempts;