refactor: address PR #839 review comments

- Rename proxyProtocol → nlbShardAwareness throughout (ClientRoutesConfig,
  DefaultDriverOption, TypedDriverOption, OptionsMap, DefaultDriverContext).
  The config key path (advanced.client-routes.proxy-protocol) is unchanged.
- Remove PP2 integration test infrastructure (ClientRoutesIT, TcpProxy,
  RoundRobinProxy, NlbSimulator) per reviewer request.
- Fix warning log to say "has no effect" instead of "will be ignored".
- Fix reference.conf comment to match actual behaviour (logs warning,
  does not silently ignore).

Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>

Author: nikagra

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

@@ -73,10 +73,10 @@ public final class ClientRoutesConfig {
 
   private final List<ClientRouteProxy> endpoints;
   private final String tableName;
-  private final boolean proxyProtocol;
+  private final boolean nlbShardAwareness;
 
   private ClientRoutesConfig(
-      List<ClientRouteProxy> endpoints, String tableName, boolean proxyProtocol) {
+      List<ClientRouteProxy> endpoints, String tableName, boolean nlbShardAwareness) {
     if (endpoints == null || endpoints.isEmpty()) {
       throw new IllegalArgumentException("At least one endpoint must be specified");
     }
@@ -88,7 +88,7 @@ private ClientRoutesConfig(
     }
     this.endpoints = Collections.unmodifiableList(new ArrayList<>(endpoints));
     this.tableName = tableName;
-    this.proxyProtocol = proxyProtocol;
+    this.nlbShardAwareness = nlbShardAwareness;
   }
 
   /**
@@ -112,18 +112,17 @@ public String getTableName() {
   }
 
   /**
-   * Returns whether Proxy Protocol v2 is in use between the NLB and ScyllaDB nodes.
+   * Returns whether NLB shard awareness is enabled.
    *
-   * <p>When {@code true}, the driver assumes the NLB prepends a PP2 binary header to each
-   * connection it opens to ScyllaDB. The header carries the original client IP and source port,
-   * which ScyllaDB uses for shard-aware routing. This restores shard-awareness end-to-end through
-   * the NLB. Requires both the NLB and ScyllaDB to be configured for Proxy Protocol v2, and {@code
-   * advanced-shard-awareness.enabled} must be {@code true} (the default).
+   * <p>When {@code true}, the driver assumes the NLB is configured to forward the driver's original
+   * source port to ScyllaDB (e.g. via Proxy Protocol v2), enabling shard-aware connection routing
+   * end-to-end through the NLB. Requires {@code advanced-shard-awareness.enabled} to be {@code
+   * true} (the default).
    *
-   * @return {@code true} if Proxy Protocol v2 is enabled.
+   * @return {@code true} if NLB shard awareness is enabled.
    */
-  public boolean isProxyProtocol() {
-    return proxyProtocol;
+  public boolean isNlbShardAwareness() {
+    return nlbShardAwareness;
   }
 
   /**
@@ -145,14 +144,14 @@ public boolean equals(Object o) {
       return false;
     }
     ClientRoutesConfig that = (ClientRoutesConfig) o;
-    return proxyProtocol == that.proxyProtocol
+    return nlbShardAwareness == that.nlbShardAwareness
         && endpoints.equals(that.endpoints)
         && tableName.equals(that.tableName);
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(endpoints, tableName, proxyProtocol);
+    return Objects.hash(endpoints, tableName, nlbShardAwareness);
   }
 
   @Override
@@ -163,8 +162,8 @@ public String toString() {
         + ", tableName='"
         + tableName
         + '\''
-        + ", proxyProtocol="
-        + proxyProtocol
+        + ", nlbShardAwareness="
+        + nlbShardAwareness
         + '}';
   }
 
@@ -173,7 +172,7 @@ public static final class Builder {
     private final List<ClientRouteProxy> endpoints = new ArrayList<>();
     private final Set<String> seenConnectionIds = new HashSet<>();
     private String tableName = DEFAULT_TABLE_NAME;
-    private boolean proxyProtocol = false;
+    private boolean nlbShardAwareness = false;
 
     /**
      * Adds an endpoint to the configuration.
@@ -232,22 +231,20 @@ Builder withTableName(@NonNull String tableName) {
     }
 
     /**
-     * Sets whether Proxy Protocol v2 (PP2) is in use between the NLB and ScyllaDB nodes.
+     * Sets whether NLB shard awareness is enabled.
      *
-     * <p>When {@code true}, the driver assumes the NLB prepends a PP2 binary header to each
-     * connection it opens to ScyllaDB. The header carries the original client source IP and port,
-     * which ScyllaDB uses to route the connection to the correct shard. This restores
-     * shard-awareness end-to-end through the NLB.
+     * <p>When {@code true}, the driver assumes the NLB is configured to forward the driver's
+     * original source port to ScyllaDB (e.g. via Proxy Protocol v2), enabling shard-aware
+     * connection routing end-to-end through the NLB.
      *
-     * <p>Requires: (1) the NLB configured with PP2, (2) ScyllaDB configured to accept PP2, (3)
-     * {@code advanced-shard-awareness.enabled = true} (the default).
+     * <p>Requires {@code advanced-shard-awareness.enabled = true} (the default).
      *
-     * @param proxyProtocol {@code true} to enable PP2 mode.
+     * @param nlbShardAwareness {@code true} to enable NLB shard awareness.
      * @return this builder.
      */
     @NonNull
-    public Builder withProxyProtocol(boolean proxyProtocol) {
-      this.proxyProtocol = proxyProtocol;
+    public Builder withNlbShardAwareness(boolean nlbShardAwareness) {
+      this.nlbShardAwareness = nlbShardAwareness;
       return this;
     }
 
@@ -259,7 +256,7 @@ public Builder withProxyProtocol(boolean proxyProtocol) {
      */
     @NonNull
     public ClientRoutesConfig build() {
-      return new ClientRoutesConfig(endpoints, tableName, proxyProtocol);
+      return new ClientRoutesConfig(endpoints, tableName, nlbShardAwareness);
     }
   }
 }

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

@@ -1099,17 +1099,16 @@ public enum DefaultDriverOption implements DriverOption {
    */
   CLIENT_ROUTES_ENDPOINTS("advanced.client-routes.endpoints"),
   /**
-   * Whether Proxy Protocol v2 (PP2) is in use between the NLB and ScyllaDB nodes.
+   * Whether NLB shard awareness is enabled for client-routes deployments.
    *
-   * <p>When {@code true}, the driver assumes the NLB prepends a PP2 binary header to each
-   * connection it opens to ScyllaDB. The header carries the original client source IP and port,
-   * enabling shard-aware routing through the NLB. Requires: (1) NLB configured with PP2, (2)
-   * ScyllaDB configured to accept PP2, (3) {@code advanced-shard-awareness.enabled = true} (the
+   * <p>When {@code true}, the driver assumes the NLB is configured to forward the driver's original
+   * source port to ScyllaDB (e.g. via Proxy Protocol v2), enabling shard-aware connection routing
+   * end-to-end through the NLB. Requires {@code advanced-shard-awareness.enabled = true} (the
    * default).
    *
    * <p>Value type: boolean
    */
-  CLIENT_ROUTES_PROXY_PROTOCOL("advanced.client-routes.proxy-protocol");
+  CLIENT_ROUTES_NLB_SHARD_AWARENESS("advanced.client-routes.proxy-protocol");
 
   private final String path;
 

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

@@ -398,7 +398,7 @@ protected static void fillWithDriverDefaults(OptionsMap map) {
         "PRESERVE_REPLICA_ORDER");
     // CLIENT_ROUTES_ENDPOINTS is intentionally omitted: it is a list-of-objects (compound HOCON
     // values) with no sensible scalar default, analogous to how CONFIG_RELOAD_INTERVAL is omitted.
-    map.put(TypedDriverOption.CLIENT_ROUTES_PROXY_PROTOCOL, false);
+    map.put(TypedDriverOption.CLIENT_ROUTES_NLB_SHARD_AWARENESS, false);
   }
 
   @Immutable

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

@@ -944,10 +944,10 @@ public String toString() {
   // DriverExecutionProfile API); it is excluded from the TypedDriverOptionTest consistency check
   // accordingly.
 
-  /** Whether Proxy Protocol v2 is in use between the NLB and ScyllaDB nodes. */
-  public static final TypedDriverOption<Boolean> CLIENT_ROUTES_PROXY_PROTOCOL =
+  /** Whether NLB shard awareness is enabled for client-routes deployments. */
+  public static final TypedDriverOption<Boolean> CLIENT_ROUTES_NLB_SHARD_AWARENESS =
       new TypedDriverOption<>(
-          DefaultDriverOption.CLIENT_ROUTES_PROXY_PROTOCOL, GenericType.BOOLEAN);
+          DefaultDriverOption.CLIENT_ROUTES_NLB_SHARD_AWARENESS, GenericType.BOOLEAN);
 
   private static Iterable<TypedDriverOption<?>> introspectBuiltInValues() {
     try {

core/src/main/java/com/datastax/oss/driver/internal/core/context/DefaultDriverContext.java

@@ -514,9 +514,9 @@ ClientRoutesConfig buildClientRoutesConfigFromFile() {
 
     ClientRoutesConfig.Builder builder = ClientRoutesConfig.builder();
 
-    if (defaultProfile.isDefined(DefaultDriverOption.CLIENT_ROUTES_PROXY_PROTOCOL)) {
-      builder.withProxyProtocol(
-          defaultProfile.getBoolean(DefaultDriverOption.CLIENT_ROUTES_PROXY_PROTOCOL));
+    if (defaultProfile.isDefined(DefaultDriverOption.CLIENT_ROUTES_NLB_SHARD_AWARENESS)) {
+      builder.withNlbShardAwareness(
+          defaultProfile.getBoolean(DefaultDriverOption.CLIENT_ROUTES_NLB_SHARD_AWARENESS));
     }
 
     for (int i = 0; i < endpointsList.size(); i++) {
@@ -649,24 +649,17 @@ private void validateClientRoutesConfiguration(ClientRoutesConfig clientRoutesCo
               + "They are mutually exclusive. Please use either a secure connect bundle OR "
               + "client routes configuration, but not both.");
     }
-    if (clientRoutesConfig.isProxyProtocol()) {
+    if (clientRoutesConfig.isNlbShardAwareness()) {
       boolean shardAwarenessEnabled =
           getConfig()
               .getDefaultProfile()
               .getBoolean(DefaultDriverOption.CONNECTION_ADVANCED_SHARD_AWARENESS_ENABLED);
       if (!shardAwarenessEnabled) {
-        // proxyProtocol=true signals that the NLB will forward the driver's original source port
-        // to ScyllaDB via a PP2 header, enabling shard-aware connection routing through the proxy.
-        // However, this only has effect when advanced shard awareness is also enabled — that is the
-        // mechanism that binds a shard-specific local port in the first place. With shard awareness
-        // disabled the driver uses a random local port, so PP2 forwards a port that carries no
-        // shard intent. The setting is therefore ignored. If shard-aware routing through the NLB
-        // is desired, enable advanced-shard-awareness (it is on by default).
         LOG.warn(
-            "[{}] ClientRoutesConfig has proxyProtocol=true but {} is false. "
-                + "Proxy Protocol v2 has no effect without advanced shard awareness — "
-                + "the proxyProtocol flag will be ignored. To enable shard-aware routing "
-                + "through the NLB, set advanced-shard-awareness.enabled=true (the default).",
+            "[{}] ClientRoutesConfig has nlbShardAwareness=true but {} is false. "
+                + "NLB shard awareness has no effect without advanced shard awareness enabled — "
+                + "the nlbShardAwareness setting will have no effect. To enable shard-aware "
+                + "routing through the NLB, set advanced-shard-awareness.enabled=true (the default).",
             getSessionName(),
             DefaultDriverOption.CONNECTION_ADVANCED_SHARD_AWARENESS_ENABLED.getPath());
       }

core/src/main/resources/reference.conf

@@ -1158,8 +1158,8 @@ datastax-java-driver {
     # Requires: (1) NLB configured with PP2, (2) ScyllaDB configured to accept PP2,
     #           (3) advanced.connection.advanced-shard-awareness.enabled = true (the default).
     #
-    # If this is true but advanced-shard-awareness.enabled is false, the driver logs a warning and
-    # ignores the setting — there is no shard-specific port to forward.
+    # If this is true but advanced-shard-awareness.enabled is false, the driver logs a warning
+    # (the flag has no effect in this configuration) — there is no shard-specific port to forward.
     #
     # Required: no
     # Default: false

integration-tests/src/test/java/com/datastax/oss/driver/core/clientroutes/ClientRoutesIT.java

@@ -820,59 +820,6 @@ public void should_select_tls_port_when_ssl_configured() throws Exception {
     }
   }
 
-  @Test
-  public void should_use_shard_awareness_through_pp2_nlb() throws Exception {
-    // Verify server supports client_routes
-    try (CqlSession admin = openAdminSession()) {
-      requireSystemClientRoutesTable(admin);
-    }
-    try (CcmBridge ccm = CcmBridge.builder().withNodes(1).build()) {
-      ccm.create();
-      ccm.start();
-
-      // Create PP2-enabled NLB
-      NlbSimulator nlb =
-          new NlbSimulator(ccm, NLB_ADDRESS, NLB_BASE_PORT, /* proxyProtocol= */ true);
-      try {
-        nlb.addNode(1);
-        Map<Integer, UUID> hostIds = collectHostIds(ccm, 1);
-        postClientRoutes(ccm, hostIds, nlb);
-        waitForRoutesVisibleOnAllNodes(ccm, hostIds.keySet(), hostIds.size());
-
-        ClientRoutesConfig config =
-            ClientRoutesConfig.builder()
-                .addEndpoint(new ClientRouteProxy(CONNECTION_ID, NLB_ADDRESS))
-                .withProxyProtocol(true)
-                .build();
-
-        try (CqlSession session = openNlbSession(config, nlb)) {
-          assertQueryWorks(session);
-
-          // With PP2, the NLB forwards the driver's original source port to ScyllaDB.
-          // The driver binds shard-specific local ports (advanced shard awareness, on by default),
-          // so ScyllaDB can route each connection to the correct shard. Verify the pool works
-          // correctly by running queries and waiting for the full pool to be established.
-          Node node = session.getMetadata().getNodes().values().iterator().next();
-          int shardCount =
-              node.getShardingInfo() != null ? node.getShardingInfo().getShardsCount() : 1;
-
-          // Wait for full shard-aware pool to be established (one connection per shard)
-          await()
-              .atMost(30, TimeUnit.SECONDS)
-              .pollInterval(1, TimeUnit.SECONDS)
-              .until(() -> node.getOpenConnections() >= shardCount);
-
-          // Run queries to verify shard-aware routing works end-to-end through the PP2 NLB
-          for (int i = 0; i < 20; i++) {
-            assertQueryWorks(session);
-          }
-        }
-      } finally {
-        nlb.close();
-      }
-    }
-  }
-
   @Test
   public void should_work_with_mixed_proxy_and_direct_nodes() throws Exception {
     try (CqlSession admin = openAdminSession()) {

integration-tests/src/test/java/com/datastax/oss/driver/core/clientroutes/NlbSimulator.java

@@ -57,7 +57,6 @@ public class NlbSimulator implements Closeable {
   private final CcmBridge ccmBridge;
   private final String bindAddress;
   private final int basePort;
-  private final boolean proxyProtocol;
 
   // Discovery port proxy: round-robins across all nodes
   private volatile RoundRobinProxy discoveryProxy;
@@ -75,24 +74,9 @@ public class NlbSimulator implements Closeable {
    * @param basePort the base port for NLB (discovery on basePort, per-node on basePort+nodeId)
    */
   public NlbSimulator(CcmBridge ccmBridge, String bindAddress, int basePort) {
-    this(ccmBridge, bindAddress, basePort, false);
-  }
-
-  /**
-   * Creates an NLB simulator with optional Proxy Protocol v2 support.
-   *
-   * @param ccmBridge the CCM bridge to get node addresses from
-   * @param bindAddress the IP address to bind proxy listeners on (e.g. "127.254.254.254")
-   * @param basePort the base port for NLB (discovery on basePort, per-node on basePort+nodeId)
-   * @param proxyProtocol when {@code true}, all proxied connections will include a PP2 binary
-   *     header carrying the original client IP and source port
-   */
-  public NlbSimulator(
-      CcmBridge ccmBridge, String bindAddress, int basePort, boolean proxyProtocol) {
     this.ccmBridge = ccmBridge;
     this.bindAddress = bindAddress;
     this.basePort = basePort;
-    this.proxyProtocol = proxyProtocol;
   }
 
   /** Returns the bind address used by this NLB simulator. */
@@ -130,7 +114,7 @@ public synchronized void addNode(int nodeId) throws IOException {
 
     // Create per-node proxy first, before updating state
     int nodePort = getNodePort(nodeId);
-    TcpProxy proxy = new TcpProxy(bindAddress, nodePort, nodeAddr, proxyProtocol);
+    TcpProxy proxy = new TcpProxy(bindAddress, nodePort, nodeAddr);
 
     // Update state and rebuild discovery proxy; if rebuild fails, close the new proxy
     activeNodes.add(nodeId);
@@ -180,7 +164,7 @@ private void rebuildDiscoveryProxy() throws IOException {
     }
 
     // Create new proxy before closing old one to avoid inconsistent state on failure
-    discoveryProxy = new RoundRobinProxy(bindAddress, basePort, targets, proxyProtocol);
+    discoveryProxy = new RoundRobinProxy(bindAddress, basePort, targets);
     if (oldProxy != null) {
       oldProxy.close();
     }