DRIVERS-3446 - Add prose tests to verify correct retry behavior when a mix of overload and non-overload errors are encountered

DRIVERS-3427: Remove token bucket disclaimer from backpressure speci… (mongodb#1923)

DRIVERS-3436 - Refine `withTransaction` timeout error wrapping semantics and label propagation in spec and prose tests (mongodb#1920)

Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>
Co-authored-by: Valentin Kovalenko <valentin.male.kovalenko@gmail.com>

DRIVERS-3325 allow keyAltName in encryptedFields spec test (mongodb#1853)

Author: NoahStapp

source/client-backpressure/client-backpressure.md

@@ -159,9 +159,9 @@ The retry policy in this specification is separate from the other retry policies
 specifications. Drivers MUST ensure:
 
 - When a failed attempt is retried, backoff MUST be applied if and only if the error is an overload error.
-- If an overload error is encountered:
+- If an overload error is encountered at any point during an operation's retry loop:
     - Regardless of whether CSOT is enabled or not, the maximum number of retries for any retry policy becomes
-        `MAX_RETRIES`.
+        `MAX_RETRIES`. This includes retryable non-overload errors following the encountered overload error.
     - If CSOT is enabled and a command has been retried at least `MAX_RETRIES` times, it MUST NOT be retried further.
 
 #### Pseudocode
@@ -307,7 +307,7 @@ The Node and Python drivers will provide the reference implementations. See
 The client backpressure retry loop is primarily concerned with spreading out retries to avoid retry storms. The exact
 sleep duration is not critical to the intended behavior, so long as we sleep at least as long as we say we will.
 
-### Why override existing maximum number of retry attempt defaults for retryable reads and writes if an overload error is received?
+### Why override existing maximum number of retry attempt defaults for retryable reads and writes if an overload error is received at any point during an operation's retry loop?
 
 Load-shedded errors indicate that the request was rejected by the server to minimize load, not that the command failed
 for logical reasons. So, when determining the number of retries an operation should attempt:
@@ -325,8 +325,8 @@ specifications with load-shedding behavior:
     [retryable writes](../retryable-writes/retryable-writes.md) and
     [CSOT](../client-side-operations-timeout/client-side-operations-timeout.md) specifications when no overload errors are
     encountered.
-- Adjusting the maximum number of retry attempts to 5 if an overload error is returned from the server gives requests
-    more opportunities to succeed and helps reduce application errors.
+- Adjusting the maximum number of retry attempts to MAX_RETRIES if an overload error is returned from the server gives
+    requests more opportunities to succeed and helps reduce application errors.
 - An alternative approach would be to retry once if we don't receive an overload error, in which case we'd retry 5
     times. The approach chosen allows for additional retries in scenarios where a non-overload error fails on a retry
     with an overload error.

source/retryable-reads/tests/README.md

@@ -217,6 +217,57 @@ This test MUST be executed against a MongoDB 4.4+ replica set that has at least
 
 6. Assert that both events occurred on the same server.
 
+### 1: Test that drivers set the maximum number of retries for all retryable read errors when an overload error is encountered
+
+This test MUST be executed against a MongoDB 4.4+ server that supports `retryReads=true` and has enabled the
+`configureFailPoint` command with the `errorLabels` option.
+
+1. Create a client.
+
+2. Configure a fail point with error code `91` (ShutdownInProgress) with the `RetryableError` and
+    `SystemOverloadedError` error labels:
+
+    ```javascript
+    {
+        configureFailPoint: "failCommand",
+        mode: {times: 1},
+        data: {
+            failCommands: ["find"],
+            errorLabels: ["RetryableError", "SystemOverloadedError"],
+            errorCode: 91
+        }
+    }
+    ```
+
+3. Via the command monitoring CommandFailedEvent, configure a fail point with error code `91` (ShutdownInProgress) and
+    the `RetryableError` label:
+
+    ```javascript
+    {
+        configureFailPoint: "failCommand",
+        mode: "alwaysOn",
+        data: {
+            failCommands: ["find"],
+            errorLabels: ["RetryableError"],
+            errorCode: 91
+        }
+    }
+    ```
+
+    Configure the second fail point command only if the failed event is for the first error configured in step 2.
+
+4. Attempt a `findOne` operation on any record for any database and collection. Expect the `findOne` to fail with a
+    server error. Assert that `MAX_ADAPTIVE_RETRIES + 1` attempts were made.
+
+5. Disable the fail point:
+
+    ```javascript
+    {
+        configureFailPoint: "failCommand",
+        mode: "off"
+    }
+    ```
+
 ## Changelog
 
 - 2026-03-31: Add additional prose test for overload retargeting.

source/retryable-writes/tests/README.md

@@ -419,6 +419,54 @@ to cover the same sequence of events.
     }
     ```
 
+#### Case 4: Test that drivers set the maximum number of retries for all retryable write errors when an overload error is encountered
+
+1. Create a client with `retryWrites=true`.
+
+2. Configure a fail point with error code `91` (ShutdownInProgress) with the `RetryableError` and
+    `SystemOverloadedError` error labels:
+
+    ```javascript
+    {
+        configureFailPoint: "failCommand",
+        mode: {times: 1},
+        data: {
+            failCommands: ["insert"],
+            errorLabels: ["RetryableError", "SystemOverloadedError"],
+            errorCode: 91
+        }
+    }
+    ```
+
+3. Via the command monitoring CommandFailedEvent, configure a fail point with error code `91` (ShutdownInProgress) and
+    the `RetryableWriteError` and `RetryableError` labels:
+
+    ```javascript
+    {
+        configureFailPoint: "failCommand",
+        mode: "alwaysOn",
+        data: {
+            failCommands: ["insert"],
+            errorLabels: ["RetryableError", "RetryableWriteError"],
+            errorCode: 91
+        }
+    }
+    ```
+
+    Configure the second fail point command only if the failed event is for the first error configured in step 2.
+
+4. Attempt an `insertOne` operation on any record for any database and collection. Expect the `insertOne` to fail with a
+    server error. Assert that `MAX_ADAPTIVE_RETRIES + 1` attempts were made.
+
+5. Disable the fail point:
+
+    ```javascript
+    {
+        configureFailPoint: "failCommand",
+        mode: "off"
+    }
+    ```
+
 ## Changelog
 
 - 2026-04-02: Fix test for error propagation behavior when multiple errors are encountered.