From 0f305d8d1e1a47525f011819f2e32b0089fe13cc Mon Sep 17 00:00:00 2001 From: Jib Date: Tue, 24 Mar 2026 09:07:56 -0400 Subject: [PATCH 1/5] DRIVERS-3427 Phase 1 rollout: configurable retries, retargeting knob, retry metadata - Change MAX_RETRIES default from 5 to 2; expose as configurable maxAdaptiveRetries option - Add enableOverloadRetargeting option (default: false) to gate server deprioritization - Add "retry": N field requirement for outgoing command bodies on retry attempts - Renumber overload retry policy rules accordingly Co-Authored-By: Claude Code --- .../client-backpressure.md | 19 ++++++++++++++----- 1 file changed, 14 insertions(+), 5 deletions(-) diff --git a/source/client-backpressure/client-backpressure.md b/source/client-backpressure/client-backpressure.md index 5bf6f211b3..992de1ad22 100644 --- a/source/client-backpressure/client-backpressure.md +++ b/source/client-backpressure/client-backpressure.md @@ -122,7 +122,8 @@ rules: 2. A retry attempt will only be permitted if: 1. The error is a retryable overload error. 2. We have not reached `MAX_RETRIES`. - - The value of `MAX_RETRIES` is 5 and non-configurable. + - The default value of `MAX_RETRIES` is 2. Drivers MUST expose this as a configurable option named + `maxAdaptiveRetries`. - This intentionally changes the behavior of CSOT which otherwise would retry an unlimited number of times within the timeout to avoid retry storms. 3. (CSOT-only): There is still time for a retry attempt according to the @@ -142,10 +143,15 @@ rules: - `MAX_BACKOFF` is 10000ms. - This results in delays of 100ms, 200ms, 400ms, 800ms, and 1600ms before accounting for jitter. 4. If the request is eligible for retry (as outlined in step 2 above and step 4 in the - [adaptive retry requirements](client-backpressure.md#adaptive-retry-requirements) below), the client MUST add the - previously used server's address to the list of deprioritized server addresses for - [server selection](../server-selection/server-selection.md). + [adaptive retry requirements](client-backpressure.md#adaptive-retry-requirements) below) and + `enableOverloadRetargeting` is enabled, the client MUST add the previously used server's address to the list of + deprioritized server addresses for [server selection](../server-selection/server-selection.md). Drivers MUST expose + this as a configurable boolean option named `enableOverloadRetargeting` defaulting to `false`. 5. If the request is eligible for retry (as outlined in step 2 above and step 4 in the + [adaptive retry requirements](client-backpressure.md#adaptive-retry-requirements) below), the client MUST add a + `"retry"` field to the outgoing command body containing the current attempt number (starting at 1 for the first + retry). This allows the server to observe the impact of retry storms. +6. If the request is eligible for retry (as outlined in step 2 above and step 4 in the [adaptive retry requirements](client-backpressure.md#adaptive-retry-requirements) below) and is a retryable write: 1. If the command is a part of a transaction, the instructions for command modification on retry for commands in transactions MUST be followed, as outlined in the @@ -153,7 +159,7 @@ rules: 2. If the command is a not a part of a transaction, the instructions for command modification on retry for retryable writes MUST be followed, as outlined in the [retryable writes](../retryable-writes/retryable-writes.md) specification. -6. If the request is not eligible for any retries, then the client MUST propagate errors following the behaviors +7. If the request is not eligible for any retries, then the client MUST propagate errors following the behaviors described in the [retryable reads](../retryable-reads/retryable-reads.md), [retryable writes](../retryable-writes/retryable-writes.md) and the [transactions](../transactions/transactions.md) specifications. @@ -468,6 +474,9 @@ retrying a write command when only `retryReads` is enabled. ## Changelog +- 2026-03-23: Change `MAX_RETRIES` default to 2 with configurable `maxAdaptiveRetries` option. Add + `enableOverloadRetargeting` option (default `false`). Add retry metadata (`"retry"` field) to retried commands. + - 2026-02-20: Disable token buckets by default. - 2026-01-09: Initial version. From 72cc464b45ba07517ba2d1fa81ffd17fa431b23c Mon Sep 17 00:00:00 2001 From: Jib Date: Tue, 24 Mar 2026 16:21:43 -0400 Subject: [PATCH 2/5] Apply suggestion from @Jibola --- source/client-backpressure/client-backpressure.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/source/client-backpressure/client-backpressure.md b/source/client-backpressure/client-backpressure.md index 992de1ad22..f919c1fb27 100644 --- a/source/client-backpressure/client-backpressure.md +++ b/source/client-backpressure/client-backpressure.md @@ -474,9 +474,6 @@ retrying a write command when only `retryReads` is enabled. ## Changelog -- 2026-03-23: Change `MAX_RETRIES` default to 2 with configurable `maxAdaptiveRetries` option. Add - `enableOverloadRetargeting` option (default `false`). Add retry metadata (`"retry"` field) to retried commands. - - 2026-02-20: Disable token buckets by default. - 2026-01-09: Initial version. From ab34435a97b377768f4f50e1daa44ced51e7f6ae Mon Sep 17 00:00:00 2001 From: Jib Date: Wed, 25 Mar 2026 11:07:38 -0400 Subject: [PATCH 3/5] Change default MAX_RETRIES value and configuration note Updated the default value of MAX_RETRIES to 2 and clarified its exposure as a configurable option. --- source/client-backpressure/client-backpressure.md | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/source/client-backpressure/client-backpressure.md b/source/client-backpressure/client-backpressure.md index f919c1fb27..2715b9f983 100644 --- a/source/client-backpressure/client-backpressure.md +++ b/source/client-backpressure/client-backpressure.md @@ -122,8 +122,7 @@ rules: 2. A retry attempt will only be permitted if: 1. The error is a retryable overload error. 2. We have not reached `MAX_RETRIES`. - - The default value of `MAX_RETRIES` is 2. Drivers MUST expose this as a configurable option named - `maxAdaptiveRetries`. + - The default value of `MAX_RETRIES` is 2. Drivers MUST expose this as a configurable option. - This intentionally changes the behavior of CSOT which otherwise would retry an unlimited number of times within the timeout to avoid retry storms. 3. (CSOT-only): There is still time for a retry attempt according to the @@ -205,7 +204,7 @@ BASE_BACKOFF = 0.1 # 100ms MAX_BACKOFF = 10 # 10000ms RETRY_TOKEN_RETURN_RATE = 0.1 -MAX_RETRIES = 5 +MAX_RETRIES = 2 def execute_command_retryable(command, ...): deprioritized_servers = [] From b6b29aece64e93ce48213ea5953be27da2ebc485 Mon Sep 17 00:00:00 2001 From: Jib Date: Wed, 25 Mar 2026 11:21:28 -0400 Subject: [PATCH 4/5] Update MAX_RETRIES option to include 'maxRetries' --- source/client-backpressure/client-backpressure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/client-backpressure/client-backpressure.md b/source/client-backpressure/client-backpressure.md index 2715b9f983..c310246cef 100644 --- a/source/client-backpressure/client-backpressure.md +++ b/source/client-backpressure/client-backpressure.md @@ -122,7 +122,7 @@ rules: 2. A retry attempt will only be permitted if: 1. The error is a retryable overload error. 2. We have not reached `MAX_RETRIES`. - - The default value of `MAX_RETRIES` is 2. Drivers MUST expose this as a configurable option. + - The default value of `MAX_RETRIES` is 2. Drivers MUST expose this as a configurable option `maxRetries`. - This intentionally changes the behavior of CSOT which otherwise would retry an unlimited number of times within the timeout to avoid retry storms. 3. (CSOT-only): There is still time for a retry attempt according to the From dac8a50816a5e5d08a20fd3d3e76b60c0c08c795 Mon Sep 17 00:00:00 2001 From: Jib Date: Wed, 25 Mar 2026 11:24:18 -0400 Subject: [PATCH 5/5] Apply suggestions from code review Co-authored-by: Jib --- source/client-backpressure/client-backpressure.md | 6 +----- 1 file changed, 1 insertion(+), 5 deletions(-) diff --git a/source/client-backpressure/client-backpressure.md b/source/client-backpressure/client-backpressure.md index c310246cef..5f489cab80 100644 --- a/source/client-backpressure/client-backpressure.md +++ b/source/client-backpressure/client-backpressure.md @@ -147,10 +147,6 @@ rules: deprioritized server addresses for [server selection](../server-selection/server-selection.md). Drivers MUST expose this as a configurable boolean option named `enableOverloadRetargeting` defaulting to `false`. 5. If the request is eligible for retry (as outlined in step 2 above and step 4 in the - [adaptive retry requirements](client-backpressure.md#adaptive-retry-requirements) below), the client MUST add a - `"retry"` field to the outgoing command body containing the current attempt number (starting at 1 for the first - retry). This allows the server to observe the impact of retry storms. -6. If the request is eligible for retry (as outlined in step 2 above and step 4 in the [adaptive retry requirements](client-backpressure.md#adaptive-retry-requirements) below) and is a retryable write: 1. If the command is a part of a transaction, the instructions for command modification on retry for commands in transactions MUST be followed, as outlined in the @@ -158,7 +154,7 @@ rules: 2. If the command is a not a part of a transaction, the instructions for command modification on retry for retryable writes MUST be followed, as outlined in the [retryable writes](../retryable-writes/retryable-writes.md) specification. -7. If the request is not eligible for any retries, then the client MUST propagate errors following the behaviors +6. If the request is not eligible for any retries, then the client MUST propagate errors following the behaviors described in the [retryable reads](../retryable-reads/retryable-reads.md), [retryable writes](../retryable-writes/retryable-writes.md) and the [transactions](../transactions/transactions.md) specifications.