GODRIVER-3810 Update WithTransaction to raise timeout error. by qingyang-hu · Pull Request #2344 · mongodb/mongo-go-driver

qingyang-hu · 2026-03-19T21:49:02Z

GODRIVER-3810, GODRIVER-3853

NOTE: GODRIVER-3853 supersedes some of the changes introduced by GODRIVER-3810.

Summary

Create a TimeoutError type to be used for backoff timeouts in WithTransaction().

Background & Motivation

mongodb-drivers-pr-bot · 2026-03-19T21:53:41Z

API Change Report

./v2/mongo

compatible changes

TimeoutError: added

mongodb-drivers-pr-bot · 2026-03-19T21:54:55Z

🧪 Performance Results

Commit SHA: f440be0

The following benchmark tests for version 69dd6d1e2b23cb00078ede23 had statistically significant changes (i.e., |z-score| > 1.96):

Benchmark	Measurement	% Change	Patch Value	Stable Region	H-Score	Z-Score
BenchmarkMultiFindMany	ops_per_second_min	-89.4025	4673.0501	Avg: 44095.9342 Med: 45057.2227 Stdev: 10053.6625	0.8613	-3.9212
BenchmarkBSONFlatDocumentEncoding	ops_per_second_min	-45.8028	2011.7891	Avg: 3711.9770 Med: 3840.0541 Stdev: 745.5166	0.8332	-2.2805
BenchmarkSingleFindOneByID	ops_per_second_min	-35.6396	804.6755	Avg: 1250.2639 Med: 1243.3079 Stdev: 171.5049	0.7945	-2.5981
BenchmarkMultiFindMany	ops_per_second_max	-3.1391	4098360.6557	Avg: 4231181.9272 Med: 4237288.1356 Stdev: 55172.0294	0.7843	-2.4074

For a comprehensive view of all microbenchmark results for this PR's commit, please check out the Evergreen perf task for this patch.

Copilot

Pull request overview

This PR introduces a new TimeoutError type to better surface WithTransaction() timeouts (with proper timeout labeling), and updates the unified test runner plumbing so spec tests can assert on the WithTransaction() error value rather than treating it as a harness failure.

Changes:

Add mongo.TimeoutError (wrapping an underlying cause and reporting ExceededTimeLimitError via HasErrorLabel).
Update Session.WithTransaction() to return TimeoutError{Wrapped: err} for timeout-driven retry/backoff exits.
Update unified spec runner operation execution to propagate operation results (including Err) and unskip a previously skipped CSOT convenient-transactions spec test.

Reviewed changes

Copilot reviewed 7 out of 7 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
`mongo/session.go`	Wraps certain overall-timeout exit paths in `TimeoutError` when retry/backoff would exceed the transaction timeout.
`mongo/errors.go`	Adds the exported `TimeoutError` type with `Unwrap()` and `HasErrorLabel()` support.
`internal/spectest/skip.go`	Removes a skip entry for the convenient-transactions timeout surfacing test.
`internal/integration/unified/unified_spec_runner.go`	Updates caller to handle `operation.execute()` returning a result + error.
`internal/integration/unified/testrunner_operation.go`	Updates thread/loop execution to match new `operation.execute()` signature.
`internal/integration/unified/session_operation_execution.go`	Changes `withTransaction` operation to return the `WithTransaction()` error in `operationResult.Err` for verification.
`internal/integration/unified/operation.go`	Changes `operation.execute()` signature to return `*operationResult` alongside an execution error.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-03-20T12:20:17Z

+// TimeoutError represents an error that occurred due to a timeout.
+type TimeoutError struct {
+	Wrapped error
+}
+
+// Error implements the error interface.
+func (e TimeoutError) Error() string {
+	return e.Wrapped.Error()
+}
+
+// Unwrap returns the underlying error.
+func (e TimeoutError) Unwrap() error {
+	return e.Wrapped
+}
+
+// HasErrorLabel returns true if the error contains the specified label.
+func (e TimeoutError) HasErrorLabel(label string) bool {
+	if label == "ExceededTimeLimitError" {
+		return true
+	} else if le := LabeledError(nil); errors.As(e.Wrapped, &le) {
+		return le.HasErrorLabel(label)
+	}
+	return false
+}


Consider adding a unit test for TimeoutError to ensure it integrates with existing timeout detection and labeling (e.g., IsTimeout should return true via the ExceededTimeLimitError label, and HasErrorLabel should delegate to the wrapped error for other labels). There are already table-driven tests for IsTimeout in mongo/errors_test.go that can be extended.

Copilot · 2026-03-20T12:20:17Z

+			_, err = threadOp.execute(ctx, loopDone)
+			return err


runOnThread: the added closure assigns to the outer-scoped err variable (_, err = threadOp.execute(...)). Because the task runs asynchronously, this captures and mutates a variable from the parent stack frame, which is a data race and can also clobber the error used earlier in the case block. Use a new local variable inside the closure (e.g., _, execErr := ...; return execErr) to avoid capturing/mutating outer state.

Suggested change

_, err = threadOp.execute(ctx, loopDone)

return err

_, execErr := threadOp.execute(ctx, loopDone)

return execErr

Copilot · 2026-03-20T12:20:18Z

+		var cbErr error
 		for idx, oper := range operations {
-			if err := oper.execute(ctx, loopDone); err != nil {
-				return nil, fmt.Errorf("error executing operation %q at index %d: %v", oper.Name, idx, err)
+			res, execErr := oper.execute(ctx, loopDone)
+			if execErr != nil {
+				err = fmt.Errorf("error executing operation %q at index %d: %v", oper.Name, idx, execErr)
+				return nil, nil
+			}
+			if cbErr == nil && res != nil {
+				cbErr = res.Err
 			}
 		}


executeWithTransaction callback: once an operation inside the callback produces a non-nil operation error (res.Err), the callback should return that error immediately so subsequent operations are not executed. The current logic records the first res.Err in cbErr but continues executing later operations, which can change transactional behavior compared to a real application callback and can cause extra side effects or different errors.

Copilot · 2026-03-20T12:20:18Z

+				err = fmt.Errorf("error executing operation %q at index %d: %v", oper.Name, idx, execErr)
+				return nil, nil


executeWithTransaction callback: on execErr, the callback currently returns (nil, nil), which causes WithTransaction to commit even though the callback did not successfully execute all operations, and relies on mutating the outer err to fail later. It would be safer to return the wrapped execution error from the callback so WithTransaction aborts/cleans up consistently and avoids committing partial work.

Suggested change

err = fmt.Errorf("error executing operation %q at index %d: %v", oper.Name, idx, execErr)

return nil, nil

return nil, fmt.Errorf("error executing operation %q at index %d: %w", oper.Name, idx, execErr)

Copilot · 2026-03-20T12:20:18Z

 			select {
 			case <-timeout.C:
-				return nil, err
+				return nil, TimeoutError{Wrapped: err}
 			default:
 			}


WithTransaction now wraps some timeout paths with TimeoutError, but other uses of the same overall timeout timer still return the raw err (e.g., the commit retry loop). This can lead to inconsistent timeout signaling/labeling for callers. If the goal is to surface a timeout error for WithTransaction timeouts, consider wrapping all returns caused by the overall timeout timer consistently.

tadjik1

hi @qingyang-hu , thanks for your work, it looks good!

I left few comments in the code on places I think should be improved, please let me know what you think about it.

tadjik1 · 2026-03-26T18:20:42Z

+	if e.Wrapped == nil {
+		return "operation timed out"
+	}
+	return e.Wrapped.Error()


I would suggest add some string prefix so this error is distinguishable (similar to what we do for other errors

Suggested change

return e.Wrapped.Error()

return "operation timed out: " + e.Wrapped.Error()

tadjik1 · 2026-03-26T18:27:18Z

-				return nil, fmt.Errorf("error executing operation %q at index %d: %v", oper.Name, idx, err)
+			res, execErr := oper.execute(ctx, loopDone)
+			if execErr != nil {
+				err = fmt.Errorf("error executing operation %q at index %d: %v", oper.Name, idx, execErr)


Just to clarify: we capture err here because we want to get "3rd type of result" from this function, errors that are not related to WithTransaction logic, right? So we do want to get error, but we don't want driver to handle this as if it's a transaction error.

Correct, we need to capture the error while still completing all operations in the transaction.

tadjik1 · 2026-03-26T18:37:20Z

 			case <-timeout.C:
 				sleep.Stop()
-				return nil, err
+				return nil, TimeoutError{Wrapped: err}


The spec says we have to distinguish between CSOT and non-CSOT errors:
Note 1: When the TIMEOUT_MS (calculated in step [1.3] 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 , 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. If timeout error is thrown then it SHOULD expose error label(s) from the transient error.
https://github.com/mongodb/specifications/blob/master/source/transactions-convenient-api/transactions-convenient-api.md#sequence-of-actions

In the current approach we always return TimeoutErrors which are indistinguishable.

@tadjik1 The non-CSOT path in WithTransaction uses a manual wall-clock check against the 120-second limit, not a context deadline. AFIAK context.DeadlineExceeded is always CSOT in Go Driver.

Also, since the original error is wrapped in the new type, the user can always trace back and distinguish the errors.

This is probably beyond the scope of this PR, but moving forward we should avoid picking which error to return and instead return all errors joined using errutil.Join

E.g.

var errs []error // ... select { case <-timeout.C: errs = append(errs, errors.New("default WithTransaction timeout reached")) return nil, errutil.Join(errs...) default: } // ...

matthewdale · 2026-04-16T23:26:19Z

+type TimeoutError struct {
+	Wrapped error


Does TimeoutError need to be exported? If not, we shouldn't export it.

Additionally, we need to update IsTimeout to return true if the error is a timeoutError, including a test to confirm IsTimeout works with the new error type.

matthewdale · 2026-04-16T23:33:57Z

+					select {
+					case <-timeout.C:
+						return res, TimeoutError{Wrapped: err}
+					default:


Is the intent of this change to only respect the default WithTransaction timeout if the error is a CommandError with label "UnknownTransactionCommitResult"?

GODRIVER-3810 Update WithTransaction to raise timeout error.

3aaab64

qingyang-hu added feature enhancement and removed feature labels Mar 19, 2026

qingyang-hu marked this pull request as ready for review March 20, 2026 12:16

Copilot AI review requested due to automatic review settings March 20, 2026 12:16

qingyang-hu requested a review from a team as a code owner March 20, 2026 12:16

qingyang-hu requested a review from tadjik1 March 20, 2026 12:16

Copilot started reviewing on behalf of qingyang-hu March 20, 2026 12:16 View session

Copilot AI reviewed Mar 20, 2026

View reviewed changes

qingyang-hu marked this pull request as draft March 20, 2026 12:38

fixes and unit tests for TimeoutError

48ba30a

qingyang-hu marked this pull request as ready for review March 20, 2026 20:03

tadjik1 suggested changes Mar 26, 2026

View reviewed changes

matthewdale self-requested a review April 6, 2026 20:25

qingyang-hu marked this pull request as draft April 10, 2026 14:56

GODRIVER-3853 Update erroring logic.

f440be0

qingyang-hu force-pushed the godriver3810 branch from b52f921 to f440be0 Compare April 13, 2026 22:24

qingyang-hu marked this pull request as ready for review April 13, 2026 22:57

matthewdale reviewed Apr 16, 2026

View reviewed changes

		err = fmt.Errorf("error executing operation %q at index %d: %v", oper.Name, idx, execErr)
		return nil, nil

	err = fmt.Errorf("error executing operation %q at index %d: %v", oper.Name, idx, execErr)
	return nil, nil
	return nil, fmt.Errorf("error executing operation %q at index %d: %w", oper.Name, idx, execErr)

	return e.Wrapped.Error()
	return "operation timed out: " + e.Wrapped.Error()

Conversation

qingyang-hu commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Summary

Background & Motivation

Uh oh!

mongodb-drivers-pr-bot bot commented Mar 19, 2026

API Change Report

./v2/mongo

compatible changes

Uh oh!

mongodb-drivers-pr-bot bot commented Mar 19, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🧪 Performance Results

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Mar 20, 2026

Choose a reason for hiding this comment

Uh oh!

tadjik1 left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

matthewdale Apr 17, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

5 participants

qingyang-hu commented Mar 19, 2026 •

edited

Loading

mongodb-drivers-pr-bot bot commented Mar 19, 2026 •

edited

Loading

matthewdale Apr 17, 2026 •

edited

Loading