JAVA-5950 Update Transactions Convenient API with exponential backoff on retries

[nhachicha]

Original PR accidentally closed #1852, it has outstanding review comments for @stIncMale to go over when re-reviewing.

Relevant specification changes:

• DRIVERS-1934: withTransaction API retries too frequently (#1851)
• DRIVERS-1934: clarify drivers back off before all transaction retries (#1868)
• DRIVERS-3364: Fix Retry Backoff is Enforced prose test.
• DRIVERS-3391: Clarify withTransaction CSOT timeout error with backoff+jitter
• DRIVERS-3436 - Refine withTransaction timeout error wrapping semantics and label propagation in spec and prose tests #1920
• DRIVERS-3370: Retry backoff jitter interval may include 1.0 (#1905)
• DRIVERS-3436: Refine withTransaction timeout error wrapping semantics and label propagation in spec and prose tests
  JAVA-5950, JAVA-6046, (JAVA-6093, JAVA-6160), JAVA-6113 (only the part about transactions-convenient-api)

AI usage and effectiveness

• Implementation (Sonnet/Opus 4.6): Partially AI-generated but went through many rounds of manual modifications. Tests were AI-generated based on the spec prose test descriptions, then reviewed and adjusted

• It did identify a potential spec divergence: the implementation wraps non-labeled errors in MongoTimeoutException, which later resulted in a discussion during catch-up and https://jira.mongodb.org/browse/DRIVERS-3436

• Copilot review 2/13 actionable (both minor nits) see details

Review generated by Claude Opus 4.6 as of commit `4a3d1ae1` on 2026-04-01.

Findings Table — Diff-Only Review vs. PR Context

#	Finding	Verdict	Rationale
1	Non-volatile testJitterSupplier static field — data race risk across threads	Valid, tracked	Multiple reviewers flagged. Test-only, deferred to JAVA-6079. Should be volatile at minimum.
2	Thread.sleep(backoffMs) may overshoot remaining timeout	False positive	shortenBy(...).onExpired(...) checks before sleeping; next iteration fails fast if expired. Overshoot bounded by
500ms cap.
3	clearTransactionContextOnError(e) call removed	False positive	@stIncMale confirmed: commitTransaction calls it internally; the outer call was redundant.
4	Error wrapping obscures original exception type	Valid, intentional	Spec-mandated (DRIVERS-3391). Labels are now copied from cause to wrapper. Tests verify.
5	Visibility widening of CommandOperationHelper + constants	False positive	Everything under com.mongodb.internal is internal by definition. Enables cross-package dedup.
6	@VisibleForTesting on timeoutOrAlternative	Resolved	@stIncMale requested removal; addressed in cherry-picked refactor (60acf51d).
7	TRANSACTION_MAX_MS package-private; hardcoded expected values in test	Minor nit	Iteration bounds now based on EXPECTED_BACKOFFS_MAX_VALUES.length (adopted). Hardcoded array is an
independent oracle — acceptable.
8	TODO comments in production code	Valid, accepted	Will be resolved before backpressure → main merge. Blocked on docs PR.
9	testRetryBackoffIsEnforced wall-clock timing sensitivity	Valid, mitigated	Jitter controlled via setTestJitterSupplier. 500ms tolerance. Spec-mandated prose test.
10	Deleted copyTimeoutContext() — verify no other callers	False positive	Explicitly requested by @stIncMale. Private constructor also removed as dead code.

Summary: 4 false positives, 2 resolved, 1 valid+intentional, 1 tracked, 1 accepted, 1 minor nit.

---

Additional Findings from PR Reviewers (not caught in diff-only review)

#	Finding	Source	Status
A	calculateTransactionBackoffMs Javadoc said 0-based but implementation is 1-based	Copilot, @stIncMale	Fixed
B	Error labels not copied from wrapped cause to MongoTimeoutException	@stIncMale	Fixed (d4bc4c70)
C	applyMajorityWriteConcernToTransactionOptions called on outer retry	@stIncMale	Fixed (60acf51d)
D	withTransaction code structure doesn't follow spec algorithm ordering	@stIncMale	Fixed (60acf51d)
E	Spec submodule not updated to latest spec tests	@stIncMale	Deferred — main updated separately
F	AI-generated comments cluttering test code	@stIncMale	Fixed
G	MongoTimeoutException message inconsistency (missing period)	Copilot	Fixed
H	timeoutOrAlternative removal + timeoutMsConfigured renaming	@stIncMale	Fixed (60acf51d)

---

Remaining Issues to Address

#	Issue	Severity	File(s)	Status	Tracking
1	testJitterSupplier should be volatile — mutable static read/written across threads without memory visibility guarantee	Low (test-only)	ExponentialBackoff.java	Open — deferred	JAVA-6079

|
| 2 | Spec "Note 1" about error propagation needs rework — spec language around propagation/raising is inconsistent | Medium | Spec-side | Open — spec change needed | DRIVERS-3436 |
| 3 | TODO-BACKPRESSURE comments in production code — must be resolved before merging backpressure → main | Low | MongoException.java, ExponentialBackoff.java | Open — blocked on docs PR
(10gen/docs-mongodb-internal#17281) | Implicit |
| 4 | Spec submodule not pointing to latest spec tests — new transactions-convenient-api JSON tests not included | Medium | testing/resources/specifications (submodule) | Open — main updated
(55e1861) but not merged into backpressure | TODO-BACKPRESSURE |
| 5 | Verify spec test withTransaction surfaces a timeout after exhausting transient transaction retries is run | Medium | Test runner config | Open — reminder in PR comments | — |
| 6 | Verify prose tests assert all error labels are copied to wrapping exception | Medium | WithTransactionProseTest.java | Partially addressed — labels copied in code, test coverage completeness not
confirmed | — |
| 7 | OTel tracing terminology inconsistency (finalize vs finish vs stop) | Low (orthogonal) | ClientSessionImpl.java tracing code | Open — no ticket yet | — |

Priority Summary

• Must resolve before merge to backpressure: Items 5, 6
• Must resolve before merge to main: Items 3 (TODOs), 4 (submodule)
• Tracked for future work: Items 1 (JAVA-6079), 2 (DRIVERS-3436), 7

---

What Looks Good

• Exponential backoff formula (base=5ms, growth=1.5x, cap=500ms) with jitter is well-designed for transaction retries
• Replacing ClientSessionClock singleton with SystemNanoTime + Mockito is a significant test infrastructure improvement
• ExponentialBackoffTest has good coverage of boundary conditions (jitter=0, jitter=1, cap enforcement)
• backpressure: true handshake flag is a clean protocol extension
• Error label propagation through timeout wrapping preserves diagnostic information
• abortIfInTransaction() extraction reduces duplication and improves clarity
• @stIncMale's refactor of withTransaction (60acf51d) now aligns the code with the spec algorithm, making correctness easier to verify
• New prose tests (testRetryBackoffIsEnforced, testExponentialBackoffOnTransientError) provide functional validation of backoff behavior

---

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated 3 comments.

---

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

[Copilot]

Pull request overview

Copilot reviewed 21 out of 21 changed files in this pull request and generated no new comments.

---

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

[stIncMale]

I updated the PR description with the information about DRIVERS-3436 and the JAVA-6160 which the former split into.