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).
- Rename nlb* identifiers to drop the NLB-specific prefix:
  ClientRoutesConfig: nlbShardAwareness → shardAwareness,
  isNlbShardAwareness() → isShardAwareness(),
  withNlbShardAwareness() → withShardAwareness()
- Rename DefaultDriverOption.CLIENT_ROUTES_NLB_SHARD_AWARENESS →
  CLIENT_ROUTES_SHARD_AWARENESS_ENABLED with new config key
  advanced.client-routes.shard-awarness-enabled (matching reviewer spelling)
- Rename TypedDriverOption / OptionsMap constant to match
- Update reference.conf: proxy-protocol → shard-awarness-enabled,
  reword comment to be load-balancer-agnostic
- Remove validation block in DefaultDriverContext that warned when
  shardAwareness=true but advanced-shard-awareness was disabled
- Delete manual/core/private_link/README.md per reviewer request

Author: nikagra

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

@@ -84,13 +84,13 @@ public final class ClientRoutesConfig {
   private final List<ClientRouteProxy> endpoints;
   private final String tableName;
   private final int nativeTransportPort;
-  private final boolean proxyProtocol;
+  private final boolean shardAwareness;
 
   private ClientRoutesConfig(
       List<ClientRouteProxy> endpoints,
       String tableName,
       int nativeTransportPort,
-      boolean proxyProtocol) {
+      boolean shardAwareness) {
     if (endpoints == null || endpoints.isEmpty()) {
       throw new IllegalArgumentException("At least one endpoint must be specified");
     }
@@ -103,7 +103,7 @@ private ClientRoutesConfig(
     this.endpoints = Collections.unmodifiableList(new ArrayList<>(endpoints));
     this.tableName = tableName;
     this.nativeTransportPort = nativeTransportPort;
-    this.proxyProtocol = proxyProtocol;
+    this.shardAwareness = shardAwareness;
   }
 
   /**
@@ -139,18 +139,17 @@ public int getNativeTransportPort() {
   }
 
   /**
-   * Returns whether Proxy Protocol v2 is in use between the NLB and ScyllaDB nodes.
+   * Returns whether 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 load balancer 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 load balancer. 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 shard awareness is enabled.
    */
-  public boolean isProxyProtocol() {
-    return proxyProtocol;
+  public boolean isShardAwareness() {
+    return shardAwareness;
   }
 
   /**
@@ -175,12 +174,12 @@ public boolean equals(Object o) {
     return endpoints.equals(that.endpoints)
         && tableName.equals(that.tableName)
         && nativeTransportPort == that.nativeTransportPort
-        && proxyProtocol == that.proxyProtocol;
+        && shardAwareness == that.shardAwareness;
   }
 
   @Override
   public int hashCode() {
-    return Objects.hash(endpoints, tableName, nativeTransportPort, proxyProtocol);
+    return Objects.hash(endpoints, tableName, nativeTransportPort, shardAwareness);
   }
 
   @Override
@@ -193,8 +192,8 @@ public String toString() {
         + '\''
         + ", nativeTransportPort="
         + nativeTransportPort
-        + ", proxyProtocol="
-        + proxyProtocol
+        + ", shardAwareness="
+        + shardAwareness
         + '}';
   }
 
@@ -204,7 +203,7 @@ public static final class Builder {
     private final Set<String> seenConnectionIds = new HashSet<>();
     private String tableName = DEFAULT_TABLE_NAME;
     private int nativeTransportPort = DEFAULT_NATIVE_TRANSPORT_PORT;
-    private boolean proxyProtocol = false;
+    private boolean shardAwareness = false;
 
     /**
      * Adds an endpoint to the configuration.
@@ -278,22 +277,20 @@ public Builder withNativeTransportPort(int port) {
     }
 
     /**
-     * Sets whether Proxy Protocol v2 (PP2) is in use between the NLB and ScyllaDB nodes.
+     * Sets whether 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 load balancer 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 load balancer.
      *
-     * <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 shardAwareness {@code true} to enable shard awareness.
      * @return this builder.
      */
     @NonNull
-    public Builder withProxyProtocol(boolean proxyProtocol) {
-      this.proxyProtocol = proxyProtocol;
+    public Builder withShardAwareness(boolean shardAwareness) {
+      this.shardAwareness = shardAwareness;
       return this;
     }
 
@@ -305,7 +302,7 @@ public Builder withProxyProtocol(boolean proxyProtocol) {
      */
     @NonNull
     public ClientRoutesConfig build() {
-      return new ClientRoutesConfig(endpoints, tableName, nativeTransportPort, proxyProtocol);
+      return new ClientRoutesConfig(endpoints, tableName, nativeTransportPort, shardAwareness);
     }
   }
 }

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

@@ -1110,17 +1110,16 @@ public enum DefaultDriverOption implements DriverOption {
   CLIENT_ROUTES_NATIVE_TRANSPORT_PORT("advanced.client-routes.native-transport-port"),
 
   /**
-   * 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_SHARD_AWARENESS_ENABLED("advanced.client-routes.shard-awarness-enabled");
 
   private final String path;
 

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

@@ -399,7 +399,7 @@ protected static void fillWithDriverDefaults(OptionsMap map) {
     // 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_NATIVE_TRANSPORT_PORT, 9042);
-    map.put(TypedDriverOption.CLIENT_ROUTES_PROXY_PROTOCOL, false);
+    map.put(TypedDriverOption.CLIENT_ROUTES_SHARD_AWARENESS_ENABLED, false);
   }
 
   @Immutable

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

@@ -949,10 +949,10 @@ public String toString() {
       new TypedDriverOption<>(
           DefaultDriverOption.CLIENT_ROUTES_NATIVE_TRANSPORT_PORT, GenericType.INTEGER);
 
-  /** Whether Proxy Protocol v2 is in use between the NLB and ScyllaDB nodes. */
-  public static final TypedDriverOption<Boolean> CLIENT_ROUTES_PROXY_PROTOCOL =
+  /** Whether shard awareness is enabled for client-routes deployments. */
+  public static final TypedDriverOption<Boolean> CLIENT_ROUTES_SHARD_AWARENESS_ENABLED =
       new TypedDriverOption<>(
-          DefaultDriverOption.CLIENT_ROUTES_PROXY_PROTOCOL, GenericType.BOOLEAN);
+          DefaultDriverOption.CLIENT_ROUTES_SHARD_AWARENESS_ENABLED, 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_SHARD_AWARENESS_ENABLED)) {
+      builder.withShardAwareness(
+          defaultProfile.getBoolean(DefaultDriverOption.CLIENT_ROUTES_SHARD_AWARENESS_ENABLED));
     }
 
     for (int i = 0; i < endpointsList.size(); i++) {
@@ -654,29 +654,6 @@ 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()) {
-      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).",
-            getSessionName(),
-            DefaultDriverOption.CONNECTION_ADVANCED_SHARD_AWARENESS_ENABLED.getPath());
-      }
-    }
-
     DriverExecutionProfile defaultProfile = getConfig().getDefaultProfile();
     if (defaultProfile.isDefined(DefaultDriverOption.ADDRESS_TRANSLATOR_CLASS)) {
       String className = defaultProfile.getString(DefaultDriverOption.ADDRESS_TRANSLATOR_CLASS);

core/src/main/resources/reference.conf

@@ -1157,24 +1157,21 @@ datastax-java-driver {
     # Overridable in a profile: no
     native-transport-port = 9042
 
-    # Whether Proxy Protocol v2 (PP2) is in use between the NLB and ScyllaDB nodes.
+    # Whether shard awareness is enabled for client-routes deployments.
     #
-    # When 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. The driver's own role is to continue binding shard-specific local ports as usual
-    # (controlled by advanced-shard-awareness.enabled, which is true by default); the NLB then
-    # forwards those ports to ScyllaDB via the PP2 header.
+    # When true, the driver assumes the load balancer is configured to forward the driver's original
+    # source port to ScyllaDB (e.g. via Proxy Protocol v2). 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 load balancer. The driver's own role is to
+    # continue binding shard-specific local ports as usual (controlled by
+    # advanced-shard-awareness.enabled, which is true by default).
     #
-    # Requires: (1) NLB configured with PP2, (2) ScyllaDB configured to accept PP2,
+    # Requires: (1) load balancer 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.
-    #
     # Required: no
     # Default: false
-    proxy-protocol = false
+    shard-awarness-enabled = 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()) {