feat: add configurable DNS cache duration to ClientRoutesConfig

Author: nikagra

core/src/main/java/com/datastax/oss/driver/api/core/config/ClientRoutesConfig.java

@@ -44,6 +44,7 @@
  *     .addEndpoint(new ClientRoutesEndpoint(
  *         UUID.fromString("12345678-1234-1234-1234-123456789012"),
  *         "my-privatelink.us-east-1.aws.scylladb.com:9042"))
+ *     .withDnsCacheDuration(1000L)  // Cache DNS for 1 second (default: 500ms)
  *     .build();
  *
  * CqlSession session = CqlSession.builder()
@@ -57,15 +58,23 @@
 @Immutable
 public class ClientRoutesConfig {
 
+  private static final long DEFAULT_DNS_CACHE_DURATION_MILLIS = 500L;
+
   private final List<ClientRoutesEndpoint> endpoints;
   private final String tableName;
+  private final long dnsCacheDurationMillis;
 
-  private ClientRoutesConfig(List<ClientRoutesEndpoint> endpoints, String tableName) {
+  private ClientRoutesConfig(
+      List<ClientRoutesEndpoint> endpoints, String tableName, long dnsCacheDurationMillis) {
     if (endpoints == null || endpoints.isEmpty()) {
       throw new IllegalArgumentException("At least one endpoint must be specified");
     }
+    if (dnsCacheDurationMillis < 0) {
+      throw new IllegalArgumentException("DNS cache duration must be non-negative");
+    }
     this.endpoints = Collections.unmodifiableList(new ArrayList<>(endpoints));
     this.tableName = tableName;
+    this.dnsCacheDurationMillis = dnsCacheDurationMillis;
   }
 
   /**
@@ -88,6 +97,19 @@ public String getTableName() {
     return tableName;
   }
 
+  /**
+   * Returns the DNS cache duration in milliseconds.
+   *
+   * <p>This controls how long resolved DNS entries are cached before being re-resolved. A shorter
+   * duration is appropriate for dynamic environments where DNS mappings change frequently, while a
+   * longer duration can reduce DNS lookup overhead in stable environments.
+   *
+   * @return the DNS cache duration in milliseconds (default: 500ms).
+   */
+  public long getDnsCacheDurationMillis() {
+    return dnsCacheDurationMillis;
+  }
+
   /**
    * Creates a new builder for constructing a {@link ClientRoutesConfig}.
    *
@@ -107,12 +129,14 @@ public boolean equals(Object o) {
       return false;
     }
     ClientRoutesConfig that = (ClientRoutesConfig) o;
-    return endpoints.equals(that.endpoints) && Objects.equals(tableName, that.tableName);
+    return dnsCacheDurationMillis == that.dnsCacheDurationMillis
+        && endpoints.equals(that.endpoints)
+        && Objects.equals(tableName, that.tableName);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(endpoints, tableName);
+    return Objects.hash(endpoints, tableName, dnsCacheDurationMillis);
   }
 
   @Override
@@ -123,13 +147,16 @@ public String toString() {
         + ", tableName='"
         + tableName
         + '\''
+        + ", dnsCacheDurationMillis="
+        + dnsCacheDurationMillis
         + '}';
   }
 
   /** Builder for {@link ClientRoutesConfig}. */
   public static class Builder {
     private final List<ClientRoutesEndpoint> endpoints = new ArrayList<>();
     private String tableName;
+    private long dnsCacheDurationMillis = DEFAULT_DNS_CACHE_DURATION_MILLIS;
 
     /**
      * Adds an endpoint to the configuration.
@@ -177,6 +204,29 @@ public Builder withTableName(@Nullable String tableName) {
       return this;
     }
 
+    /**
+     * Sets the DNS cache duration in milliseconds.
+     *
+     * <p>This controls how long resolved DNS entries are cached before being re-resolved. A shorter
+     * duration is appropriate for dynamic environments where DNS mappings change frequently (e.g.,
+     * during rolling updates), while a longer duration can reduce DNS lookup overhead in stable
+     * environments.
+     *
+     * <p>Default: 500ms
+     *
+     * @param durationMillis the cache duration in milliseconds (must be non-negative).
+     * @return this builder.
+     * @throws IllegalArgumentException if the duration is negative.
+     */
+    @NonNull
+    public Builder withDnsCacheDuration(long durationMillis) {
+      if (durationMillis < 0) {
+        throw new IllegalArgumentException("DNS cache duration must be non-negative");
+      }
+      this.dnsCacheDurationMillis = durationMillis;
+      return this;
+    }
+
     /**
      * Builds the {@link ClientRoutesConfig} with the configured endpoints and table name.
      *
@@ -185,7 +235,7 @@ public Builder withTableName(@Nullable String tableName) {
      */
     @NonNull
     public ClientRoutesConfig build() {
-      return new ClientRoutesConfig(endpoints, tableName);
+      return new ClientRoutesConfig(endpoints, tableName, dnsCacheDurationMillis);
     }
   }
 }

core/src/test/java/com/datastax/oss/driver/api/core/config/ClientRoutesConfigTest.java

@@ -120,4 +120,48 @@ public void should_replace_endpoints_with_withEndpoints() {
     assertThat(config.getEndpoints().get(0).getConnectionId()).isEqualTo(connectionId2);
     assertThat(config.getEndpoints().get(1).getConnectionId()).isEqualTo(connectionId3);
   }
+
+  @Test
+  public void should_use_default_dns_cache_duration() {
+    ClientRoutesConfig config =
+        ClientRoutesConfig.builder()
+            .addEndpoint(new ClientRoutesEndpoint(UUID.randomUUID()))
+            .build();
+
+    assertThat(config.getDnsCacheDurationMillis()).isEqualTo(500L);
+  }
+
+  @Test
+  public void should_build_config_with_custom_dns_cache_duration() {
+    ClientRoutesConfig config =
+        ClientRoutesConfig.builder()
+            .addEndpoint(new ClientRoutesEndpoint(UUID.randomUUID()))
+            .withDnsCacheDuration(1000L)
+            .build();
+
+    assertThat(config.getDnsCacheDurationMillis()).isEqualTo(1000L);
+  }
+
+  @Test
+  public void should_allow_zero_dns_cache_duration() {
+    ClientRoutesConfig config =
+        ClientRoutesConfig.builder()
+            .addEndpoint(new ClientRoutesEndpoint(UUID.randomUUID()))
+            .withDnsCacheDuration(0L)
+            .build();
+
+    assertThat(config.getDnsCacheDurationMillis()).isEqualTo(0L);
+  }
+
+  @Test
+  public void should_fail_when_dns_cache_duration_is_negative() {
+    assertThatThrownBy(
+            () ->
+                ClientRoutesConfig.builder()
+                    .addEndpoint(new ClientRoutesEndpoint(UUID.randomUUID()))
+                    .withDnsCacheDuration(-1L)
+                    .build())
+        .isInstanceOf(IllegalArgumentException.class)
+        .hasMessageContaining("DNS cache duration must be non-negative");
+  }
 }