PYTHON-5885 Client Backpressure with baseBackoffMS by NoahStapp · Pull Request #2877 · mongodb/mongo-python-driver

NoahStapp · 2026-06-16T18:04:14Z

Changes in this PR

Adds baseBackoffMS support for backoff calculation on retryable overload errors.

Test Plan

Adds a new prose test test_05_overload_errors_with_retryafterms_override_backoff to verify the baseBackoffMS behavior. Note that this new test requires a server with baseBackoffMS support.

Checklist

Checklist for Author

Did you update the changelog (if necessary)?
Is there test coverage?
~~[ ] Is any followup work tracked in a JIRA ticket? If so, add link(s).~~

Checklist for Reviewer

Does the title of the PR reference a JIRA Ticket?
Do you fully understand the implementation? (Would you be comfortable explaining how this code works to someone else?)
Is all relevant documentation (README or docstring) updated?

codecov-commenter · 2026-06-16T18:50:18Z

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

NoahStapp · 2026-07-01T15:51:01Z

Note: SERVER-130142 will rename retryAfterMS to baseBackoffMS. That change will require the spec to update as well as this PR.

Copilot

Pull request overview

Adds support for using retryAfterMS from retryable overload errors to influence the client’s adaptive retry backoff, plus updates handshake backpressure metadata and related tests/docs.

Changes:

Parse and propagate retryAfterMS from server error documents into the overload backoff calculation.
Update hello/handshake backpressure field value (and metadata tests) to "2".
Add a new prose-style timing test validating that retryAfterMS reduces overload backoff.

Reviewed changes

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

Show a summary per file

File	Description
`pymongo/errors.py`	Parses `retryAfterMS` from error details into `PyMongoError`.
`pymongo/synchronous/mongo_client.py`	Uses `retryAfterMS` override when computing overload retry backoff (sync).
`pymongo/asynchronous/mongo_client.py`	Uses `retryAfterMS` override when computing overload retry backoff (async).
`pymongo/synchronous/helpers.py`	Adjusts backoff helper to accept an override base backoff (sync).
`pymongo/asynchronous/helpers.py`	Adjusts backoff helper to accept an override base backoff (async).
`pymongo/synchronous/pool.py`	Updates handshake hello `backpressure` value (sync).
`pymongo/asynchronous/pool.py`	Updates handshake hello `backpressure` value (async).
`test/test_client_backpressure.py`	Adds a new test for `retryAfterMS`-driven backoff behavior (sync).
`test/asynchronous/test_client_backpressure.py`	Adds a new test for `retryAfterMS`-driven backoff behavior (async).
`test/test_client_metadata.py`	Updates handshake backpressure assertion (sync).
`test/asynchronous/test_client_metadata.py`	Updates handshake backpressure assertion (async).
`doc/changelog.rst`	Updates changelog entry for 4.18.0.

Copilot

Pull request overview

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

aclark4life · 2026-07-20T14:12:18Z

retryAfterMS is now baseBackoffMScorrect? Is so can you update the PR desc ?

aclark4life · 2026-07-20T14:22:20Z

                        if overloaded:
                            self._max_retries = self._client.options.max_adaptive_retries
-                        always_retryable = exc.has_error_label("RetryableError") and overloaded
+                            self._base_backoff_ms = exc_to_check._base_backoff_ms


🤖 suggests:

self._base_backoff_ms = getattr(exc_to_check, "_base_backoff_ms", None)

here and here because _base_backoff_ms is a property defined only on OperationFailure but exc_to_check can be a ConnectionFailure and the if overloaded: guard only checks the error label not the type.

The server can only attach SystemOverloadedError to OperationFailure errors, so this can't ever occur currently. We could add the getattr as a safeguard in case that changes in the future, but it also makes that existing contract with the server less clear.

Actually, never mind. Having to add a type override here instead of getattr is silly.

Copilot

Pull request overview

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

Copilot

Pull request overview

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

Comments suppressed due to low confidence (3)

doc/changelog.rst:5

The changelog header uses a placeholder release date "2026/XX/XX". This is not a valid date and makes the changelog look released/dated when it isn’t; consider keeping the undated header until the release date is known.

Changes in Version 4.18.0 (2026/XX/XX)
--------------------------------------

doc/changelog.rst:13

This changelog bullet is a single very long line; wrap it to match the surrounding formatting and avoid exceeding typical reStructuredText line-length conventions.

- Improved performance for MongoDB 9.0's Intelligent Workload Management (IWM) by only retrying overload errors when doing so is expected to not worsen server conditions.

test/asynchronous/test_client_backpressure.py:306

The PR description says it adds prose test test_05_overload_errors_with_retryafterms_override_backoff, but the added test here is test_05_overload_errors_with_basebackoffms_override_backoff. Please update the PR description (or rename the test) so they match.

    @async_client_context.require_version_min(9, 0, 0, -1)
    @async_client_context.require_failCommand_appName
    async def test_05_overload_errors_with_basebackoffms_override_backoff(self, random_func):
        # Drivers should test that overload errors with `baseBackoffMS` override the default backoff duration.

aclark4life · 2026-07-22T14:25:19Z

+    def backoff(self, attempt: int, base_backoff: Optional[float] = None) -> float:
+        """Return the actual backoff duration for the given attempt and base backoff."""
+        return _backoff(
+            max(0, attempt),


What is the actual backoff duration and how does changing from attempt -1 to attempt help to implement ?

attempt - 1 -> attempt is to comply with the latest spec, which conforms to the server's exponential backoff formula for consistency. The actual backoff duration for two different backoff calls with the same attempt argument can differ due to base_backoff.

aclark4life · 2026-07-22T14:29:45Z

        self._attempt_number = 0
        self._is_run_command = is_run_command
        self._is_aggregate_write = is_aggregate_write
+        self._base_backoff_ms: Optional[float] = None


Should this be int as it is in errors.py or vice versa ?

Good catch, errors.py should use a float for consistency.

aclark4life · 2026-07-22T14:37:03Z

+        # and the baseBackoffMS=50 backoffs are 0.1 + 0.2 = 0.3s.
+        self.assertGreaterEqual(exponential_backoff_time, 0.6)
+        self.assertGreaterEqual(with_base_backoff_ms_time, 0.3)
+        self.assertLess(with_base_backoff_ms_time, 0.6)


Do we care if unrelated perf issues push this past 0.6?

Perf issues are an annoying thorn in our side for this type of test: it's more resilient to assert with_base_backoff_ms_time < exponential_backoff_time, but that doesn't ensure that we backed off for the correct amount of time required by base_backoff_ms. I could see preferring the less accurate but also less flakey assertion over the current one, thoughts?

Yeah, we have a way to deal with flaky tests (I think?) so maybe this just goes into that category, unless we do something crazy like < exponential_backoff_time if exponential_backoff_time == base_backoff_ms 😂 IOW some conditional to compare them before using exponential_backoff_time instead of base_backoff_ms but that's starting to sound worse than just accepting flakiness.

aclark4life · 2026-07-22T14:43:58Z

+                    delay = self._retry_policy.backoff(
+                        self._attempt_number,
+                        self._base_backoff_ms / 1000 if self._base_backoff_ms else None,
+                    )


Ye Olde None confusion: if _base_backoff_ms is truthy, divide by 1000 else None but if the server sends 0 (which can presumably never happen?) then _base_backoff_ms is None instead of zero. If you go down this rabbit hole, maybe we do this instead:

self._base_backoff_ms / 1000 if self._base_backoff_ms is not None else None

The server should never send baseBackoffMS = 0, as doing so would result in no backoff. I don't think we need to complicate this edge case here as a result.

aclark4life

LGTM pending optional nit fix suggestions (if accepted)!

aclark4life

LGTM

NoahStapp added 7 commits May 29, 2026 14:12

retryAfterMS PoC

1464c48

Avoid dividing None

733b906

Merge branch 'master' into backpressure-v2

f82d99d

Cleanup

18c3c2e

Merge branch 'master' into backpressure-v2

6486561

Merge branch 'master' into backpressure-v2

bc648de

Add prose test + update changelog

576e870

NoahStapp mentioned this pull request Jun 16, 2026

DRIVERS-3535 - Client Backpressure with baseBackoffMS mongodb/specifications#1953

Merged

4 tasks

NoahStapp added 5 commits June 17, 2026 13:06

Merge branch 'master' into backpressure-v2

ac17fae

Linting fixes

aa7e1d4

Set handshake backpressure version to 2

49cb18d

Match newest spec

68268f9

Merge branch 'master' into backpressure-v2

acd7d89

NoahStapp marked this pull request as ready for review July 1, 2026 15:50

NoahStapp requested a review from a team as a code owner July 1, 2026 15:50

NoahStapp requested review from aclark4life and Copilot July 1, 2026 15:50

Copilot started reviewing on behalf of NoahStapp July 1, 2026 15:50 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

NoahStapp added 3 commits July 1, 2026 12:10

Merge branch 'master' into backpressure-v2

8c06ebc

CP review

2cf06dc

Cleanup

31edb0e

NoahStapp requested a review from Copilot July 1, 2026 17:48

Copilot started reviewing on behalf of NoahStapp July 1, 2026 17:48 View session

Copilot AI reviewed Jul 1, 2026

View reviewed changes

Comment thread doc/changelog.rst Outdated

Comment thread test/test_client_backpressure.py Outdated

Comment thread test/asynchronous/test_client_backpressure.py Outdated

NoahStapp added 2 commits July 1, 2026 14:55

Merge branch 'master' into backpressure-v2

f9316a7

Rename retryAfterMS to baseBackoffMS

4486c68

NoahStapp changed the title ~~PYTHON-5885 - Client Backpressure with retryAfterMS~~ PYTHON-5885 - Client Backpressure with baseBackoffMS Jul 8, 2026

Merge branch 'main' into backpressure-v2

f512029

aclark4life requested changes Jul 20, 2026

View reviewed changes

AC review

a6e3b3c

NoahStapp requested review from Jibola, aclark4life and Copilot July 20, 2026 18:08

Copilot started reviewing on behalf of NoahStapp July 20, 2026 18:08 View session

Copilot AI reviewed Jul 20, 2026

View reviewed changes

Comment thread test/asynchronous/test_client_backpressure.py Outdated

Comment thread test/asynchronous/test_client_backpressure.py

Comment thread test/test_client_backpressure.py Outdated

Comment thread test/test_client_backpressure.py

Comment thread doc/changelog.rst

NoahStapp added 3 commits July 20, 2026 14:14

Specify that baseBackoffMS is only for 9.0+

a553b0b

Backoff uses 2^i not 2^(i-1)

f3ef3d4

Cleanup

5a675b2

NoahStapp requested a review from Copilot July 20, 2026 19:33

Copilot started reviewing on behalf of NoahStapp July 20, 2026 19:34 View session

Copilot AI reviewed Jul 20, 2026

View reviewed changes

Merge branch 'main' into backpressure-v2

bf4c0d5

aclark4life reviewed Jul 22, 2026

View reviewed changes

AC review

b7c1475

NoahStapp requested a review from aclark4life July 22, 2026 14:36

aclark4life reviewed Jul 22, 2026

View reviewed changes

aclark4life previously approved these changes Jul 22, 2026

View reviewed changes

Implement DRIVERS-3578

3a22ee2

NoahStapp dismissed aclark4life’s stale review via 3a22ee2 July 22, 2026 19:54

NoahStapp mentioned this pull request Jul 22, 2026

DRIVERS-3578 Use correct sum of backoffs for convenient transactions … mongodb/specifications#1968

Open

4 tasks

NoahStapp requested a review from aclark4life July 22, 2026 19:55

aclark4life approved these changes Jul 23, 2026

View reviewed changes

Jibola approved these changes Jul 23, 2026

View reviewed changes

NoahStapp merged commit 7d1af1c into mongodb:main Jul 24, 2026
76 of 89 checks passed

Uh oh!

Conversation

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

Uh oh!

Changes in this PR

Test Plan

Checklist

Checklist for Author

Checklist for Reviewer

Uh oh!

codecov-commenter commented Jun 16, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Codecov Report

Uh oh!

NoahStapp commented Jul 1, 2026

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!

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!

aclark4life commented Jul 20, 2026

Uh oh!

Choose a reason for hiding this comment

Uh oh!

NoahStapp Jul 20, 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!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aclark4life Jul 22, 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!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

aclark4life left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

NoahStapp commented Jun 16, 2026 •

edited

Loading

codecov-commenter commented Jun 16, 2026 •

edited

Loading

NoahStapp Jul 20, 2026 •

edited

Loading

aclark4life Jul 22, 2026 •

edited

Loading

aclark4life left a comment •

edited

Loading