Client Backpressure by stIncMale · Pull Request #1918 · mongodb/mongo-java-driver

stIncMale · 2026-03-21T03:55:49Z

How to include `main` changes into `backpressure`

Rebase backpressure on top of main when there are no outstanding PRs for backpressure that are being reviewed, because this leads to GitHub closing the PRs.

See #1917 (comment) for more details.

How to deal with TODOs

TODO-BACKPRESSURE is the tag we use to leave TODOs in PRs for the backpressure branch that must be addressed before the current PR is merged in main. When we are leaving such a comment, and we know who should be responsible for addressing it, we should add the name of that engineer in the comment (for example, @stIncMale uses TODO-BACKPRESSURE Valentin for the TODOs he should address).

JAVA-5942, JAVA-6019, JAVA-6261

evergreen-ci-prod · 2026-05-08T20:58:40Z

There is an existing patch(es) for this commit SHA:

Evergreen patch with PR

Please note that the status that is posted is not in the context of this PR but rather the (latest) existing patch and that may affect some tests that may depend on the particular PR. If your tests do not rely on any PR-specific values (like base or head branch name) then your tests will report the same status. If you would like a patch to run in the context of this PR and abort the other(s), comment 'evergreen retry'.

stIncMale · 2026-06-03T19:04:04Z

The latest Evergreen build for this PR did succeed.

Judging from a build result in a different PR that targets the backpressure branch, I suspect that some tests started failing without driver-side code changes (without even the specifications submodule changes). So I am rerunning the build here, to see how it goes. Update: it failed, and I left a PR comment that we'll need to address.

The relevant spec changes: - https://github.com/mongodb/specifications/blame/ba14b6bdc1dc695aa9cc20ccf9378592da1b2329/source/retryable-writes/tests/README.md#L265-L418 - See also https://jira.mongodb.org/browse/DRIVERS-3432 for the phrasing fixes for "Test 3 Case 3" JAVA-6055

JAVA-6141

- Deprioritize sharded clusters on any error, all other topologies only on SystemOverloadedError. - Pass ClusterType to updateCandidate so onAttemptFailure can distinguish topology types. - Add retryable reads prose tests 3.1 and 3.2. - Change ServerSelectionSelectionTest to use BaseCluster server selection chain. JAVA-6105 JAVA-6021 JAVA-6074 --------- Co-authored-by: Valentin Kovalenko <valentin.male.kovalenko@gmail.com> Co-authored-by: Ross Lawley <ross.lawley@gmail.com>

The relevant spec changes: - https://github.com/mongodb/specifications/blob/8a8a7c56429c80b51ec62268dcafc5e5e3c477ef/source/client-backpressure/tests/README.md JAVA-5956, JAVA-6117, JAVA-6113, JAVA-6119, JAVA-6141

- 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 --------- Co-authored-by: Ross Lawley <ross.lawley@gmail.com>

…#1949)

… on retries (#1899)

…ishing connections (#1900)

…1978)

…#1968) JAVA-6035: Add backpressure flag to connection handshake (#1906)

JAVA-6167

JAVA-6218

JAVA-6229

Introduce `sleepAsync`, `CommonExecutor`, `AsyncClientExecutor` Notable changes: - `MongoThreadPoolExecutor`/`MongoScheduledThreadPoolExecutor` - the executors we should eventually use everywhere internally (see https://jira.mongodb.org/browse/JAVA-6109), because they make sure uncaught task failures are propagated to the `UncaughtExceptionHandler`. - `RetryPolicy.Decision.RetryAttemptInfo.getBackoff` - allows `RetryPolicy` to require the immediate next attempt to be delayed. - `ThreadUtil.sleep`/`sleepAsync` - allows sleeping in `RetryingSyncSupplier`/`RetryingAsyncCallbackSupplier` based on the `RetryAttemptInfo.getBackoff`. - `StreamFactoryFactory.getExecutor` - exposes the I/O executor used by `Stream`s to the rest of the `MongoClient` components. - `AsyncClientExecutor` - allows to schedule a task using the aforementioned I/O executor, which saves us from creating another thread pool per `MongoClient`, essentially duplicating the I/O executor. - `CommonExecutor` - provides the scheduling functionality when the I/O executor is not a `ScheduledThreadPoolExecutor` at the cost of a single new thread per class loader. `AsyncClientExecutor` and `CommonExecutor` should eventually manage all internal computational resources (see https://jira.mongodb.org/browse/JAVA-4930). JAVA-6240

…retryable (#2041) JAVA-6248

- Extend SpecRetryPolicy so the overload sub-policy can borrow the write policy's error propagation logic independently of includeWrite(), enabling runCommand's client-backpressure rules without pulling in unwanted write-retry decisions. - Split CommandReadOperation into an abstract base plus a concrete runCommand subclass that composes overload-only retries gated on retryReads && retryWrites; explain operations continue to use the base with no retry. JAVA-6294

- Wrap CommandCursor / AsyncCommandCursor getMore in the SpecRetryPolicy overload-retry loop, gated by retryReads and propagated as a read command per client-backpressure, so any read cursor (find, aggregate, listCollections, listIndexes, changeStream) and the bulk-write result cursor participates in the overload-retry loop when iterating. - Threads retryReads / maxAdaptiveRetries through to cursor construction sites, including ClientBulkWriteOperation whose result-cursor getMore is a read at the wire level despite the parent being a write. - Extend the overload sub-policy with sessionScopeUpdatesSuspended so a nested retry loop (cursor getMore invoked inside another retry supplier such as the bulk-write cursor exhaust under RetryControl.doWhileDisabled) does not open, mutate, or close the parent's still-open command execution scope on the session. - Remove the JAVA-5956 skip for the getMore-retried-backpressure unified test and adds coverage prose tests for the bulk-write cursor's getMore under overload retry, non-overload propagation, and retryReads=false. JAVA-6296

- Implements overload-only retry (gated on retryWrites) for the write commands that previously dispatched with no retry wrapper: createIndexes, dropIndexes, create/drop/rename collection, aggregate with $out/$merge, and the search-index commands. - Removes the JAVA-5956 skips that hid these commands from the unified client-backpressure suite, and adds prose tests (not part of the spec suite) covering the commands that have no unified test coverage. JAVA-6308 JAVA-6119 JAVA-6124 JAVA-5956

Co-authored-by: Viacheslav Babanin <frest0512@gmail.com> --------- Co-authored-by: Viacheslav Babanin <frest0512@gmail.com>

JAVA-6243

- Send backpressure: "2" in handshake. - Add MongoDB 9.0 to Evergreen version matrix. - Add baseBackoffMS override prose test (Test 5). - Support server-supplied baseBackoffMS override for overload backoff. JAVA-6238 JAVA-6255

…or` (#2056) Non-terminated global threads are a problem as described in https://jira.mongodb.org/browse/JAVA-6291, https://jira.mongodb.org/browse/JAVA-5643. We know that there is at least one user who suffers from it and has a [workaround|#2029]. That workaround handles only the global thread in `PowerOfTwoBufferPool`, and will break when we release backpressure with another global thread in the `CommonExecutor`. We temporarily stopped using `CommonExecutor` in `DefaultAsyncClientExecutor`, and use its own single-thread scheduler instead. We pay by sometimes creating a new thread per instance of `MongoClient`, but the aforementioned user workaround continues to work. When we do https://jira.mongodb.org/browse/JAVA-6291, which will fix the problem in both `PowerOfTwoBufferPool` and `CommonExecutor`, we will change `DefaultAsyncClientExecutor` back to using `CommonExecutor`. JAVA-6292

We retry everything we must according to the spec, except for `killCursors`. Despite the specification requiring us to retry it, other drivers did not implement retries for this command, neither did the Java driver. The decision/spec will be reevaluated. For now we have https://jira.mongodb.org/browse/JAVA-6309.

…h the `main` branch (#2060) Rebasing `backpressure` on top of `main` did not achieve that.

stIncMale requested review from nhachicha and vbabanin March 21, 2026 03:55

stIncMale requested a review from a team as a code owner March 21, 2026 03:55

stIncMale commented Mar 24, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/MongoException.java

stIncMale commented Mar 24, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/internal/connection/InternalStreamConnectionInitializer.java Outdated

stIncMale mentioned this pull request Mar 27, 2026

JAVA-6055 Implement prose backpressure retryable writes tests #1929

Merged

nhachicha reviewed Apr 1, 2026

View reviewed changes

Comment thread driver-sync/src/test/functional/com/mongodb/client/WithTransactionProseTest.java

stIncMale mentioned this pull request Apr 16, 2026

Add support for server selection's deprioritized servers to all topologies. #1860

Merged

1 task done

stIncMale commented Apr 17, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/MongoException.java

Comment thread driver-core/src/main/com/mongodb/MongoException.java

stIncMale force-pushed the backpressure branch from f20e56b to 2d1b2e1 Compare May 8, 2026 18:16

stIncMale commented May 8, 2026

View reviewed changes

Comment thread driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTestModifications.java

stIncMale commented May 8, 2026

View reviewed changes

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

stIncMale force-pushed the backpressure branch from 2d1b2e1 to 11a7b73 Compare May 8, 2026 20:58

stIncMale commented May 9, 2026

View reviewed changes

Comment thread driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTestModifications.java

stIncMale commented May 9, 2026

View reviewed changes

Comment thread driver-sync/src/test/functional/com/mongodb/client/unified/UnifiedTestModifications.java

stIncMale commented Jun 3, 2026

View reviewed changes

Comment thread driver-sync/src/test/functional/com/mongodb/client/ServerDiscoveryAndMonitoringProseTests.java

This was referenced Jun 3, 2026

Refactor MixedBulkWriteOperation to simplify retry logic there #1989

Merged

Improve the label in withTransaction #1994

Merged

stIncMale force-pushed the backpressure branch from 8d8e4fe to c707ffe Compare June 4, 2026 18:14

stIncMale commented Jun 5, 2026

View reviewed changes

Comment thread driver-core/src/main/com/mongodb/MongoSocksProxyException.java

stIncMale mentioned this pull request Aug 17, 2026

Introduce necessary executors and implement sleepAsync stIncMale/mongo-java-driver#3

Closed

stIncMale force-pushed the backpressure branch from 8fa85b1 to 09305b2 Compare August 18, 2026 18:32

stIncMale mentioned this pull request Aug 18, 2026

Introduce necessary executors and implement sleepAsync #2040

Merged

vbabanin mentioned this pull request Sep 15, 2026

Replace error label string literals with constant #2055

Merged

stIncMale mentioned this pull request Sep 16, 2026

update client and server @since labels to 5.12 and 9 for server #2057

Merged

stIncMale and others added 25 commits September 17, 2026 11:05

Add maxAdaptiveRetries API (#1944)

6f70ce3

JAVA-6141

Implement prose backpressure tests (#1946)

f9022e8

The relevant spec changes: - https://github.com/mongodb/specifications/blob/8a8a7c56429c80b51ec62268dcafc5e5e3c477ef/source/client-backpressure/tests/README.md JAVA-5956, JAVA-6117, JAVA-6113, JAVA-6119, JAVA-6141

Add handshake prose Test 9: backpressure: true in handshake documents (…

2458cf9

…#1949)

JAVA-5950 Update Transactions Convenient API with exponential backoff…

ba29122

… on retries (#1899)

JAVA-5949 preserve connection pool on backpressure errors when establ…

d8d1225

…ishing connections (#1900)

JAVA-6174 Fix sdam eventType to assert serverDescriptionChangedEvent (#…

f05af7d

…1978)

JAVA-6194 Add MongoSocksProxyException for CMAP backpressure labeling (…

37f39aa

…#1968) JAVA-6035: Add backpressure flag to connection handshake (#1906)

Improve the label in the withTransaction method (#1994)

bd019de

Remove skips for enableOverloadRetargeting. (#1995)

8827cf8

JAVA-6167

Refactor MixedBulkWriteOperation to simplify retry logic there (#1989)

77d39fc

JAVA-6218

Introduce the RetryPolicy abstraction (#2004)

7bc2041

JAVA-6229

Fix tests after backpressure rebase

6b4c8a5

Implement the overload retry policy for commands that are read/write …

78d3180

…retryable (#2041) JAVA-6248

Replace error label string literals with constants(#2055)

52aad5e

Add code design rules for AI (#2028)

ad16f81

Co-authored-by: Viacheslav Babanin <frest0512@gmail.com> --------- Co-authored-by: Viacheslav Babanin <frest0512@gmail.com>

Update client and server @SInCE labels to 5.12 and 9 for server (#2057)

117b37c

JAVA-6243

Add baseBackoffMS support (#2052)

0436355

- Send backpressure: "2" in handshake. - Add MongoDB 9.0 to Evergreen version matrix. - Add baseBackoffMS override prose test (Test 5). - Support server-supplied baseBackoffMS override for overload backoff. JAVA-6238 JAVA-6255

stIncMale force-pushed the backpressure branch from fdba837 to 43d09eb Compare September 17, 2026 17:15

stIncMale and others added 2 commits September 17, 2026 11:37

Update the specifications submodule from d4d0cdf to 92b3c0b to matc…

7c5812d

…h the `main` branch (#2060) Rebasing `backpressure` on top of `main` did not achieve that.

stIncMale merged commit f0bc4cb into main Sep 17, 2026
202 of 282 checks passed

stIncMale deleted the backpressure branch September 17, 2026 20:01

Navigation Menu

Client Backpressure - #1918

Client Backpressure#1918
stIncMale merged 29 commits into
mainfrom
backpressure

stIncMale commented Mar 21, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

evergreen-ci-prod Bot commented May 8, 2026

Uh oh!

Uh oh!

Uh oh!

stIncMale commented Jun 3, 2026 •

edited

Loading

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

Conversation

stIncMale commented Mar 21, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

How to include main changes into backpressure

How to deal with TODOs

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

evergreen-ci-prod Bot commented May 8, 2026

Uh oh!

Uh oh!

Uh oh!

stIncMale commented Jun 3, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

stIncMale commented Mar 21, 2026 •

edited

Loading

How to include `main` changes into `backpressure`

stIncMale commented Jun 3, 2026 •

edited

Loading