DRIVERS-2584 Errors handling in Convenient Transactions API (#1475)

Co-authored-by: Andreas Braun <[email protected]>
Co-authored-by: Jeremy Mikola <[email protected]>

source/transactions-convenient-api/transactions-convenient-api.rst

@@ -299,6 +299,25 @@ MongoClient within the callback in order to execute operations within the
 transaction. Per the `Driver Session`_ specification, ClientSessions should
 already provide access to a client object.
 
+Handling errors inside the callback
+-----------------------------------
+
+Drivers MUST document that the callback MUST NOT silently handle command errors
+without allowing such errors to propagate. Command errors may abort the transaction
+on the server, and an attempt to commit the transaction will be rejected with
+``NoSuchTransaction`` error.
+
+For example, ``DuplicateKeyError`` is an error that aborts a transaction on the
+server. If the callback catches ``DuplicateKeyError`` and does not re-throw it,
+the driver will attempt to commit the transaction. The server will reject the
+commit attempt with ``NoSuchTransaction`` error. This error has the
+"TransientTransactionError" label and the driver will retry the commit. This
+will result in an infinite loop.
+
+Drivers MUST recommend that the callback re-throw command errors if they
+need to be handled inside the callback. Drivers SHOULD also recommend using
+Core Transaction API if a user wants to handle errors in a custom way.
+
 Test Plan
 =========
 
@@ -494,6 +513,7 @@ client-side operation timeout, withTransaction can continue to use the
 Changes
 =======
 
+:2023-11-22: Document error handling inside the callback.
 :2022-10-05: Remove spec front matter and reformat changelog.
 :2022-01-19: withTransaction applies timeouts per the client-side operations
              timeout specification.

source/transactions/transactions.rst

@@ -982,6 +982,13 @@ label. For example:
                 continue
             raise
 
+Handling command errors
+-----------------------
+
+Drivers MUST document that command errors inside a transaction may abort
+the transaction on the server. An attempt to commit such transaction will be
+rejected with ``NoSuchTransaction`` error.
+
 **Test Plan**
 -------------
 
@@ -1407,6 +1414,8 @@ durable, which achieves the primary objective of avoiding duplicate commits.
 **Changelog**
 -------------
 
+:2023-11-22: Specify that non-transient transaction errors abort the transaction
+             on the server.
 :2022-10-05: Remove spec front matter and reformat changelog
 :2022-01-25: Mention the additional case of a retryable handshake error
 :2022-01-19: Deprecate maxCommitTimeMS in favor of timeoutMS.