Skip to content

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

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
stIncMale merged 15 commits into from
Apr 10, 2026
+52 −41
Merged

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

Show file tree
Hide file tree
Changes from 5 commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
3398035
Fixes DRIVERS-3436
nhachicha Apr 2, 2026
dc02bb2
PR feedback
nhachicha Apr 2, 2026
77ab714
Update source/transactions-convenient-api/tests/README.md
nhachicha Apr 2, 2026
847816e
Remove error wrapping for UnknownTransactionCommitResult
nhachicha Apr 2, 2026
1d4ec77
Update changelog
nhachicha Apr 2, 2026
3df2210
Add missing case for error propagation
nhachicha Apr 3, 2026
d410325
Update source/transactions-convenient-api/transactions-convenient-api.md
nhachicha Apr 10, 2026
8ec2180
Refactor the "Timeout Error propagation mechanism" section
stIncMale Apr 10, 2026
e416f1f
Make the "propagate as is" vs "propagate as per timeout error propaga…
stIncMale Apr 10, 2026
6d97107
Add the "propagate...to the caller of `withTransaction`...and return …
stIncMale Apr 10, 2026
3bbcdc0
Address remaining review feedback for terminology and formatting
nhachicha Apr 10, 2026
893f9d4
Fix broken anchor links in prose tests README
nhachicha Apr 10, 2026
5444a68
Refactor step 2.1
stIncMale Apr 10, 2026
f1c0623
Fix formatting
stIncMale Apr 10, 2026
f674dc7
Fix formatting
stIncMale Apr 10, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
25 changes: 13 additions & 12 deletions source/transactions-convenient-api/tests/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -29,23 +29,22 @@ 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 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.
- 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.
- 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.
Copy link
Copy Markdown
Contributor

@NoahStapp NoahStapp Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is this point also supposed to call out the propagation mechanism?

Copy link
Copy Markdown
Contributor Author

@nhachicha nhachicha Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Good catch 👍 I fixed the prose and the spec.
TL;DR UnknownTransactionCommitResult is retriable in the commit loop if we don't exceed the timeout, so it makes sense to wrap it into a Timeout error if we exceed the timeout and want to throw and return (as described in section 10.1.1)

- 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
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

Expand Down Expand Up @@ -112,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).
Expand Down
35 changes: 17 additions & 18 deletions source/transactions-convenient-api/transactions-convenient-api.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -163,8 +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 Note 1 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.
Expand All @@ -180,20 +180,19 @@ 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 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 retriable error.

##### Pseudo-code

Expand Down Expand Up @@ -264,9 +263,6 @@ withTransaction(callback, options) {
* {ok:1, writeConcernError: {code: 50, codeName: "MaxTimeMSExpired"}}
*/
lastError = error;
if (Date.now() - startTime >= timeout) {
Copy link
Copy Markdown
Contributor Author

@nhachicha nhachicha Apr 2, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This was removed because in sections 7.4 & 10.3 of the [sequence-of-actions|https://github.com/mongodb/specifications/blob/master/source/transactions-convenient-api/transactions-convenient-api.md#sequence-of-actions] the errors are not retriable, and they are mainly the reason for returning immediately from withTransaction. So there's no need to wrap them in a TimeoutError (if Timeout is encountered)

Copy link
Copy Markdown
Contributor Author

@nhachicha nhachicha Apr 3, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

However, in section 10.1.1 (UnknownTransactionCommitResult encountered during commit) The error is retriable if the timeout is not exeeded. So the wrapping into a timeout error needs to happen if we are throwing

throw makeTimeoutError(error);
}
if (!isMaxTimeMSExpiredError(error) &&
error.hasErrorLabel("UnknownTransactionCommitResult")) {
continue retryCommit;
Expand Down Expand Up @@ -348,8 +344,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

Expand Down Expand Up @@ -440,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.
Expand Down
Loading