[automatic failover] Builder APIs for DatabaseConfig and CircuitBreakerConfig (CAE-1695) (#3571)

* add DatabaseConfig.Builder

* healthCheckStrategySupplier now defaults to PingStrategy.DEFAULT in the builder

 - When using the builder without setting healthCheckStrategySupplier: Health checks will use PingStrategy.DEFAULT
 - When explicitly setting to null: Health checks will be disabled (as documented)
 - When setting to a custom supplier: Uses the custom health check strategy

 Example Usage:
 // Uses PingStrategy.DEFAULT for health checks
 DatabaseConfig config1 = DatabaseConfig.builder(uri)
     .weight(1.0f)
     .build();

 // Explicitly disables health checks
 DatabaseConfig config2 = DatabaseConfig.builder(uri)
     .healthCheckStrategySupplier(null)
     .build();

 // Uses custom health check strategy
 DatabaseConfig config3 = DatabaseConfig.builder(uri)
     .healthCheckStrategySupplier(customSupplier)
     .build();

* HealthCheckStrategySupplier.NO_HEALTH_CHECK instead null

* Remove DatabaseConfig constructors

// To create DatabaseConfig use provided builder
DatabaseConfig config = DatabaseConfig.builder(redisURI)
    .weight(1.5f)
    .clientOptions(options)
    .circuitBreakerConfig(cbConfig)
    .healthCheckStrategySupplier(supplier)
    .build();

* remove redundant public modifiers

* Builder for CircuitBreakerConfig

// Minimal configuration with defaults
CircuitBreakerConfig config = CircuitBreakerConfig.builder().build();

// Custom configuration
CircuitBreakerConfig config = CircuitBreakerConfig.builder()
    .failureRateThreshold(25.0f)
    .minimumNumberOfFailures(500)
    .metricsWindowSize(5)
    .build();

// With custom tracked exceptions
Set<Class<? extends Throwable>> customExceptions = new HashSet<>();
customExceptions.add(RuntimeException.class);

CircuitBreakerConfig config = CircuitBreakerConfig.builder()
    .failureRateThreshold(15.5f)
    .minimumNumberOfFailures(200)
    .trackedExceptions(customExceptions)
    .metricsWindowSize(3)
    .build();

* enforce min window size of 2s

* tracked exceptions should not be null

* add convenience methods for Tracked Exceptions

//Combine add and remove
CircuitBreakerConfig config = CircuitBreakerConfig.builder()
    .addTrackedExceptions(MyCustomException.class)
    .removeTrackedExceptions(TimeoutException.class)
    .build();

// Replace all tracked exceptions
Set<Class<? extends Throwable>> customExceptions = new HashSet<>();
customExceptions.add(RuntimeException.class);
customExceptions.add(IOException.class);
CircuitBreakerConfig config = CircuitBreakerConfig.builder()
    .trackedExceptions(customExceptions)
    .build();

* remove option to configure per database clientOptions till #3572 is resolved

* Disable health checks in test configs to isolate circuit breaker testing

Configure DB1, DB2, and DB3 with NO_HEALTH_CHECK to prevent health check
interference when testing circuit breaker failure detection.

* forma

* clean up

* address review comments (Copilot)

Author: ggivo

src/main/java/io/lettuce/core/failover/CircuitBreaker.java

@@ -13,13 +13,15 @@
 import io.lettuce.core.RedisConnectionException;
 import io.lettuce.core.failover.api.CircuitBreakerStateListener;
 import io.lettuce.core.failover.metrics.MetricsSnapshot;
+import io.lettuce.core.internal.LettuceAssert;
 
 /**
- * Circuit breaker for tracking command metrics and managing circuit breaker state. Wraps CircuitBreakerMetrics and exposes it
- * via {@link #getMetrics()}.
+ * Circuit breaker for tracking command metrics and managing circuit breaker state.
+ * 
  * <p>
- * State transitions and metrics replacement are atomic and lock-free using {@link AtomicReference}. When the circuit breaker
- * transitions to a new state, a fresh metrics instance is created atomically.
+ * This interface provides methods to track command metrics and manage circuit breaker state. Implementations must be
+ * thread-safe.
+ * </p>
  *
  * @author Ali Takavci
  * @since 7.1
@@ -32,52 +34,52 @@ public interface CircuitBreaker extends Closeable {
      *
      * @return an immutable snapshot of current metrics
      */
-    public MetricsSnapshot getSnapshot();
+    MetricsSnapshot getSnapshot();
 
     /**
      * Get the current generation of the circuit breaker. This is used to track the state and metrics of the circuit breaker at
      * the time of command execution.
      *
      * @return the current generation of the circuit breaker
      */
-    public CircuitBreakerGeneration getGeneration();
+    CircuitBreakerGeneration getGeneration();
 
     /**
      * Get the current state of the circuit breaker.
      *
      * @return the current state
      */
-    public State getCurrentState();
+    State getCurrentState();
 
     /**
      * Check if the circuit breaker is in the closed state.
      *
      * @return {@code true} if the circuit breaker is in the closed state
      */
-    public boolean isClosed();
+    boolean isClosed();
 
     /**
      * Add a listener for circuit breaker state change events.
      *
      * @param listener the listener to add, must not be {@code null}
      */
-    public void addListener(CircuitBreakerStateListener listener);
+    void addListener(CircuitBreakerStateListener listener);
 
     /**
      * Remove a listener for circuit breaker state change events.
      *
      * @param listener the listener to remove, must not be {@code null}
      */
-    public void removeListener(CircuitBreakerStateListener listener);
+    void removeListener(CircuitBreakerStateListener listener);
 
     @Override
-    public void close();
+    void close();
 
-    public enum State {
+    enum State {
         CLOSED, OPEN
     }
 
-    public static class CircuitBreakerConfig {
+    class CircuitBreakerConfig {
 
         private final static float DEFAULT_FAILURE_RATE_THRESHOLD = 10;
 
@@ -98,7 +100,7 @@ public static class CircuitBreakerConfig {
 
         ));
 
-        public static final CircuitBreakerConfig DEFAULT = new CircuitBreakerConfig();
+        public static final CircuitBreakerConfig DEFAULT = builder().build();
 
         private final Set<Class<? extends Throwable>> trackedExceptions;
 
@@ -108,17 +110,26 @@ public static class CircuitBreakerConfig {
 
         private final int metricsWindowSize;
 
-        private CircuitBreakerConfig() {
-            this(DEFAULT_FAILURE_RATE_THRESHOLD, DEFAULT_MINIMUM_NUMBER_OF_FAILURES, DEFAULT_TRACKED_EXCEPTIONS,
-                    DEFAULT_METRICS_WINDOW_SIZE);
+        /**
+         * Create a new circuit breaker configuration from a builder. Use {@link #builder()} instead.
+         *
+         * @param builder the builder
+         */
+        CircuitBreakerConfig(Builder builder) {
+            this.trackedExceptions = new HashSet<>(builder.trackedExceptions);
+            this.failureThreshold = builder.failureThreshold;
+            this.minimumNumberOfFailures = builder.minimumNumberOfFailures;
+            this.metricsWindowSize = builder.metricsWindowSize;
         }
 
-        public CircuitBreakerConfig(float failureThreshold, int minimumNumberOfFailures,
-                Set<Class<? extends Throwable>> trackedExceptions, int metricsWindowSize) {
-            this.trackedExceptions = trackedExceptions;
-            this.failureThreshold = failureThreshold;
-            this.minimumNumberOfFailures = minimumNumberOfFailures;
-            this.metricsWindowSize = metricsWindowSize;
+        /**
+         * Create a new builder for {@link CircuitBreakerConfig}.
+         *
+         * @return a new builder
+         * @since 7.4
+         */
+        public static Builder builder() {
+            return new Builder();
         }
 
         public Set<Class<? extends Throwable>> getTrackedExceptions() {
@@ -143,6 +154,131 @@ public String toString() {
                     + ", minimumNumberOfFailures=" + minimumNumberOfFailures + ", metricsWindowSize=" + metricsWindowSize + '}';
         }
 
+        /**
+         * Builder for {@link CircuitBreakerConfig}.
+         *
+         * @since 7.4
+         */
+        public static class Builder {
+
+            private Set<Class<? extends Throwable>> trackedExceptions = DEFAULT_TRACKED_EXCEPTIONS;
+
+            private float failureThreshold = DEFAULT_FAILURE_RATE_THRESHOLD;
+
+            private int minimumNumberOfFailures = DEFAULT_MINIMUM_NUMBER_OF_FAILURES;
+
+            private int metricsWindowSize = DEFAULT_METRICS_WINDOW_SIZE;
+
+            private Builder() {
+            }
+
+            /**
+             * Set the failure rate threshold percentage (0-100). The circuit breaker will open when the failure rate exceeds
+             * this threshold.
+             *
+             * @param failureThreshold the failure rate threshold percentage, must be >= 0
+             * @return {@code this} builder
+             */
+            public Builder failureRateThreshold(float failureThreshold) {
+                this.failureThreshold = failureThreshold;
+                return this;
+            }
+
+            /**
+             * Set the minimum number of failures required before the circuit breaker can open. This prevents the circuit from
+             * opening due to a small number of failures.
+             *
+             * @param minimumNumberOfFailures the minimum number of failures, must be >= 0
+             * @return {@code this} builder
+             */
+            public Builder minimumNumberOfFailures(int minimumNumberOfFailures) {
+                this.minimumNumberOfFailures = minimumNumberOfFailures;
+                return this;
+            }
+
+            /**
+             * Set the exceptions to track for circuit breaker metrics. Only these exceptions (and their subclasses) will be
+             * counted as failures. This replaces any previously configured tracked exceptions.
+             *
+             * @param trackedExceptions the set of exception classes to track, must not be {@code null}
+             * @return {@code this} builder
+             */
+            public Builder trackedExceptions(Set<Class<? extends Throwable>> trackedExceptions) {
+                LettuceAssert.notNull(trackedExceptions, "Tracked exceptions must not be null");
+                this.trackedExceptions = trackedExceptions;
+                return this;
+            }
+
+            /**
+             * Add one or more exception classes to track for circuit breaker metrics. Only these exceptions (and their
+             * subclasses) will be counted as failures. This adds to the existing tracked exceptions.
+             *
+             * @param exceptionClasses one or more exception classes to track, must not be {@code null} and must not contain
+             *        {@code null} elements
+             * @return {@code this} builder
+             * @since 7.4
+             */
+            @SafeVarargs
+            public final Builder addTrackedExceptions(Class<? extends Throwable>... exceptionClasses) {
+                LettuceAssert.notNull(exceptionClasses, "Exception classes must not be null");
+                LettuceAssert.noNullElements(exceptionClasses, "Exception classes must not contain null elements");
+                LettuceAssert.notEmpty(exceptionClasses, "Exception classes must contain at least one element");
+
+                // Ensure we have a mutable copy
+                if (this.trackedExceptions == DEFAULT_TRACKED_EXCEPTIONS) {
+                    this.trackedExceptions = new HashSet<>(DEFAULT_TRACKED_EXCEPTIONS);
+                }
+
+                this.trackedExceptions.addAll(Arrays.asList(exceptionClasses));
+                return this;
+            }
+
+            /**
+             * Remove one or more exception classes from the tracked exceptions for circuit breaker metrics.
+             *
+             * @param exceptionClasses one or more exception classes to remove, must not be {@code null} and must not contain
+             *        {@code null} elements
+             * @return {@code this} builder
+             * @since 7.4
+             */
+            @SafeVarargs
+            public final Builder removeTrackedExceptions(Class<? extends Throwable>... exceptionClasses) {
+                LettuceAssert.notNull(exceptionClasses, "Exception classes must not be null");
+                LettuceAssert.noNullElements(exceptionClasses, "Exception classes must not contain null elements");
+                LettuceAssert.notEmpty(exceptionClasses, "Exception classes must contain at least one element");
+
+                // Ensure we have a mutable copy
+                if (this.trackedExceptions == DEFAULT_TRACKED_EXCEPTIONS) {
+                    this.trackedExceptions = new HashSet<>(DEFAULT_TRACKED_EXCEPTIONS);
+                }
+
+                Arrays.asList(exceptionClasses).forEach(this.trackedExceptions::remove);
+                return this;
+            }
+
+            /**
+             * Set the metrics window size in seconds. Metrics are collected over this time window.
+             *
+             * @param metricsWindowSize the metrics window size in seconds, must be >= 2
+             * @return {@code this} builder
+             */
+            public Builder metricsWindowSize(int metricsWindowSize) {
+                LettuceAssert.isTrue(metricsWindowSize >= 2, "Metrics window size must be at least 2 seconds");
+                this.metricsWindowSize = metricsWindowSize;
+                return this;
+            }
+
+            /**
+             * Build a new {@link CircuitBreakerConfig} instance.
+             *
+             * @return a new {@link CircuitBreakerConfig}
+             */
+            public CircuitBreakerConfig build() {
+                return new CircuitBreakerConfig(this);
+            }
+
+        }
+
     }
 
 }