Add enableOverloadRetargeting API

driver-core/src/main/com/mongodb/ConnectionString.java

@@ -19,6 +19,7 @@
 import com.mongodb.annotations.Alpha;
 import com.mongodb.annotations.Reason;
 import com.mongodb.connection.ClusterSettings;
+import com.mongodb.connection.ClusterType;
 import com.mongodb.connection.ConnectionPoolSettings;
 import com.mongodb.connection.ServerMonitoringMode;
 import com.mongodb.connection.ServerSettings;
@@ -272,6 +273,9 @@
  *  Defaults to true.</li>
  * <li>{@code retryReads=true|false}. If true the driver will retry supported read operations if they fail due to a network error.
  *  Defaults to true.</li>
+ * <li>{@code enableOverloadRetargeting=true|false}. If true the driver may route a request to a different server on a subsequent
+ *  retry attempt if the previously used server is overloaded. Does not take effect for {@linkplain ClusterType#SHARDED sharded clusters}.
+ *  Defaults to false.</li>
  * <li>{@code uuidRepresentation=unspecified|standard|javaLegacy|csharpLegacy|pythonLegacy}.  See
  * {@link MongoClientSettings#getUuidRepresentation()} for documentation of semantics of this parameter.  Defaults to "javaLegacy", but
  * will change to "unspecified" in the next major release.</li>
@@ -308,6 +312,7 @@ public class ConnectionString {
     private WriteConcern writeConcern;
     private Boolean retryWrites;
     private Boolean retryReads;
+    private Boolean enableOverloadRetargeting;
     private ReadConcern readConcern;
 
     private Integer minConnectionPoolSize;
@@ -558,6 +563,7 @@ public ConnectionString(final String connectionString, @Nullable final DnsClient
         GENERAL_OPTIONS_KEYS.add("servermonitoringmode");
         GENERAL_OPTIONS_KEYS.add("retrywrites");
         GENERAL_OPTIONS_KEYS.add("retryreads");
+        GENERAL_OPTIONS_KEYS.add("enableoverloadretargeting");
 
         GENERAL_OPTIONS_KEYS.add("appname");
 
@@ -706,6 +712,9 @@ private void translateOptions(final Map<String, List<String>> optionsMap) {
                 case "retryreads":
                     retryReads = parseBoolean(value, "retryreads");
                     break;
+                case "enableoverloadretargeting":
+                    enableOverloadRetargeting = parseBoolean(value, "enableoverloadretargeting");
+                    break;
                 case "uuidrepresentation":
                     uuidRepresentation = createUuidRepresentation(value);
                     break;
@@ -1473,7 +1482,7 @@ public Boolean getRetryWritesValue() {
     /**
      * <p>Gets whether reads should be retried if they fail due to a network error</p>
      *
-     * @return the retryWrites value
+     * @return the retryReads value
      * @since 3.11
      * @mongodb.server.release 3.6
      */
@@ -1482,6 +1491,29 @@ public Boolean getRetryReads() {
         return retryReads;
     }
 
+    /**
+     * Gets whether overload retargeting is enabled.
+     *
+     * <p>When enabled, the previously selected servers on which attempts failed with an error
+     * {@linkplain MongoException#hasErrorLabel(String) having}
+     * the {@value MongoException#SYSTEM_OVERLOADED_ERROR_LABEL} label may be deprioritized during
+     * server selection on subsequent retry attempts. This applies to reads when retryReads is enabled,
+     * and to writes when retryWrites is enabled.</p>
+     *
+     * <p>This setting does not take effect for
+     * {@linkplain com.mongodb.connection.ClusterType#SHARDED sharded clusters}.</p>
+     *
+     * <p>Defaults to {@code false}.</p>
+     *
+     * @return the enableOverloadRetargeting value, or null if not set
+     * @see MongoClientSettings.Builder#enableOverloadRetargeting(boolean)
+     * @since 5.7
+     */
+    @Nullable
+    public Boolean getEnableOverloadRetargeting() {
+        return enableOverloadRetargeting;
+    }
+
     /**
      * Gets the minimum connection pool size specified in the connection string.
      * @return the minimum connection pool size
@@ -1795,6 +1827,7 @@ public boolean equals(final Object o) {
                 && Objects.equals(writeConcern, that.writeConcern)
                 && Objects.equals(retryWrites, that.retryWrites)
                 && Objects.equals(retryReads, that.retryReads)
+                && Objects.equals(enableOverloadRetargeting, that.enableOverloadRetargeting)
                 && Objects.equals(readConcern, that.readConcern)
                 && Objects.equals(minConnectionPoolSize, that.minConnectionPoolSize)
                 && Objects.equals(maxConnectionPoolSize, that.maxConnectionPoolSize)
@@ -1826,8 +1859,8 @@ public boolean equals(final Object o) {
     @Override
     public int hashCode() {
         return Objects.hash(credential, isSrvProtocol, hosts, database, collection, directConnection, readPreference,
-                writeConcern, retryWrites, retryReads, readConcern, minConnectionPoolSize, maxConnectionPoolSize, maxWaitTime,
-                maxConnectionIdleTime, maxConnectionLifeTime, maxConnecting, connectTimeout, timeout, socketTimeout, sslEnabled,
+                writeConcern, retryWrites, retryReads, enableOverloadRetargeting, readConcern, minConnectionPoolSize, maxConnectionPoolSize,
+                maxWaitTime, maxConnectionIdleTime, maxConnectionLifeTime, maxConnecting, connectTimeout, timeout, socketTimeout, sslEnabled,
                 sslInvalidHostnameAllowed, requiredReplicaSetName, serverSelectionTimeout, localThreshold, heartbeatFrequency,
                 serverMonitoringMode, applicationName, compressorList, uuidRepresentation, srvServiceName, srvMaxHosts, proxyHost,
                 proxyPort, proxyUsername, proxyPassword);

driver-core/src/main/com/mongodb/MongoClientSettings.java

@@ -24,6 +24,7 @@
 import com.mongodb.client.model.geojson.codecs.GeoJsonCodecProvider;
 import com.mongodb.client.model.mql.ExpressionCodecProvider;
 import com.mongodb.connection.ClusterSettings;
+import com.mongodb.connection.ClusterType;
 import com.mongodb.connection.ConnectionPoolSettings;
 import com.mongodb.connection.ServerSettings;
 import com.mongodb.connection.SocketSettings;
@@ -93,6 +94,7 @@ public final class MongoClientSettings {
     private final WriteConcern writeConcern;
     private final boolean retryWrites;
     private final boolean retryReads;
+    private final boolean enableOverloadRetargeting;
     private final ReadConcern readConcern;
     private final MongoCredential credential;
     private final TransportSettings transportSettings;
@@ -214,6 +216,7 @@ public static final class Builder {
         private WriteConcern writeConcern = WriteConcern.ACKNOWLEDGED;
         private boolean retryWrites = true;
         private boolean retryReads = true;
+        private boolean enableOverloadRetargeting = false;
         private ReadConcern readConcern = ReadConcern.DEFAULT;
         private CodecRegistry codecRegistry = MongoClientSettings.getDefaultCodecRegistry();
         private TransportSettings transportSettings;
@@ -255,6 +258,7 @@ private Builder(final MongoClientSettings settings) {
             writeConcern = settings.getWriteConcern();
             retryWrites = settings.getRetryWrites();
             retryReads = settings.getRetryReads();
+            enableOverloadRetargeting = settings.getEnableOverloadRetargeting();
             readConcern = settings.getReadConcern();
             credential = settings.getCredential();
             uuidRepresentation = settings.getUuidRepresentation();
@@ -314,6 +318,10 @@ public Builder applyConnectionString(final ConnectionString connectionString) {
             if (retryReadsValue != null) {
                 retryReads = retryReadsValue;
             }
+            Boolean enableOverloadRetargetingValue = connectionString.getEnableOverloadRetargeting();
+            if (enableOverloadRetargetingValue != null) {
+                enableOverloadRetargeting = enableOverloadRetargetingValue;
+            }
             if (connectionString.getUuidRepresentation() != null) {
                 uuidRepresentation = connectionString.getUuidRepresentation();
             }
@@ -456,6 +464,30 @@ public Builder retryReads(final boolean retryReads) {
             return this;
         }
 
+        /**
+         * Sets whether to enable overload retargeting.
+         *
+         * <p>When enabled, the previously selected servers on which attempts failed with an error
+         * {@linkplain MongoException#hasErrorLabel(String) having}
+         * the {@value MongoException#SYSTEM_OVERLOADED_ERROR_LABEL} label may be deprioritized during
+         * server selection on subsequent retry attempts. This applies to reads when
+         * {@linkplain #retryReads(boolean) retryReads} is enabled, and to writes when
+         * {@linkplain #retryWrites(boolean) retryWrites} is enabled.</p>
+         *
+         * <p>This setting does not take effect for {@linkplain ClusterType#SHARDED sharded clusters}.</p>
+         *
+         * <p>Defaults to {@code false}.</p>
+         *
+         * @param enableOverloadRetargeting whether to enable overload retargeting.
+         * @return this
+         * @see #getEnableOverloadRetargeting()
+         * @since 5.7
+         */
+        public Builder enableOverloadRetargeting(final boolean enableOverloadRetargeting) {
+            this.enableOverloadRetargeting = enableOverloadRetargeting;
+            return this;
+        }
+
         /**
          * Sets the read concern.
          *
@@ -807,6 +839,18 @@ public boolean getRetryReads() {
         return retryReads;
     }
 
+    /**
+     * Returns whether overload retargeting is enabled.
+     * See {@link Builder#enableOverloadRetargeting(boolean)} for more information.
+     *
+     * @return the enableOverloadRetargeting value
+     * @see Builder#enableOverloadRetargeting(boolean)
+     * @since 5.7
+     */
+    public boolean getEnableOverloadRetargeting() {
+        return enableOverloadRetargeting;
+    }
+
     /**
      * The read concern to use.
      *
@@ -1080,6 +1124,7 @@ public boolean equals(final Object o) {
         MongoClientSettings that = (MongoClientSettings) o;
         return retryWrites == that.retryWrites
                 && retryReads == that.retryReads
+                && enableOverloadRetargeting == that.enableOverloadRetargeting
                 && heartbeatSocketTimeoutSetExplicitly == that.heartbeatSocketTimeoutSetExplicitly
                 && heartbeatConnectTimeoutSetExplicitly == that.heartbeatConnectTimeoutSetExplicitly
                 && Objects.equals(readPreference, that.readPreference)
@@ -1109,8 +1154,8 @@ public boolean equals(final Object o) {
 
     @Override
     public int hashCode() {
-        return Objects.hash(readPreference, writeConcern, retryWrites, retryReads, readConcern, credential, transportSettings,
-                commandListeners, codecRegistry, loggerSettings, clusterSettings, socketSettings,
+        return Objects.hash(readPreference, writeConcern, retryWrites, retryReads, enableOverloadRetargeting, readConcern, credential,
+                transportSettings, commandListeners, codecRegistry, loggerSettings, clusterSettings, socketSettings,
                 heartbeatSocketSettings, connectionPoolSettings, serverSettings, sslSettings, applicationName, compressorList,
                 uuidRepresentation, serverApi, autoEncryptionSettings, heartbeatSocketTimeoutSetExplicitly,
                 heartbeatConnectTimeoutSetExplicitly, dnsClient, inetAddressResolver, contextProvider, timeoutMS);
@@ -1124,6 +1169,7 @@ public String toString() {
                 + ", writeConcern=" + writeConcern
                 + ", retryWrites=" + retryWrites
                 + ", retryReads=" + retryReads
+                + ", enableOverloadRetargeting=" + enableOverloadRetargeting
                 + ", readConcern=" + readConcern
                 + ", credential=" + credential
                 + ", transportSettings=" + transportSettings
@@ -1154,6 +1200,7 @@ private MongoClientSettings(final Builder builder) {
         writeConcern = builder.writeConcern;
         retryWrites = builder.retryWrites;
         retryReads = builder.retryReads;
+        enableOverloadRetargeting = builder.enableOverloadRetargeting;
         readConcern = builder.readConcern;
         credential = builder.credential;
         transportSettings = builder.transportSettings;

driver-core/src/main/com/mongodb/internal/connection/BaseCluster.java

@@ -113,9 +113,9 @@ abstract class BaseCluster implements Cluster {
     private volatile ClusterDescription description;
 
     BaseCluster(final ClusterId clusterId,
-                final ClusterSettings settings,
-                final ClusterableServerFactory serverFactory,
-                final ClientMetadata clientMetadata) {
+                          final ClusterSettings settings,
+                          final ClusterableServerFactory serverFactory,
+                          final ClientMetadata clientMetadata) {
         this.clusterId = notNull("clusterId", clusterId);
         this.settings = notNull("settings", settings);
         this.serverFactory = notNull("serverFactory", serverFactory);
@@ -159,7 +159,7 @@ public ServerTuple selectServer(final ServerSelector serverSelector, final Opera
             if (serverTuple != null) {
                 ServerAddress serverAddress = serverTuple.getServerDescription().getAddress();
                 logServerSelectionSucceeded(operationContext, clusterId, serverAddress, serverSelector, currentDescription);
-                serverDeprioritization.updateCandidate(serverAddress);
+                serverDeprioritization.updateCandidate(serverAddress, currentDescription.getType());
                 return serverTuple;
             }
             computedServerSelectionTimeout.onExpired(() ->
@@ -302,7 +302,7 @@ private boolean handleServerSelectionRequest(
                 if (serverTuple != null) {
                     ServerAddress serverAddress = serverTuple.getServerDescription().getAddress();
                     logServerSelectionSucceeded(operationContext, clusterId, serverAddress, request.originalSelector, description);
-                    serverDeprioritization.updateCandidate(serverAddress);
+                    serverDeprioritization.updateCandidate(serverAddress, description.getType());
                     request.onResult(serverTuple, null);
                     return true;
                 }
@@ -361,8 +361,7 @@ private static ServerSelector getCompleteServerSelector(
             final ClusterSettings settings) {
         List<ServerSelector> selectors = Stream.of(
                 getRaceConditionPreFilteringSelector(serversSnapshot),
-                serverSelector,
-                serverDeprioritization.getServerSelector(),
+                serverDeprioritization.apply(serverSelector),
                 settings.getServerSelector(), // may be null
                 new LatencyMinimizingServerSelector(settings.getLocalThreshold(MILLISECONDS), MILLISECONDS),
                 AtMostTwoRandomServerSelector.instance(),