Merge branch 'master' into dependabot/github_actions/actions-497a60f9a9

Author: Jibola

.github/copilot-instructions.md

@@ -1,3 +1,44 @@
-Please see [AGENTS.md](../AGENTS.md).
+When reviewing code, focus on:
 
-Follow the repository instructions defined in `AGENTS.md` when working in this codebase.
+## Security Critical Issues
+- Check for hardcoded secrets, API keys, or credentials.
+- Check for instances of potential method call injection, dynamic code execution, symbol injection or other code injection vulnerabilities.
+
+## Performance Red Flags
+- Spot inefficient loops and algorithmic issues.
+- Check for memory leaks and resource cleanup.
+
+## Code Quality Essentials
+- Methods should be focused and appropriately sized. If a method is doing too much, suggest refactorings to split it up.
+- Use clear, descriptive naming conventions.
+- Avoid encapsulation violations and ensure proper separation of concerns.
+- All public classes, modules, and methods should have clear documentation in Sphinx format.
+
+## PyMongo-specific Concerns
+- Do not review files within `pymongo/synchronous` or files in `test/` that also have a file of the same name in `test/asynchronous` unless the reviewed changes include a `_IS_SYNC` statement. PyMongo generates these files from `pymongo/asynchronous` and `test/asynchronous` using `tools/synchro.py`.
+- All asynchronous functions must not call any blocking I/O.
+
+## Review Style
+- Be specific and actionable in feedback.
+- Explain the "why" behind recommendations.
+- Acknowledge good patterns when you see them.
+- Ask clarifying questions when code intent is unclear.
+
+Always prioritize security vulnerabilities and performance issues that could impact users.
+
+Always suggest changes to improve readability and testability. For example, this suggestion seeks to make the code more readable, reusable, and testable:
+
+```python
+# Instead of:
+if user.email and "@" in user.email and len(user.email) > 5:
+    submit_button.enabled = True
+else:
+    submit_button.enabled = False
+
+# Consider:
+def valid_email(email):
+    return email and "@" in email and len(email) > 5
+
+
+submit_button.enabled = valid_email(user.email)
+```

AGENTS.md

@@ -16,7 +16,7 @@ PyMongo 4.17 brings a number of changes including:
   See <PLACEHOLDER> for examples and more information.
 - Added support for MongoDB's Intelligent Workload Management (IWM) and ingress connection rate limiting features.
   The driver now gracefully handles write-blocking scenarios and optimizes connection establishment during high-load conditions to maintain application availability.
-  See <DOCSP-55426> and <DOCSP-57078> for more information.
+  See the `IWM <https://www.mongodb.com/docs/atlas/intelligent-workload-management>`_ or `Overload Errors <https://www.mongodb.com/docs/atlas/overload-errors/?interface=driver&language=python>`_ docs for more information.
 
 Changes in Version 4.16.0 (2026/01/07)
 --------------------------------------

doc/changelog.rst

@@ -2779,7 +2779,7 @@ def __init__(
         self._last_error: Optional[Exception] = None
         self._retrying = False
         self._always_retryable = False
-        self._multiple_retries = _csot.get_timeout() is not None
+        self._max_retries = float("inf") if _csot.get_timeout() is not None else 1
         self._client = mongo_client
         self._retry_policy = mongo_client._retry_policy
         self._func = func
@@ -2852,6 +2852,8 @@ async def run(self) -> T:
                         # ConnectionFailures do not supply a code property
                         exc_code = getattr(exc, "code", None)
                         overloaded = exc.has_error_label("SystemOverloadedError")
+                        if overloaded:
+                            self._max_retries = self._client.options.max_adaptive_retries
                         always_retryable = exc.has_error_label("RetryableError") and overloaded
                         if not self._client.options.retry_reads or (
                             not always_retryable
@@ -2890,6 +2892,8 @@ async def run(self) -> T:
                         exc_to_check = exc.error
                     retryable_write_label = exc_to_check.has_error_label("RetryableWriteError")
                     overloaded = exc_to_check.has_error_label("SystemOverloadedError")
+                    if overloaded:
+                        self._max_retries = self._client.options.max_adaptive_retries
                     always_retryable = exc_to_check.has_error_label("RetryableError") and overloaded
 
                     # Always retry abortTransaction and commitTransaction up to once
@@ -2943,7 +2947,9 @@ async def run(self) -> T:
 
     def _is_not_eligible_for_retry(self) -> bool:
         """Checks if the exchange is not eligible for retry"""
-        return not self._retryable or (self._is_retrying() and not self._multiple_retries)
+        return not self._retryable or (
+            self._is_retrying() and self._attempt_number >= self._max_retries
+        )
 
     def _is_retrying(self) -> bool:
         """Checks if the exchange is currently undergoing a retry"""

pymongo/asynchronous/mongo_client.py

@@ -2769,7 +2769,7 @@ def __init__(
         self._last_error: Optional[Exception] = None
         self._retrying = False
         self._always_retryable = False
-        self._multiple_retries = _csot.get_timeout() is not None
+        self._max_retries = float("inf") if _csot.get_timeout() is not None else 1
         self._client = mongo_client
         self._retry_policy = mongo_client._retry_policy
         self._func = func
@@ -2842,6 +2842,8 @@ def run(self) -> T:
                         # ConnectionFailures do not supply a code property
                         exc_code = getattr(exc, "code", None)
                         overloaded = exc.has_error_label("SystemOverloadedError")
+                        if overloaded:
+                            self._max_retries = self._client.options.max_adaptive_retries
                         always_retryable = exc.has_error_label("RetryableError") and overloaded
                         if not self._client.options.retry_reads or (
                             not always_retryable
@@ -2880,6 +2882,8 @@ def run(self) -> T:
                         exc_to_check = exc.error
                     retryable_write_label = exc_to_check.has_error_label("RetryableWriteError")
                     overloaded = exc_to_check.has_error_label("SystemOverloadedError")
+                    if overloaded:
+                        self._max_retries = self._client.options.max_adaptive_retries
                     always_retryable = exc_to_check.has_error_label("RetryableError") and overloaded
 
                     # Always retry abortTransaction and commitTransaction up to once
@@ -2933,7 +2937,9 @@ def run(self) -> T:
 
     def _is_not_eligible_for_retry(self) -> bool:
         """Checks if the exchange is not eligible for retry"""
-        return not self._retryable or (self._is_retrying() and not self._multiple_retries)
+        return not self._retryable or (
+            self._is_retrying() and self._attempt_number >= self._max_retries
+        )
 
     def _is_retrying(self) -> bool:
         """Checks if the exchange is currently undergoing a retry"""

pymongo/synchronous/mongo_client.py

@@ -20,8 +20,11 @@
 import sys
 import threading
 from test.asynchronous.utils import async_set_fail_point
+from unittest import mock
 
-from pymongo.errors import OperationFailure
+from pymongo import MongoClient
+from pymongo.common import MAX_ADAPTIVE_RETRIES
+from pymongo.errors import OperationFailure, PyMongoError
 
 sys.path[0:0] = [""]
 
@@ -38,6 +41,7 @@
 )
 
 from pymongo.monitoring import (
+    CommandFailedEvent,
     ConnectionCheckedOutEvent,
     ConnectionCheckOutFailedEvent,
     ConnectionCheckOutFailedReason,
@@ -145,6 +149,19 @@ async def test_pool_paused_error_is_retryable(self):
 
 
 class TestRetryableReads(AsyncIntegrationTest):
+    async def asyncSetUp(self) -> None:
+        await super().asyncSetUp()
+        self.setup_client = MongoClient(**async_client_context.client_options)
+        self.addCleanup(self.setup_client.close)
+
+    # TODO: After PYTHON-4595 we can use async event handlers and remove this workaround.
+    def configure_fail_point_sync(self, command_args, off=False) -> None:
+        cmd = {"configureFailPoint": "failCommand", **command_args}
+        if off:
+            cmd["mode"] = "off"
+            cmd.pop("data", None)
+        self.setup_client.admin.command(cmd)
+
     @async_client_context.require_multiple_mongoses
     @async_client_context.require_failCommand_fail_point
     async def test_retryable_reads_are_retried_on_a_different_mongos_when_one_is_available(self):
@@ -383,6 +400,117 @@ async def test_03_03_retryable_reads_caused_by_overload_errors_are_retried_on_th
         # 6. Assert that both events occurred on the same server.
         assert listener.failed_events[0].connection_id == listener.succeeded_events[0].connection_id
 
+    @async_client_context.require_failCommand_fail_point
+    @async_client_context.require_version_min(4, 4, 0)  # type:ignore[untyped-decorator]
+    async def test_overload_then_nonoverload_retries_increased_reads(self) -> None:
+        # Create a client.
+        listener = OvertCommandListener()
+
+        # Configure the client to listen to CommandFailedEvents. In the attached listener, configure a fail point with error
+        # code `91` (ShutdownInProgress) and `RetryableError` and `SystemOverloadedError` labels.
+        overload_fail_point = {
+            "configureFailPoint": "failCommand",
+            "mode": {"times": 1},
+            "data": {
+                "failCommands": ["find"],
+                "errorLabels": ["RetryableError", "SystemOverloadedError"],
+                "errorCode": 91,
+            },
+        }
+
+        # Configure a fail point with error code `91` (ShutdownInProgress) with only the `RetryableError` error label.
+        non_overload_fail_point = {
+            "configureFailPoint": "failCommand",
+            "mode": "alwaysOn",
+            "data": {
+                "failCommands": ["find"],
+                "errorCode": 91,
+                "errorLabels": ["RetryableError"],
+            },
+        }
+
+        def failed(event: CommandFailedEvent) -> None:
+            # Configure the fail point command only if the failed event is for the 91 error configured in step 2.
+            if listener.failed_events:
+                return
+            assert event.failure["code"] == 91
+            self.configure_fail_point_sync(non_overload_fail_point)
+            self.addCleanup(self.configure_fail_point_sync, {}, off=True)
+            listener.failed_events.append(event)
+
+        listener.failed = failed
+
+        client = await self.async_rs_client(event_listeners=[listener])
+        await client.test.test.insert_one({})
+
+        self.configure_fail_point_sync(overload_fail_point)
+        self.addCleanup(self.configure_fail_point_sync, {}, off=True)
+
+        with self.assertRaises(PyMongoError):
+            await client.test.test.find_one()
+
+        started_finds = [e for e in listener.started_events if e.command_name == "find"]
+        self.assertEqual(len(started_finds), MAX_ADAPTIVE_RETRIES + 1)
+
+    @async_client_context.require_failCommand_fail_point
+    @async_client_context.require_version_min(4, 4, 0)  # type:ignore[untyped-decorator]
+    async def test_backoff_is_not_applied_for_non_overload_errors(self):
+        if _IS_SYNC:
+            mock_target = "pymongo.synchronous.helpers._RetryPolicy.backoff"
+        else:
+            mock_target = "pymongo.asynchronous.helpers._RetryPolicy.backoff"
+
+        # Create a client.
+        listener = OvertCommandListener()
+
+        # Configure the client to listen to CommandFailedEvents. In the attached listener, configure a fail point with error
+        # code `91` (ShutdownInProgress) and `RetryableError` and `SystemOverloadedError` labels.
+        overload_fail_point = {
+            "configureFailPoint": "failCommand",
+            "mode": {"times": 1},
+            "data": {
+                "failCommands": ["find"],
+                "errorLabels": ["RetryableError", "SystemOverloadedError"],
+                "errorCode": 91,
+            },
+        }
+
+        # Configure a fail point with error code `91` (ShutdownInProgress) with only the `RetryableError` error label.
+        non_overload_fail_point = {
+            "configureFailPoint": "failCommand",
+            "mode": "alwaysOn",
+            "data": {
+                "failCommands": ["find"],
+                "errorCode": 91,
+                "errorLabels": ["RetryableError"],
+            },
+        }
+
+        def failed(event: CommandFailedEvent) -> None:
+            # Configure the fail point command only if the failed event is for the 91 error configured in step 2.
+            if listener.failed_events:
+                return
+            assert event.failure["code"] == 91
+            self.configure_fail_point_sync(non_overload_fail_point)
+            self.addCleanup(self.configure_fail_point_sync, {}, off=True)
+            listener.failed_events.append(event)
+
+        listener.failed = failed
+
+        client = await self.async_rs_client(event_listeners=[listener])
+        await client.test.test.insert_one({})
+
+        self.configure_fail_point_sync(overload_fail_point)
+        self.addCleanup(self.configure_fail_point_sync, {}, off=True)
+
+        # Perform a findOne operation with coll. Expect the operation to fail.
+        with mock.patch(mock_target, return_value=0) as mock_backoff:
+            with self.assertRaises(PyMongoError):
+                await client.test.test.find_one()
+
+        # Assert that backoff was applied only once for the initial overload error and not for the subsequent non-overload retryable errors.
+        self.assertEqual(mock_backoff.call_count, 1)
+
 
 if __name__ == "__main__":
     unittest.main()