JAVA-5949 preserve connection pool on backpressure errors when establishing connections by nhachicha · Pull Request #1900 · mongodb/mongo-java-driver

nhachicha · 2026-02-25T13:45:19Z

Original PR #1854 accidentally closed, and had no outstanding review comments.

~~This current PR depends on [JAVA-6033] ServerHeartbeatSucceededEvent is not fired for initial POLL monitoring #1856:~~
Update: This PR no longer depends on [JAVA-6033] ServerHeartbeatSucceededEvent is not fired for initial POLL monitoring #1856. Spec PR DRIVERS-3367: Fix racy backpressure-network-* tests specifications#1880 rewrote the backpressure-network-*-fail.yml tests to wait on serverDescriptionChangedEvent instead of serverHeartbeatSucceededEvent.

~~we should merge the latter into main, then merge this PR in backpressure, and leave the necessary TODO comments in #1918 related to the dependency on #1856.~~

then, when there are no outstanding PRs for the backpressure branch, rebase backpressure on top of main to include the changes from the main (see Merge main into backpressure #1917 (comment) for more context on this process).
then address the aforementioned TODO comments.

Specification changes:

DRIVERS-3218 Avoid clearing the connection pool when the server connection rate limiter triggers (#1855)
DRIVERS-3218: update SDAM error handling tests to ignore handshake failures (#1860)
DRIVERS-3218 Clarify interaction between TLS errors and backpressure (#1879) - the change has not yet been addressed in this PR, because it was introduced after creation of the PR.
DRIVERS-3218 clarify label handling (#1892) - the change has not yet been addressed in this PR, because it was introduced after creation of the PR.
DRIVERS-3367: Fix racy backpressure-network-* tests (#1880) - just a unified spec tests (JSON) update; the change has not yet been addressed in this PR, because it was introduced after creation of the PR.
DRIVERS-1785 Add test that PoolClearedEvent is emitted before ConnectionCheckedInEvent/ConnectionCheckOutFailedEvent

Note that there was a change in the description of one of the tests that belongs to this PR, but I closed the corresponding JAVA-6095 (see this comment): DRIVERS-3394: adjust spec test description (#1894).

JAVA-5949, JAVA-6056, JAVA-5664

AI usage and effectiveness:

Model Opus 4.6 then 4.7
Used as an implementer + paired reviewer
Spec audits
Most architectural decisions were grounded in "what do Node and .NET do?" in addition to the reasoning from the spec text.

codeowners-service-app · 2026-02-25T16:59:25Z

Assigned stIncMale for team dbx-java because vbabanin is out of office.

stIncMale · 2026-03-04T22:39:28Z

Added the following to the description of the PR (a new piece of work to be done within the PR): DRIVERS-3394: adjust spec test description (#1894)(JAVA-6095).

vbabanin · 2026-03-10T04:24:21Z

+            // clear the pool as they're not related to overload.
+            // TLS configuration errors (certificate validation, protocol mismatches) should also clear the pool
+            // as they indicate configuration issues, not server overload.
+            if (beforeHandshake && !sdamIssue.relatedToAuth() && !sdamIssue.relatedToTlsConfigurationError()) {


Currently we attach SystemOverloadedError and RetryableError labels in the SDAM error-handling path (effectively only for DefaultServer). In load-balanced mode, SDAM isn’t involved: the LB code path invalidates the pool directly (e.g., connectionPool.invalidate(serviceId, generation)), so the labeling logic is bypassed.

This means users running the driver in LB mode (behind an NLB) can still hit network errors, TLS handshake failures, timeouts during connection establishment or hello, but won’t get the labels.

However, these labels are a CMAP requirement, not SDAM. The CMAP spec states: “The pool MUST add the error labels SystemOverloadedError and RetryableError to network errors or network timeouts it encounters during the connection establishment or the hello message.”

Since this is defined as a pool behavior (topology-agnostic), it seems we should implement the labeling in the connection pool layer so it applies consistently in both default and load-balanced modes.

Copilot

Pull request overview

This PR updates SDAM/backpressure handling so that connection-establishment failures caused by server-side backpressure do not clear the connection pool, and adds/updates tests and matchers to align with the SDAM spec test expectations.

Changes:

Adjust SDAM exception handling to avoid invalidating the pool on certain pre-handshake network failures, and add TLS-configuration-error classification.
Add new error label constants (SystemOverloadedError, RetryableError) and apply them for backpressure-related failures.
Extend unified event matching for additional server types and add a prose test for connection pool backpressure behavior.

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

Show a summary per file

File	Description
driver-sync/src/test/functional/com/mongodb/client/unified/EventMatcher.java	Extends server type matching for SDAM serverDescriptionChangedEvent expectations.
driver-sync/src/test/functional/com/mongodb/client/ServerDiscoveryAndMonitoringProseTests.java	Adds a prose test intended to validate connection pool backpressure behavior via server rate limiter parameters.
driver-core/src/test/unit/com/mongodb/internal/connection/DefaultServerSpecification.groovy	Updates unit tests to expect pool preservation on network errors during connection establishment (sync/async).
driver-core/src/main/com/mongodb/internal/connection/SdamServerDescriptionManager.java	Adds TLS configuration error detection helper on SDAM issues.
driver-core/src/main/com/mongodb/internal/connection/DefaultSdamServerDescriptionManager.java	Changes SDAM exception handling to preserve pool/server description for certain pre-handshake failures and apply labels.
driver-core/src/main/com/mongodb/MongoException.java	Introduces new public error label constants used by the backpressure handling path.

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

stIncMale · 2026-03-28T00:30:49Z

[this comment is left on a file, but has nothing to do with the file; this is done so that we could reply to the comment; commenting on a PR does not allow replies - horrendous GitHub functionality]

The current PR seemingly depends on #1856 (see the description of the current PR). We need to decide what to do with that.

P.S. I originally left my thoughts in the description of this PR, but I don't know if that's what we are going to do.

We no longer depend on this PR see #1900 (comment)

stIncMale · 2026-03-28T00:44:38Z

[this comment is left on a file, but has nothing to do with the file; this is done so that we could reply to the comment; commenting on a PR does not allow replies - horrendous GitHub functionality]

@nhachicha

Could you please confirm that all the specification changes listed in the "Specification changes" part of the description of the current PR have been addressed in the PR?

If they have been addressed, let's update the description correspondingly.

Description updated. All specs are implemented

stIncMale · 2026-03-28T00:59:02Z

[this comment is left on a file, but has nothing to do with the file; this is done so that we could reply to the comment; commenting on a PR does not allow replies - horrendous GitHub functionality]

JAVA-5949 has an old comment, which instructs to re-enable some tests that were previously disabled when we updated the testing/resources/specifications submodule in main. Those tests were not enabled. Let's enable them and make sure they pass.

This PR no longer depends on #1856. Spec PR mongodb/specifications#1880 rewrote the backpressure-network-*-fail.yml tests to wait on serverDescriptionChangedEvent instead of serverHeartbeatSucceededEvent.

…establishing connections

- Fixing static check analysis

…handshake network timeout

- Fixed https://jira.mongodb.org/browse/JAVA-5664 (https://jira.mongodb.org/browse/DRIVERS-1785)

…r PR

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

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

- Add the complementary test to cover the suppress-on-label branch.

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

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

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

Copilot

Pull request overview

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

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 12 out of 12 changed files in this pull request and generated no new comments.

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

…re/preserve_connection_pool

nhachicha self-assigned this Feb 25, 2026

nhachicha requested a review from vbabanin February 25, 2026 16:56

nhachicha marked this pull request as ready for review February 25, 2026 16:56

nhachicha requested a review from a team as a code owner February 25, 2026 16:56

codeowners-service-app Bot requested a review from stIncMale February 25, 2026 16:59

stIncMale mentioned this pull request Feb 25, 2026

[JAVA-6033] ServerHeartbeatSucceededEvent is not fired for initial POLL monitoring #1856

Open

katcharov removed the request for review from stIncMale March 3, 2026 16:34

vbabanin requested changes Mar 10, 2026

View reviewed changes

katcharov requested a review from Copilot March 20, 2026 22:58

Copilot started reviewing on behalf of katcharov March 20, 2026 22:59 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

stIncMale mentioned this pull request Mar 23, 2026

JAVA-5949 preserve connection pool on backpressure errors when establishing connections #1854

Closed

stIncMale requested changes Mar 28, 2026

View reviewed changes

nhachicha and others added 10 commits April 20, 2026 17:47

Fixes JAVA-5949 prevent connection churn on backpressure errors when …

21abfe2

…establishing connections

Remove handshake and update submodule including new tests

339297b

Update spec test; fix test runner

2e44072

Add prose test

4cff1b2

Increasing the timeout termination

0a93dd7

- Revert spec timeout

b1f4ba0

- Fixing static check analysis

Update exception checks

1b1558d

Increase timeout for operations to complete

fcdfa23

Simplifying conditions check

d423093

Apply backpressure labels in CMAP layer; align SDAM with spec

bce97d4

nhachicha force-pushed the nh/backpressure/preserve_connection_pool branch from 0be0250 to bce97d4 Compare April 22, 2026 17:16

nhachicha added 4 commits April 23, 2026 11:06

Align Prose Test with Spec

41b2773

Test runner needs to add the SystemOverloadedError label for the pre-…

508d741

…handshake network timeout

- Re-enable JAVA-5949-skipped SDAM/backpressure tests

c5e68fc

- Fixed https://jira.mongodb.org/browse/JAVA-5664 (https://jira.mongodb.org/browse/DRIVERS-1785)

Deferred fixes to https://jira.mongodb.org/browse/JAVA-5664 to anothe…

71c91f0

…r PR

vbabanin reviewed May 1, 2026

View reviewed changes

nhachicha and others added 3 commits May 1, 2026 07:46

Potential fix for pull request finding

a5720b8

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

Update driver-core/src/main/com/mongodb/internal/connection/Backpress…

75a5ea4

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

- Replace the dedicated DNS test with a generic one.

7f74b9b

- Add the complementary test to cover the suppress-on-label branch.

nhachicha requested a review from vbabanin May 1, 2026 08:51

vbabanin reviewed May 5, 2026

View reviewed changes

Comment thread driver-core/src/test/unit/com/mongodb/internal/connection/DefaultServerSpecification.groovy Outdated

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

nhachicha and others added 2 commits May 5, 2026 14:48

Update driver-core/src/test/unit/com/mongodb/internal/connection/Defa…

4938412

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

Simplifying TLS error detection

0050ab1

nhachicha requested a review from vbabanin May 5, 2026 15:24

Add isBouncyCastleTlsError to cover BC's TlsFatalAlert*

f50b3a6

nhachicha requested a review from Copilot May 5, 2026 23:54

Copilot started reviewing on behalf of nhachicha May 5, 2026 23:54 View session

Copilot AI reviewed May 5, 2026

View reviewed changes

vbabanin reviewed May 7, 2026

View reviewed changes

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

Make BC TLS detection testable; refactor to FQCN walk

ca44050

nhachicha requested review from Copilot and vbabanin May 7, 2026 13:30

Copilot started reviewing on behalf of nhachicha May 7, 2026 13:31 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

Potential fix for pull request finding

581162a

Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com>

nhachicha requested a review from Copilot May 7, 2026 14:16

Copilot started reviewing on behalf of nhachicha May 7, 2026 14:17 View session

Copilot AI reviewed May 7, 2026

View reviewed changes

vbabanin reviewed May 7, 2026

View reviewed changes

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

vbabanin previously approved these changes May 7, 2026

View reviewed changes

Update driver-core/src/main/com/mongodb/internal/connection/Backpress…

8dac2ec

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

nhachicha dismissed vbabanin’s stale review via 8dac2ec May 8, 2026 06:12

Merge remote-tracking branch 'origin/backpressure' into nh/backpressu…

34f5462

…re/preserve_connection_pool

nhachicha merged commit f20e56b into mongodb:backpressure May 8, 2026
43 of 53 checks passed

nhachicha deleted the nh/backpressure/preserve_connection_pool branch May 8, 2026 11:40

Conversation

nhachicha commented Feb 25, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

AI usage and effectiveness:

Uh oh!

codeowners-service-app Bot commented Feb 25, 2026

Uh oh!

stIncMale commented Mar 4, 2026

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

vbabanin Mar 10, 2026

Choose a reason for hiding this comment

Uh oh!

nhachicha Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

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

Uh oh!

Choose a reason for hiding this comment

Uh oh!

nhachicha Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

stIncMale Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

nhachicha Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

stIncMale Mar 28, 2026

Choose a reason for hiding this comment

Uh oh!

nhachicha Apr 23, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

nhachicha commented Feb 25, 2026 •

edited

Loading

stIncMale Mar 28, 2026 •

edited

Loading