client routes: add exclusive-proxy config flag for strict proxy enforcement

Introduces advanced.client-routes.exclusive-proxy (default: false).

When false (default), the driver falls back to the node broadcast
address when no client-route entry exists — preserving backward
compatibility with mixed proxy/direct topologies.

When true, no fallback is attempted: the node stays DOWN until a
CLIENT_ROUTES_CHANGE event publishes the route. This prevents silent
bypass of the proxy infrastructure during node additions.

Author: nikagra

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

@@ -1119,7 +1119,22 @@ public enum DefaultDriverOption implements DriverOption {
    *
    * <p>Value type: boolean
    */
-  CLIENT_ROUTES_SHARD_AWARENESS_ENABLED("advanced.client-routes.shard-awarness-enabled");
+  CLIENT_ROUTES_SHARD_AWARENESS_ENABLED("advanced.client-routes.shard-awarness-enabled"),
+
+  /**
+   * Whether the driver connects exclusively through proxies when client routes are configured.
+   *
+   * <p>When {@code true}, any node whose {@code host_id} does not appear in the {@code
+   * system.client_routes} table is treated as unreachable; the driver will never fall back to the
+   * node's broadcast address. The node stays DOWN and the reconnection loop retries until a {@code
+   * CLIENT_ROUTES_CHANGE} event populates the route.
+   *
+   * <p>When {@code false} (the default), nodes that have no route entry are contacted directly
+   * using their broadcast address, preserving backward-compatible mixed proxy/direct topologies.
+   *
+   * <p>Value type: boolean
+   */
+  CLIENT_ROUTES_EXCLUSIVE_PROXY("advanced.client-routes.exclusive-proxy");
 
   private final String path;
 

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

@@ -400,6 +400,7 @@ protected static void fillWithDriverDefaults(OptionsMap map) {
     // values) with no sensible scalar default, analogous to how CONFIG_RELOAD_INTERVAL is omitted.
     map.put(TypedDriverOption.CLIENT_ROUTES_NATIVE_TRANSPORT_PORT, 9042);
     map.put(TypedDriverOption.CLIENT_ROUTES_SHARD_AWARENESS_ENABLED, false);
+    map.put(TypedDriverOption.CLIENT_ROUTES_EXCLUSIVE_PROXY, false);
   }
 
   @Immutable

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

@@ -954,6 +954,15 @@ public String toString() {
       new TypedDriverOption<>(
           DefaultDriverOption.CLIENT_ROUTES_SHARD_AWARENESS_ENABLED, GenericType.BOOLEAN);
 
+  /**
+   * Whether the driver connects exclusively through proxies when client routes are configured. When
+   * {@code false} (default), nodes without a route entry are contacted directly via their broadcast
+   * address.
+   */
+  public static final TypedDriverOption<Boolean> CLIENT_ROUTES_EXCLUSIVE_PROXY =
+      new TypedDriverOption<>(
+          DefaultDriverOption.CLIENT_ROUTES_EXCLUSIVE_PROXY, GenericType.BOOLEAN);
+
   private static Iterable<TypedDriverOption<?>> introspectBuiltInValues() {
     try {
       ImmutableList.Builder<TypedDriverOption<?>> result = ImmutableList.builder();

core/src/main/resources/reference.conf

@@ -1173,6 +1173,19 @@ datastax-java-driver {
     # Default: false
     shard-awarness-enabled = false
 
+    # When true, the driver connects exclusively through proxies and will never fall back to a
+    # node's broadcast address when no route entry exists in system.client_routes. Any node
+    # without a route is treated as unreachable; it goes DOWN and the reconnection loop retries
+    # until a CLIENT_ROUTES_CHANGE event populates the route.
+    #
+    # When false (default), nodes that have no route entry are reached directly using their
+    # broadcast address, preserving backward-compatible mixed proxy/direct topologies where some
+    # nodes are behind the private endpoint and others are not.
+    #
+    # Required: no
+    # Default: false
+    exclusive-proxy = false
+
   }
 
   # Whether to resolve the addresses passed to `basic.contact-points`.