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, 65535);
     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,52 @@ 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.
+      #
+      # Requires passing shard-aware port as contact point (usually 19042 or 19142(ssl)).
+      # Having this enabled makes sense only for ScyllaDB clusters.
+      #
+      # Reduces number of reconnections driver needs to fully initialize connection pool.
+      # In short it's a feature that allows targeting particular shard when connecting to a node by using specific
+      # local port number.
+      # For context see https://www.scylladb.com/2021/04/27/connect-faster-to-scylla-with-a-shard-aware-port/
+      #
+      # If set to false the driver will not attempt to use this feature. This means connection's local port
+      # will be random according to system rules and driver will keep opening connections until it gets right shards.
+      # In such case non-shard aware port is recommended (by default 9042 or 9142).
+      # 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 already 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.
+      # Overridable in a profile: no
+      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.
+      # Overridable in a profile: no
+      port-high = 65535
+    }
   }
 
   # Advanced options for the built-in load-balancing policies.