Add enableOverloadRetargeting API

[vbabanin]

• Add enableOverloadRetargeting boolean option to MongoClientSettings and ConnectionString to allow
  the driver to route requests to a different replica set member on retries when the previously
  used server is overloaded

• Add prose test 3.3 to verify that overload errors are retried on the same server when retargeting
  is disabled

  JAVA-6167

[Copilot]

Pull request overview

Adds a new enableOverloadRetargeting client/URI option and wires it through operation execution so the driver can deprioritize overloaded servers during retry server selection (per spec), along with new/updated prose and unit tests.

Changes:

• Add enableOverloadRetargeting to MongoClientSettings, ConnectionString, and legacy MongoClientOptions/MongoClientURI parsing.
• Propagate the setting into OperationContext.ServerDeprioritization and integrate it into server selection in BaseCluster.
• Refactor/extend retryable reads prose tests and update many tests to use ClusterFixture.createOperationContext() instead of a shared static context.

Reviewed changes

Copilot reviewed 102 out of 102 changed files in this pull request and generated 2 comments.

Show a summary per file

File	Description
driver-sync/src/test/unit/com/mongodb/client/internal/MongoClusterSpecification.groovy	Passes enableOverloadRetargeting into MongoClusterImpl in tests.
driver-sync/src/test/unit/com/mongodb/client/internal/CryptConnectionSpecification.groovy	Uses ClusterFixture.createOperationContext() in tests.
driver-sync/src/test/unit/com/mongodb/client/internal/ClientSessionBindingSpecification.groovy	Uses createOperationContext() instead of static OPERATION_CONTEXT.
driver-sync/src/test/functional/com/mongodb/client/RetryableReadsProseTest.java	Refactors sync prose tests into an abstract base.
driver-sync/src/test/functional/com/mongodb/client/AbstractRetryableReadsProseTest.java	Adds retryable-reads prose tests 3.1–3.3 for overload retargeting behavior.
driver-sync/src/main/com/mongodb/client/internal/MongoClusterImpl.java	Stores/propagates enableOverloadRetargeting into OperationContext.
driver-sync/src/main/com/mongodb/client/internal/MongoClientImpl.java	Passes enableOverloadRetargeting from settings to MongoClusterImpl.
driver-reactive-streams/src/test/unit/com/mongodb/reactivestreams/client/internal/ClientSessionBindingSpecification.groovy	Uses createOperationContext() in reactive streams tests.
driver-reactive-streams/src/test/functional/com/mongodb/reactivestreams/client/RetryableReadsProseTest.java	Reuses shared abstract prose tests via SyncMongoClient.
driver-reactive-streams/src/main/com/mongodb/reactivestreams/client/internal/OperationExecutorImpl.java	Adds ServerDeprioritization(enableOverloadRetargeting) to operation context creation.
driver-legacy/src/test/unit/com/mongodb/MongoClientURISpecification.groovy	Adds URI parsing tests for enableOverloadRetargeting.
driver-legacy/src/test/unit/com/mongodb/MongoClientOptionsSpecification.groovy	Adds builder/settings propagation tests for enableOverloadRetargeting.
driver-legacy/src/test/functional/com/mongodb/LegacyMixedBulkWriteOperationSpecification.groovy	Uses createOperationContext(readPreference) helper.
driver-legacy/src/test/functional/com/mongodb/DBTest.java	Uses ClusterFixture.createOperationContext() in legacy functional test.
driver-legacy/src/main/com/mongodb/MongoClientURI.java	Documents and applies enableOverloadRetargeting from parsed URI options.
driver-legacy/src/main/com/mongodb/MongoClientOptions.java	Adds getEnableOverloadRetargeting and builder setter for legacy options.
driver-core/src/test/unit/com/mongodb/internal/session/ServerSessionPoolSpecification.groovy	Uses createOperationContext() instead of static context in unit tests.
driver-core/src/test/unit/com/mongodb/internal/session/BaseClientSessionImplTest.java	Uses createOperationContext() when creating ServerSessionPool.
driver-core/src/test/unit/com/mongodb/internal/operation/SyncOperationHelperSpecification.groovy	Updates tests to pass fresh operation contexts.
driver-core/src/test/unit/com/mongodb/internal/operation/OperationUnitSpecification.groovy	Updates tests to pass fresh operation contexts.
driver-core/src/test/unit/com/mongodb/internal/operation/OperationHelperSpecification.groovy	Updates retryability tests to use createOperationContext().
driver-core/src/test/unit/com/mongodb/internal/operation/ListCollectionsOperationTest.java	Uses createOperationContext() for operation execution.
driver-core/src/test/unit/com/mongodb/internal/operation/CursorResourceManagerTest.java	Uses createOperationContext() in cursor resource manager tests.
driver-core/src/test/unit/com/mongodb/internal/operation/CommitTransactionOperationUnitSpecification.groovy	Uses createOperationContext() for sync/async execution tests.
driver-core/src/test/unit/com/mongodb/internal/operation/ClientBulkWriteOperationTest.java	Uses createOperationContext() in bulk write unit tests.
driver-core/src/test/unit/com/mongodb/internal/operation/AsyncOperationHelperSpecification.groovy	Updates async helper tests to use createOperationContext().
driver-core/src/test/unit/com/mongodb/internal/mockito/InsufficientStubbingDetectorDemoTest.java	Uses createOperationContext() in demo test assertions/stubbing.
driver-core/src/test/unit/com/mongodb/internal/connection/X509AuthenticatorUnitTest.java	Uses createOperationContext() when authenticating.
driver-core/src/test/unit/com/mongodb/internal/connection/X509AuthenticatorNoUserNameTest.java	Uses createOperationContext() when authenticating.
driver-core/src/test/unit/com/mongodb/internal/connection/UsageTrackingConnectionSpecification.groovy	Uses createOperationContext() across connection usage tests.
driver-core/src/test/unit/com/mongodb/internal/connection/SingleServerClusterSpecification.groovy	Uses createOperationContext() in server snapshot/selection tests.
driver-core/src/test/unit/com/mongodb/internal/connection/ServerSelectionWithinLatencyWindowTest.java	Fixes import path for buildClusterDescription.
driver-core/src/test/unit/com/mongodb/internal/connection/ServerSelectionSelectionTest.java	Refactors server-selection spec tests to use a test cluster and support deprioritized servers input.
driver-core/src/test/unit/com/mongodb/internal/connection/ServerDiscoveryAndMonitoringTest.java	Uses createOperationContext() for server snapshot/timeouts.
driver-core/src/test/unit/com/mongodb/internal/connection/ServerDeprioritizationTest.java	Adds comprehensive tests for deprioritization behavior across topologies/errors.
driver-core/src/test/unit/com/mongodb/internal/connection/PlainAuthenticatorUnitTest.java	Uses createOperationContext() when authenticating.
driver-core/src/test/unit/com/mongodb/internal/connection/MultiServerClusterSpecification.groovy	Uses createOperationContext() in multi-server cluster tests.
driver-core/src/test/unit/com/mongodb/internal/connection/LoggingCommandEventSenderSpecification.groovy	Uses createOperationContext() in logging tests.
driver-core/src/test/unit/com/mongodb/internal/connection/LoadBalancedClusterTest.java	Uses createOperationContext() in LB cluster selection tests.
driver-core/src/test/unit/com/mongodb/internal/connection/JMXConnectionPoolListenerSpecification.groovy	Uses createOperationContext() in JMX pool listener tests.
driver-core/src/test/unit/com/mongodb/internal/connection/InternalStreamConnectionSpecification.groovy	Uses createOperationContext() broadly in stream connection tests.
driver-core/src/test/unit/com/mongodb/internal/connection/DefaultServerSpecification.groovy	Uses createOperationContext() for connection acquisition tests.
driver-core/src/test/unit/com/mongodb/internal/connection/DefaultServerConnectionSpecification.groovy	Creates a local operation context and uses it consistently in expectations.
driver-core/src/test/unit/com/mongodb/internal/connection/DefaultConnectionPoolSpecification.groovy	Uses createOperationContext() in pool unit tests.
driver-core/src/test/unit/com/mongodb/internal/connection/BaseClusterTest.java	Uses fresh operation context for ServerDeprioritization in test cluster selection.
driver-core/src/test/unit/com/mongodb/internal/connection/BaseClusterSpecification.groovy	Uses createOperationContext() for selection tests.
driver-core/src/test/unit/com/mongodb/internal/connection/AbstractServerDiscoveryAndMonitoringTest.java	Uses createOperationContext() for selection timeout/timeoutContext usage.
driver-core/src/test/unit/com/mongodb/internal/connection/AbstractConnectionPoolTest.java	Uses createOperationContext() for admin commands in tests.
driver-core/src/test/unit/com/mongodb/internal/binding/SingleServerBindingSpecification.groovy	Uses createOperationContext() in binding tests.
driver-core/src/test/unit/com/mongodb/UriOptionsTest.java	Skips maxAdaptiveRetries until supported (test guard).
driver-core/src/test/unit/com/mongodb/MongoClientSettingsSpecification.groovy	Updates reflection-based field/method lists for new builder option.
driver-core/src/test/unit/com/mongodb/ConnectionStringUnitTest.java	Adds parsing tests for enableOverloadRetargeting.
driver-core/src/test/unit/com/mongodb/AbstractConnectionStringTest.java	Adds generic assertion for enableOverloadRetargeting in option tests.
driver-core/src/test/functional/com/mongodb/internal/operation/TestOperationHelper.java	Uses createOperationContext() for additional getMore calls.
driver-core/src/test/functional/com/mongodb/internal/operation/RenameCollectionOperationSpecification.groovy	Uses createOperationContext(readPreference) helper.
driver-core/src/test/functional/com/mongodb/internal/operation/MapReduceWithInlineResultsOperationSpecification.groovy	Uses createOperationContext() for read concern tests.
driver-core/src/test/functional/com/mongodb/internal/operation/MapReduceToCollectionOperationSpecification.groovy	Uses createOperationContext(readPreference) in cleanup.
driver-core/src/test/functional/com/mongodb/internal/operation/ListIndexesOperationSpecification.groovy	Uses createOperationContext(readPreference) and local contexts for assertions.
driver-core/src/test/functional/com/mongodb/internal/operation/ListDatabasesOperationSpecification.groovy	Uses createOperationContext() for sync/async execution.
driver-core/src/test/functional/com/mongodb/internal/operation/ListCollectionsOperationSpecification.groovy	Uses createOperationContext(readPreference) and local contexts for assertions.
driver-core/src/test/functional/com/mongodb/internal/operation/FindOperationSpecification.groovy	Uses createOperationContext() for profiling/read concern/timeout cases.
driver-core/src/test/functional/com/mongodb/internal/operation/DropIndexOperationSpecification.groovy	Uses createOperationContext(readPreference) for index listing.
driver-core/src/test/functional/com/mongodb/internal/operation/DropDatabaseOperationSpecification.groovy	Uses createOperationContext(readPreference) for execution/exists checks.
driver-core/src/test/functional/com/mongodb/internal/operation/DropCollectionOperationSpecification.groovy	Uses createOperationContext(readPreference) for execution/exists checks.
driver-core/src/test/functional/com/mongodb/internal/operation/DistinctOperationSpecification.groovy	Uses createOperationContext() for read concern tests.
driver-core/src/test/functional/com/mongodb/internal/operation/CreateViewOperationSpecification.groovy	Uses createOperationContext(readPreference) for list collections lookup.
driver-core/src/test/functional/com/mongodb/internal/operation/CreateIndexesOperationSpecification.groovy	Uses createOperationContext(readPreference) for list indexes.
driver-core/src/test/functional/com/mongodb/internal/operation/CreateCollectionOperationSpecification.groovy	Uses createOperationContext(readPreference) for list collections/stats.
driver-core/src/test/functional/com/mongodb/internal/operation/CountDocumentsOperationSpecification.groovy	Uses createOperationContext() for read concern tests and index creation.
driver-core/src/test/functional/com/mongodb/internal/operation/CommandBatchCursorFunctionalTest.java	Uses createOperationContext() throughout cursor functional tests.
driver-core/src/test/functional/com/mongodb/internal/operation/ChangeStreamOperationSpecification.groovy	Uses createOperationContext() for read concern/session context tests.
driver-core/src/test/functional/com/mongodb/internal/operation/AsyncCommandBatchCursorFunctionalTest.java	Uses createOperationContext() throughout async cursor functional tests.
driver-core/src/test/functional/com/mongodb/internal/operation/AggregateToCollectionOperationSpecification.groovy	Uses createOperationContext(readPreference) for profiling setup/cleanup.
driver-core/src/test/functional/com/mongodb/internal/operation/AggregateOperationSpecification.groovy	Uses createOperationContext(readPreference) and local contexts for tests.
driver-core/src/test/functional/com/mongodb/internal/connection/TlsChannelStreamFunctionalTest.java	Uses createOperationContext() in stream open/write.
driver-core/src/test/functional/com/mongodb/internal/connection/StreamSocketAddressSpecification.groovy	Uses createOperationContext() in socket stream tests.
driver-core/src/test/functional/com/mongodb/internal/connection/SocketStreamHelperSpecification.groovy	Uses createOperationContext() and local timeout overrides.
driver-core/src/test/functional/com/mongodb/internal/connection/SingleServerClusterTest.java	Uses createOperationContext() for selection and read preference test.
driver-core/src/test/functional/com/mongodb/internal/connection/ServerHelper.java	Uses createOperationContext() for server selection in helper methods.
driver-core/src/test/functional/com/mongodb/internal/connection/ScramSha256AuthenticationSpecification.groovy	Uses createOperationContext() in authentication flows.
driver-core/src/test/functional/com/mongodb/internal/connection/PlainAuthenticatorTest.java	Uses createOperationContext() for auth tests.
driver-core/src/test/functional/com/mongodb/internal/connection/PlainAuthenticationSpecification.groovy	Uses createOperationContext() in command/auth flows.
driver-core/src/test/functional/com/mongodb/internal/connection/GSSAPIAuthenticatorSpecification.groovy	Uses createOperationContext() for connection open.
driver-core/src/test/functional/com/mongodb/internal/connection/GSSAPIAuthenticationSpecification.groovy	Uses createOperationContext() in command/auth flows.
driver-core/src/test/functional/com/mongodb/internal/connection/DefaultConnectionPoolTest.java	Uses createOperationContext() in pool functional tests.
driver-core/src/test/functional/com/mongodb/internal/connection/CommandHelperSpecification.groovy	Uses createOperationContext() for async command execution in tests.
driver-core/src/test/functional/com/mongodb/internal/connection/AwsAuthenticationSpecification.groovy	Uses createOperationContext() in command/auth flows.
driver-core/src/test/functional/com/mongodb/internal/connection/AsyncStreamTimeoutsSpecification.groovy	Uses createOperationContext() for stream open tests.
driver-core/src/test/functional/com/mongodb/internal/connection/AsyncSocketChannelStreamSpecification.groovy	Uses createOperationContext() for open/openAsync tests.
driver-core/src/test/functional/com/mongodb/internal/binding/AsyncSessionBindingSpecification.groovy	Uses createOperationContext() in async binding wrapper tests.
driver-core/src/test/functional/com/mongodb/connection/netty/NettyStreamSpecification.groovy	Uses createOperationContext() for stream open/openAsync tests.
driver-core/src/test/functional/com/mongodb/connection/ConnectionSpecification.groovy	Uses a local operation context consistently for connection source/connection usage.
driver-core/src/test/functional/com/mongodb/client/test/CollectionHelper.java	Uses createOperationContext() for core operations in test helper.
driver-core/src/test/functional/com/mongodb/OperationFunctionalSpecification.groovy	Uses createOperationContext() for functional execution helpers.
driver-core/src/test/functional/com/mongodb/ClusterFixture.java	Replaces static OPERATION_CONTEXT with factory methods (createOperationContext).
driver-core/src/main/com/mongodb/internal/operation/ChangeStreamBatchCursor.java	Resets server deprioritization state for initial change stream context.
driver-core/src/main/com/mongodb/internal/operation/AsyncChangeStreamBatchCursor.java	Resets server deprioritization state for initial async change stream context.
driver-core/src/main/com/mongodb/internal/connection/OperationContext.java	Adds overload-retargeting-aware ServerDeprioritization and selector wrapping logic.
driver-core/src/main/com/mongodb/internal/connection/BaseCluster.java	Integrates deprioritization wrapper into complete server selector and candidate tracking.
driver-core/src/main/com/mongodb/MongoClientSettings.java	Adds enableOverloadRetargeting setting, parsing, equals/hashCode/toString.
driver-core/src/main/com/mongodb/ConnectionString.java	Adds enableOverloadRetargeting URI option parsing and accessor.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 102 out of 102 changed files in this pull request and generated 1 comment.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[Copilot]

Pull request overview

Copilot reviewed 17 out of 17 changed files in this pull request and generated 3 comments.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.