From 339803538d001d77013cff7490746cc10ceae01b Mon Sep 17 00:00:00 2001 From: Nabil Hachicha Date: Thu, 2 Apr 2026 16:00:42 +0100 Subject: [PATCH 1/6] Fixes DRIVERS-3436 --- .../tests/README.md | 20 ++++---- .../transactions-convenient-api.md | 48 ++++++++++++------- 2 files changed, 42 insertions(+), 26 deletions(-) diff --git a/source/transactions-convenient-api/tests/README.md b/source/transactions-convenient-api/tests/README.md index 6c94f8762b..fc917f0b54 100644 --- a/source/transactions-convenient-api/tests/README.md +++ b/source/transactions-convenient-api/tests/README.md @@ -29,23 +29,23 @@ Write a callback that returns a custom value (e.g. boolean, string, object). Exe Drivers should test that `withTransaction` enforces a non-configurable timeout before retrying both commits and entire transactions. Specifically, three cases should be checked: -- If the callback raises an error with the TransientTransactionError label and the retry timeout has been exceeded, - `withTransaction` should propagate the error (see Note 1 below) to its caller. +- If the callback raises an error with the `TransientTransactionError` label and the retry timeout has been exceeded, + `withTransaction` should propagate the error as described in the + [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) below) to its caller. - If committing raises an error with the UnknownTransactionCommitResult label, and the retry timeout has been exceeded, - `withTransaction` should propagate the error (see Note 1 below) to its caller. + `withTransaction` should propagate the error as described in the + [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. - If committing raises an error with the TransientTransactionError label and the retry timeout has been exceeded, - `withTransaction` should propagate the error (see Note 1 below) to its caller. This case may occur if the commit was - internally retried against a new primary after a failover and the second primary returned a NoSuchTransaction error - response. + `withTransaction` should propagate the error as described in the + [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. This + case may occur if the commit was internally retried against a new primary after a failover and the second primary + returned a `NoSuchTransaction` error response. If possible, drivers should implement these tests without requiring the test runner to block for the full duration of the retry timeout. This might be done by internally modifying the timeout value used by `withTransaction` with some private API or using a mock timer. -______________________________________________________________________ - -**Note 1:** The error SHOULD be propagated as a timeout error if the language allows to expose the underlying error as a -cause of a timeout error. +The drivers should assert that the timeout error propagated has the same labels as the error it wraps. ### Retry Backoff is Enforced diff --git a/source/transactions-convenient-api/transactions-convenient-api.md b/source/transactions-convenient-api/transactions-convenient-api.md index d74707b481..48b97b4ec5 100644 --- a/source/transactions-convenient-api/transactions-convenient-api.md +++ b/source/transactions-convenient-api/transactions-convenient-api.md @@ -123,8 +123,9 @@ This method should perform the following sequence of actions: 2. If `transactionAttempt` > 0: - 1. If elapsed time + `backoffMS` > `TIMEOUT_MS`, then raise the previously encountered error (see Note 1 below). If - the elapsed time of `withTransaction` is less than TIMEOUT_MS, calculate the backoffMS to be + 1. If elapsed time + `backoffMS` > `TIMEOUT_MS`, then propagate the previously encountered error (see + [propagation section](transactions-convenient-api.md#timeout-error-propagation-mechanism) below). If the + elapsed time of `withTransaction` is less than TIMEOUT_MS, calculate the backoffMS to be `jitter * min(BACKOFF_INITIAL * 1.5 ** (transactionAttempt - 1), BACKOFF_MAX)`. sleep for `backoffMS`. 1. jitter is a random float between \[0, 1), optionally including 1, depending on what is most natural for the @@ -163,8 +164,9 @@ This method should perform the following sequence of actions: committed a transaction, propagate the callback's error to the caller of `withTransaction` and return immediately. - 4. Otherwise, propagate the callback's error (see Note 1 below) to the caller of `withTransaction` and return - immediately. + 4. Otherwise, propagate the callback's error (see + [propagation section](transactions-convenient-api.md#timeout-error-propagation-mechanism) below) to the caller + of `withTransaction` and return immediately. 8. If the ClientSession is in the "no transaction", "transaction aborted", or "transaction committed" state, assume the callback intentionally aborted or committed the transaction and return immediately. @@ -180,20 +182,21 @@ This method should perform the following sequence of actions: 2. If the `commitTransaction` error includes a "TransientTransactionError" label, jump back to step two. - 3. Otherwise, propagate the `commitTransaction` error (see Note 1 below) to the caller of `withTransaction` and - return immediately. + 3. Otherwise, propagate the `commitTransaction` error (see + [propagation section](transactions-convenient-api.md#timeout-error-propagation-mechanism) below) to the caller + of `withTransaction` and return immediately. 11. The transaction was committed successfully. Return immediately. -______________________________________________________________________ +###### Timeout Error propagation mechanism -**Note 1:** When the `TIMEOUT_MS` (calculated in step [1.3](#sequence-of-actions)) is reached we MUST report a timeout -error wrapping the last error that was encountered which triggered the retry behavior. If `timeoutMS` is set, then -timeout error is a special type which is defined in CSOT +When the `TIMEOUT_MS` (calculated in step [1.3](#sequence-of-actions)) is reached we MUST report a timeout error +wrapping the previously encountered error. If `timeoutMS` is set, then timeout error is a special type which is defined +in CSOT [specification](https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.md#errors) -, If `timeoutMS` is not set, then propagate it as timeout error if the language allows to expose the underlying error as -a cause of a timeout error (see `makeTimeoutError` below in [pseudo-code](#pseudo-code)). If timeout error is thrown -then it SHOULD expose error label(s) from the transient error. +, If `timeoutMS` is not set, then propagate it as timeout error if the language allows to expose the previously +encountered error as a cause of a timeout error (see `makeTimeoutError` below in [pseudo-code](#pseudo-code)). If +timeout error is thrown then it SHOULD copy all error label(s) from the previously encountered error. ##### Pseudo-code @@ -228,11 +231,13 @@ withTransaction(callback, options) { callback(this); } catch (error) { lastError = error; + // step 7.1 if (this.transactionState == STARTING || this.transactionState == IN_PROGRESS) { this.abortTransaction(); } + // step 7.2 if (error.hasErrorLabel("TransientTransactionError")) { if (Date.now() - startTime < timeout) { continue retryTransaction; @@ -241,9 +246,16 @@ withTransaction(callback, options) { } } - throw error; + // step 7.3 + if (error.hasErrorLabel("UnknownTransactionCommitResult")) { + throw error; + } + + // step 7.4 + throw makeTimeoutError(error); } + // step 8 if (this.transactionState == NO_TXN || this.transactionState == COMMITTED || this.transactionState == ABORTED) { @@ -252,6 +264,7 @@ withTransaction(callback, options) { retryCommit: while (true) { try { + // step 9 /* We will rely on ClientSession.commitTransaction() to * apply a majority write concern if commitTransaction is * being retried (see: DRIVERS-601) */ @@ -267,15 +280,18 @@ withTransaction(callback, options) { if (Date.now() - startTime >= timeout) { throw makeTimeoutError(error); } + // step 10.1 if (!isMaxTimeMSExpiredError(error) && error.hasErrorLabel("UnknownTransactionCommitResult")) { continue retryCommit; } + // step 10.2 if (error.hasErrorLabel("TransientTransactionError")) { continue retryTransaction; } + // step 10.3 throw error; } break; // Commit was successful @@ -348,8 +364,8 @@ An earlier design also considered using the callback's return value to indicate of two ways: - The callback aborts the transaction directly and returns to `withTransaction`, which will then return to its caller. -- The callback raises an error without the "TransientTransactionError" label, in which case `withTransaction` will abort - the transaction and return to its caller. +- The callback propagates an error without the "TransientTransactionError" label, in which case `withTransaction` will + abort the transaction and return to its caller. ### Applications are responsible for passing ClientSession for operations within a transaction From dc02bb2ed40108997930c6efa45bf186a43cc2d6 Mon Sep 17 00:00:00 2001 From: Nabil Hachicha Date: Thu, 2 Apr 2026 18:31:24 +0100 Subject: [PATCH 2/6] PR feedback --- .../transactions-convenient-api.md | 28 +++---------------- 1 file changed, 4 insertions(+), 24 deletions(-) diff --git a/source/transactions-convenient-api/transactions-convenient-api.md b/source/transactions-convenient-api/transactions-convenient-api.md index 48b97b4ec5..3ce6f65426 100644 --- a/source/transactions-convenient-api/transactions-convenient-api.md +++ b/source/transactions-convenient-api/transactions-convenient-api.md @@ -164,9 +164,7 @@ This method should perform the following sequence of actions: committed a transaction, propagate the callback's error to the caller of `withTransaction` and return immediately. - 4. Otherwise, propagate the callback's error (see - [propagation section](transactions-convenient-api.md#timeout-error-propagation-mechanism) below) to the caller - of `withTransaction` and return immediately. + 4. Otherwise, propagate the callback's error to the caller of `withTransaction` and return immediately. 8. If the ClientSession is in the "no transaction", "transaction aborted", or "transaction committed" state, assume the callback intentionally aborted or committed the transaction and return immediately. @@ -182,9 +180,7 @@ This method should perform the following sequence of actions: 2. If the `commitTransaction` error includes a "TransientTransactionError" label, jump back to step two. - 3. Otherwise, propagate the `commitTransaction` error (see - [propagation section](transactions-convenient-api.md#timeout-error-propagation-mechanism) below) to the caller - of `withTransaction` and return immediately. + 3. Otherwise, propagate the `commitTransaction` error to the caller of `withTransaction` and return immediately. 11. The transaction was committed successfully. Return immediately. @@ -196,7 +192,7 @@ in CSOT [specification](https://github.com/mongodb/specifications/blob/master/source/client-side-operations-timeout/client-side-operations-timeout.md#errors) , If `timeoutMS` is not set, then propagate it as timeout error if the language allows to expose the previously encountered error as a cause of a timeout error (see `makeTimeoutError` below in [pseudo-code](#pseudo-code)). If -timeout error is thrown then it SHOULD copy all error label(s) from the previously encountered error. +timeout error is thrown then it SHOULD copy all error label(s) from the previously encountered retriable error. ##### Pseudo-code @@ -231,13 +227,11 @@ withTransaction(callback, options) { callback(this); } catch (error) { lastError = error; - // step 7.1 if (this.transactionState == STARTING || this.transactionState == IN_PROGRESS) { this.abortTransaction(); } - // step 7.2 if (error.hasErrorLabel("TransientTransactionError")) { if (Date.now() - startTime < timeout) { continue retryTransaction; @@ -246,16 +240,9 @@ withTransaction(callback, options) { } } - // step 7.3 - if (error.hasErrorLabel("UnknownTransactionCommitResult")) { - throw error; - } - - // step 7.4 - throw makeTimeoutError(error); + throw error; } - // step 8 if (this.transactionState == NO_TXN || this.transactionState == COMMITTED || this.transactionState == ABORTED) { @@ -264,7 +251,6 @@ withTransaction(callback, options) { retryCommit: while (true) { try { - // step 9 /* We will rely on ClientSession.commitTransaction() to * apply a majority write concern if commitTransaction is * being retried (see: DRIVERS-601) */ @@ -277,21 +263,15 @@ withTransaction(callback, options) { * {ok:1, writeConcernError: {code: 50, codeName: "MaxTimeMSExpired"}} */ lastError = error; - if (Date.now() - startTime >= timeout) { - throw makeTimeoutError(error); - } - // step 10.1 if (!isMaxTimeMSExpiredError(error) && error.hasErrorLabel("UnknownTransactionCommitResult")) { continue retryCommit; } - // step 10.2 if (error.hasErrorLabel("TransientTransactionError")) { continue retryTransaction; } - // step 10.3 throw error; } break; // Commit was successful From 77ab714092705694aa52ebf8dd514b156d739c9d Mon Sep 17 00:00:00 2001 From: Nabil Hachicha Date: Thu, 2 Apr 2026 19:08:52 +0100 Subject: [PATCH 3/6] Update source/transactions-convenient-api/tests/README.md Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com> --- source/transactions-convenient-api/tests/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/source/transactions-convenient-api/tests/README.md b/source/transactions-convenient-api/tests/README.md index fc917f0b54..56a778a65e 100644 --- a/source/transactions-convenient-api/tests/README.md +++ b/source/transactions-convenient-api/tests/README.md @@ -31,7 +31,7 @@ transactions. Specifically, three cases should be checked: - If the callback raises an error with the `TransientTransactionError` label and the retry timeout has been exceeded, `withTransaction` should propagate the error as described in the - [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) below) to its caller. + [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. - If committing raises an error with the UnknownTransactionCommitResult label, and the retry timeout has been exceeded, `withTransaction` should propagate the error as described in the [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. From 847816e802dce0c7101f6f8b1c42bee90d9b0342 Mon Sep 17 00:00:00 2001 From: Nabil Hachicha Date: Thu, 2 Apr 2026 19:14:27 +0100 Subject: [PATCH 4/6] Remove error wrapping for UnknownTransactionCommitResult --- source/transactions-convenient-api/tests/README.md | 7 +++---- 1 file changed, 3 insertions(+), 4 deletions(-) diff --git a/source/transactions-convenient-api/tests/README.md b/source/transactions-convenient-api/tests/README.md index 56a778a65e..94ea17d24b 100644 --- a/source/transactions-convenient-api/tests/README.md +++ b/source/transactions-convenient-api/tests/README.md @@ -32,10 +32,9 @@ transactions. Specifically, three cases should be checked: - If the callback raises an error with the `TransientTransactionError` label and the retry timeout has been exceeded, `withTransaction` should propagate the error as described in the [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. -- If committing raises an error with the UnknownTransactionCommitResult label, and the retry timeout has been exceeded, - `withTransaction` should propagate the error as described in the - [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. -- If committing raises an error with the TransientTransactionError label and the retry timeout has been exceeded, +- If committing raises an error with the `UnknownTransactionCommitResult` label, and the retry timeout has been exceeded, + `withTransaction` should propagate the error to its caller. +- If committing raises an error with the `TransientTransactionError` label and the retry timeout has been exceeded, `withTransaction` should propagate the error as described in the [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. This case may occur if the commit was internally retried against a new primary after a failover and the second primary From 1d4ec77e723fcfd5f405913156291f5af354c696 Mon Sep 17 00:00:00 2001 From: Nabil Hachicha Date: Thu, 2 Apr 2026 19:25:40 +0100 Subject: [PATCH 5/6] Update changelog --- source/transactions-convenient-api/tests/README.md | 6 ++++-- .../transactions-convenient-api.md | 3 +++ 2 files changed, 7 insertions(+), 2 deletions(-) diff --git a/source/transactions-convenient-api/tests/README.md b/source/transactions-convenient-api/tests/README.md index 94ea17d24b..c4e87a2a79 100644 --- a/source/transactions-convenient-api/tests/README.md +++ b/source/transactions-convenient-api/tests/README.md @@ -32,8 +32,8 @@ transactions. Specifically, three cases should be checked: - If the callback raises an error with the `TransientTransactionError` label and the retry timeout has been exceeded, `withTransaction` should propagate the error as described in the [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. -- If committing raises an error with the `UnknownTransactionCommitResult` label, and the retry timeout has been exceeded, - `withTransaction` should propagate the error to its caller. +- If committing raises an error with the `UnknownTransactionCommitResult` label, and the retry timeout has been + exceeded, `withTransaction` should propagate the error to its caller. - If committing raises an error with the `TransientTransactionError` label and the retry timeout has been exceeded, `withTransaction` should propagate the error as described in the [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. This @@ -111,6 +111,8 @@ Drivers should test that retries within `withTransaction` do not occur immediate ## Changelog +- 2026-04-02: [DRIVERS-3436](https://github.com/mongodb/specifications/pull/1920) Refine withTransaction timeout error + wrapping semantics and label propagation in spec and prose tests - 2026-03-03: Clarify exponential backoff jitter upper bound. - 2026-02-17: Clarify expected error when timeout is reached [DRIVERS-3391](https://jira.mongodb.org/browse/DRIVERS-3391). diff --git a/source/transactions-convenient-api/transactions-convenient-api.md b/source/transactions-convenient-api/transactions-convenient-api.md index 3ce6f65426..bf0737ce2b 100644 --- a/source/transactions-convenient-api/transactions-convenient-api.md +++ b/source/transactions-convenient-api/transactions-convenient-api.md @@ -436,6 +436,9 @@ provides an implementation of a technique already described in the MongoDB 4.0 d ## Changelog +- 2026-04-02: [DRIVERS-3436](https://github.com/mongodb/specifications/pull/1920) Refine withTransaction timeout error + wrapping semantics and label propagation in spec and prose tests. + - 2026-03-03: Clarify exponential backoff jitter upper bound. - 2026-02-20: Fix initial backoff and growth value parameters in "Design Rationale" section. From 3df2210914292a250300262d847a35564b15e203 Mon Sep 17 00:00:00 2001 From: Nabil Hachicha Date: Fri, 3 Apr 2026 16:31:52 +0100 Subject: [PATCH 6/6] Add missing case for error propagation --- .../transactions-convenient-api/tests/README.md | 3 ++- .../transactions-convenient-api.md | 16 ++++++++++++---- 2 files changed, 14 insertions(+), 5 deletions(-) diff --git a/source/transactions-convenient-api/tests/README.md b/source/transactions-convenient-api/tests/README.md index c4e87a2a79..e978343dbd 100644 --- a/source/transactions-convenient-api/tests/README.md +++ b/source/transactions-convenient-api/tests/README.md @@ -33,7 +33,8 @@ transactions. Specifically, three cases should be checked: `withTransaction` should propagate the error as described in the [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. - If committing raises an error with the `UnknownTransactionCommitResult` label, and the retry timeout has been - exceeded, `withTransaction` should propagate the error to its caller. + exceeded, `withTransaction` should propagate the error as described in the + [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller - If committing raises an error with the `TransientTransactionError` label and the retry timeout has been exceeded, `withTransaction` should propagate the error as described in the [propagation mechanism](../transactions-convenient-api.md#timeout-error-propagation-mechanism) to its caller. This diff --git a/source/transactions-convenient-api/transactions-convenient-api.md b/source/transactions-convenient-api/transactions-convenient-api.md index bf0737ce2b..2443ad4b3a 100644 --- a/source/transactions-convenient-api/transactions-convenient-api.md +++ b/source/transactions-convenient-api/transactions-convenient-api.md @@ -173,10 +173,15 @@ This method should perform the following sequence of actions: 10. If `commitTransaction` reported an error: - 1. If the `commitTransaction` error includes a "UnknownTransactionCommitResult" label and the error is not - MaxTimeMSExpired and the elapsed time of `withTransaction` is less than TIMEOUT_MS, jump back to step nine. We - will trust `commitTransaction` to apply a majority write concern on retry attempts (see: - [Majority write concern is used when retrying commitTransaction](#majority-write-concern-is-used-when-retrying-committransaction)). + 1. If the `commitTransaction` error includes a `UnknownTransactionCommitResult` label and the error is not + `MaxTimeMSExpired` + + 1. If the elapsed time of `withTransaction` exceeded `TIMEOUT_MS`, propagate the `commitTransaction` error to the + caller of `withTransaction` and return immediately (see + [propagation section](transactions-convenient-api.md#timeout-error-propagation-mechanism) below) + 2. If the elapsed time of `withTransaction` is less than `TIMEOUT_MS`, jump back to step nine. We will trust + `commitTransaction` to apply a majority write concern on retry attempts (see: + [Majority write concern is used when retrying commitTransaction](#majority-write-concern-is-used-when-retrying-committransaction)). 2. If the `commitTransaction` error includes a "TransientTransactionError" label, jump back to step two. @@ -265,6 +270,9 @@ withTransaction(callback, options) { lastError = error; if (!isMaxTimeMSExpiredError(error) && error.hasErrorLabel("UnknownTransactionCommitResult")) { + if (Date.now() - startTime >= timeout) { + throw makeTimeoutError(error); + } continue retryCommit; }