CDRIVER-2558 add mongoc_error_has_labels

Author: ajdavis

NEWS

@@ -1,6 +1,9 @@
 Next Release
 ============
 
+  * New function mongoc_error_has_label to check for specific error labels such
+    as "TransientTransactionError" or "UnknownTransactionCommitResult" in
+    error replies.
   * All "destroy" functions such as bson_destroy or mongoc_collection_destroy
     now ignore a NULL argument.
   * Update functions include a new "upsertedCount" field in the reply document.

src/libmongoc/CMakeLists.txt

@@ -401,6 +401,7 @@ set (SOURCES ${SOURCES}
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-cursor-legacy.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-cursor-array.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-database.c
+   ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-error.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-find-and-modify.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-init.c
    ${PROJECT_SOURCE_DIR}/src/mongoc/mongoc-gridfs.c

src/libmongoc/doc/errors.rst

@@ -82,6 +82,33 @@ See also: :doc:`Handling Errors in libbson <bson:errors>`.
 | ``MONGOC_ERROR_TRANSACTION``      | ``MONGOC_ERROR_TRANSACTION_INVALID``                                                                                            | You attempted to start a transaction when one is already in progress, or commit or abort when there is no transaction.                                                                                                                                                                                                                     |
 +-----------------------------------+---------------------------------------------------------------------------------------------------------------------------------+--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------+
 
+.. _error_labels:
+
+Error Labels
+------------
+
+In some cases your application must make decisions based on what category of error the driver has returned, but these categories do not correspond perfectly to an error domain or code. In such cases, error *labels* provide a reliable way to determine how your application should respond to an error.
+
+Any C Driver function that has a :symbol:`bson:bson_t` out-parameter named ``reply`` may include error labels to the reply, in the form of a BSON field named "errorLabels" containing an array of strings:
+
+.. code-block:: none
+
+  { "errorLabels": [ "TransientTransactionError" ] }
+
+Use :symbol:`mongoc_error_has_label` to test if a reply contains a specific label. See :symbol:`mongoc_client_session_start_transaction` for example code that demonstrates the use of error labels in application logic.
+
+The following error labels are currently defined. Future versions of MongoDB may introduce new labels.
+
+TransientTransactionError
+^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Within a multi-document transaction, certain errors can leave the transaction in an unknown or aborted state. These include write conflicts, primary stepdowns, and network errors. In response, the application should abort the transaction and try the same sequence of operations again in a new transaction.
+
+UnknownTransactionCommitResult
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+When :symbol:`mongoc_client_session_commit_transaction` encounters a network error or certain server errors, it is not known whether the transaction was committed. Applications should attempt to commit the transaction again until: the commit succeeds, the commit fails with an error *not* labeled "UnknownTransactionCommitResult", or the application chooses to give up.
+
 .. _errors_error_api_version:
 .. _error_api_version:
 
@@ -127,3 +154,13 @@ See Also
 
 `MongoDB Server Error Codes <https://github.com/mongodb/mongo/blob/master/src/mongo/base/error_codes.err>`_
 
+.. only:: html
+
+  Functions
+  ---------
+
+  .. toctree::
+    :titlesonly:
+    :maxdepth: 1
+
+    mongoc_error_has_label

src/libmongoc/doc/mongoc_client_session_start_transaction.rst

@@ -35,6 +35,8 @@ Returns true if the transaction was started. Returns ``false`` and sets ``error`
 Example
 -------
 
+The following example demonstrates how to use :ref:`error labels <error_labels>` to reliably execute a multi-document transaction despite network errors and other transient failures.
+
 .. literalinclude:: ../examples/example-transaction.c
    :language: c
    :caption: example-transaction.c

src/libmongoc/doc/mongoc_error_has_label.rst

@@ -0,0 +1,25 @@
+:man_page: mongoc_error_has_label
+
+mongoc_error_has_label()
+========================
+
+Synopsis
+--------
+
+.. code-block:: c
+
+  bool
+  mongoc_error_has_label (const bson_t *reply, const char *label);
+
+Test whether a reply from a failed operation includes a specific error label. See :ref:`Error Labels <error_labels>` for details, and see :symbol:`mongoc_client_session_start_transaction` for example code that demonstrates their use.
+
+Parameters
+----------
+
+* ``reply``: A :symbol:`bson:bson_t`, the reply to a failed operation.
+* ``label``: The label to test for, such as "TransientTransactionError" or "UnknownTransactionCommitResult".
+
+Returns
+-------
+
+Returns true if ``reply`` contains the error label.

src/libmongoc/examples/example-transaction.c

@@ -7,10 +7,6 @@
 #include <mongoc.h>
 
 
-/* defined below */
-static bool
-has_label (const bson_t *reply, const char *label);
-
 int
 main (int argc, char *argv[])
 {
@@ -123,9 +119,12 @@ main (int argc, char *argv[])
       if (!r) {
          MONGOC_ERROR ("Insert failed: %s", error.message);
          mongoc_client_session_abort_transaction (session, NULL);
-         if (has_label (&reply, "TransientTransactionError")) {
-            /* network error, primary failover, or other temporary error.
-             * trying the entire transaction from the start may succeed */
+
+         /* a network error, primary failover, or other temporary error in a
+          * transaction includes {"errorLabels": ["TransientTransactionError"]},
+          * meaning that trying the entire transaction again may succeed
+          */
+         if (mongoc_error_has_label (&reply, "TransientTransactionError")) {
             goto retry_transaction;
          }
 
@@ -147,10 +146,11 @@ main (int argc, char *argv[])
          break;
       } else {
          MONGOC_ERROR ("Warning: commit failed: %s", error.message);
-         if (has_label (&reply, "TransientTransactionError")) {
+         if (mongoc_error_has_label (&reply, "TransientTransactionError")) {
             mongoc_client_session_abort_transaction (session, NULL);
             goto retry_transaction;
-         } else if (has_label (&reply, "UnknownTransactionCommitResult")) {
+         } else if (mongoc_error_has_label (&reply,
+                                            "UnknownTransactionCommitResult")) {
             /* try again to commit */
             continue;
          }
@@ -179,30 +179,3 @@ main (int argc, char *argv[])
 
    return exit_code;
 }
-
-
-/* An error reply from mongoc_client_session_commit_transaction can include:
- *
- * { "errorLabels" : ["TransientTxnError"] }
- *
- * Return true if the reply contains the given label.
- */
-static bool
-has_label (const bson_t *reply, const char *label)
-{
-   bson_iter_t iter;
-   bson_iter_t labels;
-
-   if (!bson_iter_init_find (&iter, reply, "errorLabels")) {
-      return false;
-   }
-
-   bson_iter_recurse (&iter, &labels);
-   while (bson_iter_next (&labels)) {
-      if (!strcmp (bson_iter_utf8 (&labels, NULL), label)) {
-         return true;
-      }
-   }
-
-   return false;
-}

src/libmongoc/src/mongoc/CMakeLists.txt

@@ -174,6 +174,7 @@ set (src_libmongoc_src_mongoc_DIST_cs
    mongoc-cursor-cmd.c
    mongoc-cursor-cmd-deprecated.c
    mongoc-database.c
+   mongoc-error.c
    mongoc-find-and-modify.c
    mongoc-host-list.c
    mongoc-init.c

src/libmongoc/src/mongoc/mongoc-error.c

@@ -0,0 +1,41 @@
+/*
+ * Copyright 2018-present MongoDB, Inc.
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <bson.h>
+
+#include "mongoc-error.h"
+
+bool
+mongoc_error_has_label (const bson_t *reply, const char *label)
+{
+   bson_iter_t iter;
+   bson_iter_t error_labels;
+
+   BSON_ASSERT (reply);
+   BSON_ASSERT (label);
+
+   if (bson_iter_init_find (&iter, reply, "errorLabels")) {
+      bson_iter_recurse (&iter, &error_labels);
+      while (bson_iter_next (&error_labels)) {
+         if (BSON_ITER_HOLDS_UTF8 (&error_labels) &&
+             !strcmp (bson_iter_utf8 (&error_labels, NULL), label)) {
+            return true;
+         }
+      }
+   }
+
+   return false;
+}

src/libmongoc/src/mongoc/mongoc-error.h

@@ -23,6 +23,8 @@
 
 #include <bson.h>
 
+#include "mongoc-macros.h"
+
 #define MONGOC_ERROR_API_VERSION_LEGACY 1
 #define MONGOC_ERROR_API_VERSION_2 2
 
@@ -115,6 +117,8 @@ typedef enum {
    MONGOC_ERROR_TRANSACTION_INVALID_STATE,
 } mongoc_error_code_t;
 
+MONGOC_EXPORT (bool)
+mongoc_error_has_label (const bson_t *reply, const char *label);
 
 BSON_END_DECLS
 

src/libmongoc/src/mongoc/mongoc-util-private.h

@@ -124,9 +124,6 @@ mongoc_lowercase (const char *src, char *buf /* OUT */);
 bool
 mongoc_parse_port (uint16_t *port, const char *str);
 
-bool
-_mongoc_bson_array_has_label (bson_t *bson, const char *label);
-
 void
 _mongoc_bson_array_add_label (bson_t *bson, const char *label);