Add config options for advanced shard awareness

Adds config options for toggling the feature on and defining
port ranges to use.
By default the feature will be enabled.

Author: Bouncheck

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

@@ -141,6 +141,17 @@ public enum DefaultDriverOption implements DriverOption {
    * <p>Value-type: boolean
    */
   CONNECTION_WARN_INIT_ERROR("advanced.connection.warn-on-init-error"),
+  /**
+   * Whether to use advanced shard awareness.
+   *
+   * <p>Value-type: boolean
+   */
+  CONNECTION_ADVANCED_SHARD_AWARENESS_ENABLED(
+      "advanced.connection.advanced-shard-awareness.enabled"),
+  /** Inclusive lower bound of port range to use in advanced shard awareness */
+  ADVANCED_SHARD_AWARENESS_PORT_LOW("advanced.connection.advanced-shard-awareness.port-low"),
+  /** Inclusive upper bound of port range to use in advanced shard awareness */
+  ADVANCED_SHARD_AWARENESS_PORT_HIGH("advanced.connection.advanced-shard-awareness.port-high"),
   /**
    * The number of connections in the LOCAL pool.
    *

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

@@ -276,6 +276,9 @@ protected static void fillWithDriverDefaults(OptionsMap map) {
     map.put(TypedDriverOption.CONNECTION_MAX_REQUESTS, 1024);
     map.put(TypedDriverOption.CONNECTION_MAX_ORPHAN_REQUESTS, 256);
     map.put(TypedDriverOption.CONNECTION_WARN_INIT_ERROR, true);
+    map.put(TypedDriverOption.CONNECTION_ADVANCED_SHARD_AWARENESS_ENABLED, true);
+    map.put(TypedDriverOption.ADVANCED_SHARD_AWARENESS_PORT_LOW, 10000);
+    map.put(TypedDriverOption.ADVANCED_SHARD_AWARENESS_PORT_HIGH, 60000);
     map.put(TypedDriverOption.RECONNECT_ON_INIT, false);
     map.put(TypedDriverOption.RECONNECTION_POLICY_CLASS, "ExponentialReconnectionPolicy");
     map.put(TypedDriverOption.RECONNECTION_BASE_DELAY, Duration.ofSeconds(1));

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

@@ -175,6 +175,18 @@ public String toString() {
   /** Whether to log non-fatal errors when the driver tries to open a new connection. */
   public static final TypedDriverOption<Boolean> CONNECTION_WARN_INIT_ERROR =
       new TypedDriverOption<>(DefaultDriverOption.CONNECTION_WARN_INIT_ERROR, GenericType.BOOLEAN);
+  /** Whether to use advanced shard awareness */
+  public static final TypedDriverOption<Boolean> CONNECTION_ADVANCED_SHARD_AWARENESS_ENABLED =
+      new TypedDriverOption<>(
+          DefaultDriverOption.CONNECTION_ADVANCED_SHARD_AWARENESS_ENABLED, GenericType.BOOLEAN);
+  /** Inclusive lower bound of port range to use in advanced shard awareness */
+  public static final TypedDriverOption<Integer> ADVANCED_SHARD_AWARENESS_PORT_LOW =
+      new TypedDriverOption<>(
+          DefaultDriverOption.ADVANCED_SHARD_AWARENESS_PORT_LOW, GenericType.INTEGER);
+  /** Inclusive upper bound of port range to use in advanced shard awareness */
+  public static final TypedDriverOption<Integer> ADVANCED_SHARD_AWARENESS_PORT_HIGH =
+      new TypedDriverOption<>(
+          DefaultDriverOption.ADVANCED_SHARD_AWARENESS_PORT_HIGH, GenericType.INTEGER);
   /** The number of connections in the LOCAL pool. */
   public static final TypedDriverOption<Integer> CONNECTION_POOL_LOCAL_SIZE =
       new TypedDriverOption<>(DefaultDriverOption.CONNECTION_POOL_LOCAL_SIZE, GenericType.INTEGER);

core/src/main/resources/reference.conf

@@ -535,6 +535,41 @@ datastax-java-driver {
     #   change.
     # Overridable in a profile: no
     warn-on-init-error = true
+
+
+    advanced-shard-awareness {
+      # Whether to use advanced shard awareness when trying to open new connections.
+      #
+      # Having this enabled makes sense only for ScyllaDB clusters.
+      # Results in smaller connection storms in multi-client settings.
+      # If set to false the driver will not attempt to use this feature.
+      # If set to true the driver will attempt to use it and will log warnings each time something
+      # makes it not possible.
+      # If the node for some reason does not report it's sharding info the driver
+      # will log a warning and create connection the same way as if this feature was disabled.
+      # If the cluster ignores the request for specific shard warning will also be logged,
+      # although the local port will be chosen according to advanced shard awareness rules.
+      #
+      # Required: yes
+      # Modifiable at runtime: yes, the new value will be used for connections created after the
+      # change.
+      # Overridable in a profile: no
+      enabled = true
+
+      # Inclusive lower bound of port range to use in advanced shard awareness
+      # The driver will attempt to reserve ports for connection only within the range.
+      # Required: yes
+      # Modifiable at runtime: yes, the new value will be used for calls after the
+      # change.
+      port-low = 10000
+
+      # Inclusive upper bound of port range to use in advanced shard awareness.
+      # The driver will attempt to reserve ports for connection only within the range.
+      # Required: yes
+      # Modifiable at runtime: yes, the new value will be used for calls after the
+      # change.
+      port-high = 60000
+    }
   }
 
   # Advanced options for the built-in load-balancing policies.