Summary

The withTransaction specification permits drivers to return the value of the callback if they choose. We should further clarify that if they do the value should be the result of the last invocation of the callback in the case of retryable errors where the callback will be invoked multiple times.

Motivation

Who is the affected end user?

• Drivers implementing a convenient transaction api
• Users making use of the return value from withTransaction

How does this affect the end user?

• If drivers have to correct returning an unexpected value it may be a breaking change

How likely is it that this problem or use case will occur?

• Dependent on withTransaction usage. Returning a value from the callback can often be an indicator of outcome or a channel to communicate results like insertedIds.

If the problem does occur, what are the consequences and how severe are they?

• If the return value changes based on the number of retries then its inconsistent and hard to write robust code around.

Is this issue urgent?

No.

Is this ticket required by a downstream team?

No.

Is this ticket only for tests?

No.

Acceptance Criteria

• Expand the section ClientSession.withTransaction to further describe how the result of the callback should be handled
  • It should be the result of the last invocation of the callback
  • If the transaction is aborted manually (per step 7 of Sequence of Actions) the result should still be the return value of the callback