Skip to content

Add enableOverloadRetargeting API#1943

Draft
vbabanin wants to merge 62 commits intomongodb:backpressurefrom
vbabanin:JAVA-6167
Draft

Add enableOverloadRetargeting API#1943
vbabanin wants to merge 62 commits intomongodb:backpressurefrom
vbabanin:JAVA-6167

Conversation

@vbabanin
Copy link
Copy Markdown
Member

@vbabanin vbabanin commented Apr 17, 2026

  • 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

    Should be reviewed after Add support for server selection's deprioritized servers to all topologies. #1860 has been merged.

    JAVA-6167

vbabanin and others added 30 commits April 15, 2026 17:43
…Context.java

Co-authored-by: Valentin Kovalenko <valentin.male.kovalenko@gmail.com>
…onSelectionTest.java

Co-authored-by: Valentin Kovalenko <valentin.male.kovalenko@gmail.com>
…onSelectionTest.java

Co-authored-by: Valentin Kovalenko <valentin.male.kovalenko@gmail.com>
…erDeprioritizationTest.java

Co-authored-by: Valentin Kovalenko <valentin.male.kovalenko@gmail.com>
vbabanin and others added 14 commits April 15, 2026 22:55
- Reuse single OperationContext in SingleServerClusterSpecification instead of creating two independent instances
- Preserve srvResolutionException when creating filtered ClusterDescription in DeprioritizingSelector

JAVA-6021
…n replica sets

- Gate server deprioritization in onAttemptFailure: sharded clusters deprioritize on any error, all other topologies only on SystemOverloadedError
- Pass ClusterType to updateCandidate so onAttemptFailure can distinguish topology types
- Parameterize ServerDeprioritizationTest by cluster type and error type to cover conditional deprioritization
- Add retryable reads prose tests 3.1 and 3.2

JAVA-6105
…onSelectionTest.java

Co-authored-by: Ross Lawley <ross.lawley@gmail.com>
…Context.java

Co-authored-by: Ross Lawley <ross.lawley@gmail.com>
…Context.java

Co-authored-by: Ross Lawley <ross.lawley@gmail.com>
…Context.java

Co-authored-by: Ross Lawley <ross.lawley@gmail.com>
…ultServerSpecification.groovy

Co-authored-by: Ross Lawley <ross.lawley@gmail.com>
- Remove redundant @VisibleForTesting annotation and use static import for SYSTEM_OVERLOADED_ERROR_LABEL constant
- Fix ServerDeprioritizationTest to use parameterized cluster in assertions instead of SHARDED_CLUSTER constant
- Move ServerSelectionSelectionTest to internal.connection package and update references
- Update TODO comments to TODO-BACKPRESSURE format with JAVA-6167 reference

JAVA-6021
- 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
@vbabanin vbabanin changed the title Java 6167 Add enableOverloadRetargeting API Apr 17, 2026
@vbabanin vbabanin self-assigned this Apr 17, 2026
@vbabanin vbabanin requested a review from rozza April 17, 2026 16:54
@stIncMale stIncMale changed the title Add enableOverloadRetargeting API Add enableOverloadRetargeting API Apr 17, 2026
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment thread driver-sync/src/main/com/mongodb/client/internal/MongoClusterImpl.java Outdated
Copy link
Copy Markdown
Contributor

Copilot AI left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

Comment on lines +175 to +187
@Test
void overloadErrorRetriedOnSameReplicaSetServerWhenRetargetingDisabled() throws InterruptedException {
BsonDocument configureFailPoint = BsonDocument.parse(
"{\n"
+ " configureFailPoint: \"failCommand\",\n"
+ " mode: { times: 1 },\n"
+ " data: {\n"
+ " failCommands: [\"find\"],\n"
+ " errorLabels: ['" + RETRYABLE_ERROR_LABEL + "', '" + SYSTEM_OVERLOADED_ERROR_LABEL + "'],\n"
+ " errorCode: 6\n"
+ " }\n"
+ "}\n");
testRetriedOnTheSameServer(configureFailPoint);
Copy link

Copilot AI Apr 18, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

overloadErrorRetriedOnSameReplicaSetServerWhenRetargetingDisabled relies on the default value of enableOverloadRetargeting (it is never set in the client settings). This makes the test intent fragile if the default changes and also doesn't explicitly prove the "disabled" behavior described in the test name/spec. Consider explicitly setting .enableOverloadRetargeting(false) for this test (or parameterizing testRetriedOnTheSameServer to control the option).

Copilot uses AI. Check for mistakes.
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants