From 13117d601fb6ea177e485880175b5be1651a7e46 Mon Sep 17 00:00:00 2001 From: Dmitry Rybakov Date: Tue, 5 Dec 2023 09:18:46 +0100 Subject: [PATCH] DRIVERS-2584 Errors handling in Convenient Transactions API (#1475) Co-authored-by: Andreas Braun Co-authored-by: Jeremy Mikola --- .../transactions-convenient-api.rst | 20 +++++++++++++++++++ source/transactions/transactions.rst | 9 +++++++++ 2 files changed, 29 insertions(+) diff --git a/source/transactions-convenient-api/transactions-convenient-api.rst b/source/transactions-convenient-api/transactions-convenient-api.rst index aac87bc37c..5fe349a896 100644 --- a/source/transactions-convenient-api/transactions-convenient-api.rst +++ b/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. diff --git a/source/transactions/transactions.rst b/source/transactions/transactions.rst index 7a576c2c01..d32763ae01 100644 --- a/source/transactions/transactions.rst +++ b/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.