feat: update client routes configuration details for mutual exclusivity with AddressTranslator and cloud bundles

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: nikagra

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

@@ -152,8 +152,13 @@ public Builder addEndpoint(@NonNull ClientRoutesEndpoint endpoint) {
     @NonNull
     public Builder withEndpoints(@NonNull List<ClientRoutesEndpoint> endpoints) {
       Objects.requireNonNull(endpoints, "endpoints must not be null");
+      if (endpoints.isEmpty()) {
+        throw new IllegalArgumentException("endpoints must not be empty");
+      }
       this.endpoints.clear();
-      this.endpoints.addAll(endpoints);
+      for (ClientRoutesEndpoint endpoint : endpoints) {
+        addEndpoint(endpoint);
+      }
       return this;
     }
 

core/src/main/java/com/datastax/oss/driver/api/core/session/SessionBuilder.java

@@ -25,7 +25,6 @@
 
 import com.datastax.oss.driver.api.core.CqlIdentifier;
 import com.datastax.oss.driver.api.core.CqlSession;
-import com.datastax.oss.driver.api.core.addresstranslation.AddressTranslator;
 import com.datastax.oss.driver.api.core.auth.AuthProvider;
 import com.datastax.oss.driver.api.core.auth.PlainTextAuthProviderBase;
 import com.datastax.oss.driver.api.core.auth.ProgrammaticPlainTextAuthProvider;
@@ -748,9 +747,9 @@ public SelfT withCloudProxyAddress(@Nullable InetSocketAddress cloudProxyAddress
    * table. Each endpoint is identified by a connection ID and maps to specific node addresses.
    *
    * <p>This configuration is mutually exclusive with a user-provided {@link AddressTranslator}. If
-   * both are specified, an error will be thrown during session initialization. If you need custom
-   * address translation behavior with client routes, the driver's internal client routes handler
-   * will be used.
+   * both are specified, a warning will be logged and the client routes configuration will take
+   * precedence. If you need custom address translation behavior with client routes, consider
+   * implementing that logic within your client routes endpoint mapping instead.
    *
    * <p>Example usage:
    *
@@ -939,6 +938,13 @@ protected final CompletionStage<CqlSession> buildDefaultSessionAsync() {
         withSslEngineFactory(cloudConfig.getSslEngineFactory());
         withCloudProxyAddress(cloudConfig.getProxyAddress());
         programmaticArguments = programmaticArgumentsBuilder.build();
+
+        // Check for mutual exclusivity with client routes
+        if (clientRoutesConfig != null) {
+          LOG.info(
+              "Both a secure connect bundle and client routes configuration were provided. They are mutually exclusive. The configuration from the secure bundle will have priority.");
+          clientRoutesConfig = null;
+        }
       }
 
       // Handle client routes configuration
@@ -951,9 +957,10 @@ protected final CompletionStage<CqlSession> buildDefaultSessionAsync() {
           if (!"PassThroughAddressTranslator".equals(translatorClass)
               && !"com.datastax.oss.driver.internal.core.addresstranslation.PassThroughAddressTranslator"
                   .equals(translatorClass)) {
-            throw new IllegalArgumentException(
-                "Client routes configuration is mutually exclusive with a custom AddressTranslator. "
-                    + "Either remove the address translator configuration or do not use client routes.");
+            LOG.info(
+                "Both client routes configuration and a custom AddressTranslator were provided. They are mutually exclusive. The client routes configuration will have priority.");
+            // Note: We don't clear clientRoutesConfig here - it takes precedence.
+            // The AddressTranslator will be effectively ignored when client routes are active.
           }
         }
 
@@ -962,18 +969,9 @@ protected final CompletionStage<CqlSession> buildDefaultSessionAsync() {
           for (ClientRoutesEndpoint endpoint : clientRoutesConfig.getEndpoints()) {
             if (endpoint.getConnectionAddr() != null) {
               String addr = endpoint.getConnectionAddr().trim();
-              try {
-                InetSocketAddress socketAddress =
-                    AddressParser.parseContactPoint(addr, endpoint.getConnectionId());
-                programmaticContactPoints.add(new DefaultEndPoint(socketAddress));
-
-              } catch (Exception e) {
-                throw new IllegalArgumentException(
-                    String.format(
-                        "Failed to parse client routes endpoint address '%s' (connection ID: %s): %s",
-                        addr, endpoint.getConnectionId(), e.getMessage()),
-                    e);
-              }
+              InetSocketAddress socketAddress =
+                  AddressParser.parseContactPoint(addr, endpoint.getConnectionId());
+              programmaticContactPoints.add(new DefaultEndPoint(socketAddress));
             }
           }
         }

core/src/main/java/com/datastax/oss/driver/internal/core/util/AddressParser.java

@@ -92,7 +92,7 @@ public static InetSocketAddress parseContactPoint(String address, UUID connectio
                 String.format("Invalid port %d. Port must be between 1 and 65535.", port)));
       }
 
-      return new InetSocketAddress(host, port);
+      return InetSocketAddress.createUnresolved(host, port);
 
     } catch (java.net.URISyntaxException e) {
       throw new IllegalArgumentException(

core/src/main/resources/reference.conf

@@ -1120,9 +1120,11 @@ datastax-java-driver {
   # SessionBuilder.withClientRoutesConfig(). This configuration section only provides the
   # system table name option.
   #
-  # Client routes are mutually exclusive with a custom AddressTranslator. If client routes are
-  # configured programmatically, the address-translator.class option must be set to
-  # PassThroughAddressTranslator (the default), otherwise session initialization will fail.
+  # Client routes are mutually exclusive with:
+  # - A custom AddressTranslator: If both are configured, client routes take precedence
+  #   and the AddressTranslator is effectively ignored (a warning is logged).
+  # - Cloud secure connect bundles: If both are configured, the cloud bundle takes precedence
+  #   and client routes are ignored (a warning is logged).
   #
   # Required: no (programmatic configuration only)
   # Modifiable at runtime: no

manual/core/address_resolution/README.md

@@ -124,7 +124,9 @@ For cloud deployments using PrivateLink or similar private endpoint technologies
 accessed through private DNS endpoints rather than direct IP addresses. The driver provides a client routes feature
 to handle this topology.
 
-Client routes configuration is done programmatically and is **mutually exclusive** with a custom `AddressTranslator`.
+Client routes configuration is done programmatically and is **mutually exclusive** with:
+- A custom `AddressTranslator` (if both are provided, client routes takes precedence)
+- Cloud secure connect bundles (if both are provided, the cloud bundle takes precedence)
 
 Example configuration: