couchbase 3.4.2 → 3.4.3

data/ext/couchbase/test/test_integration_read_replica.cxx

@@ -63,8 +63,13 @@ TEST_CASE("integration: get any replica", "[integration]")
 {
     test::utils::integration_test_guard integration;
 
-    if (integration.number_of_replicas() == 0 && integration.number_of_nodes() <= integration.number_of_replicas()) {
-        return;
+    if (integration.number_of_replicas() == 0) {
+        SKIP("bucket has zero replicas");
+    }
+    if (integration.number_of_nodes() <= integration.number_of_replicas()) {
+        SKIP(fmt::format("number of nodes ({}) is less or equal to number of replicas ({})",
+                         integration.number_of_nodes(),
+                         integration.number_of_replicas()));
     }
 
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
@@ -95,8 +100,12 @@ TEST_CASE("integration: get all replicas", "[integration]")
     test::utils::integration_test_guard integration;
 
     auto number_of_replicas = integration.number_of_replicas();
-    if (number_of_replicas == 0 && integration.number_of_nodes() <= number_of_replicas) {
-        return;
+    if (number_of_replicas == 0) {
+        SKIP("bucket has zero replicas");
+    }
+    if (integration.number_of_nodes() <= number_of_replicas) {
+        SKIP(fmt::format(
+          "number of nodes ({}) is less or equal to number of replicas ({})", integration.number_of_nodes(), number_of_replicas));
     }
 
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
@@ -109,10 +118,16 @@ TEST_CASE("integration: get all replicas", "[integration]")
         couchbase::core::document_id id{ integration.ctx.bucket, scope_name, collection_name, key };
 
         couchbase::core::operations::insert_request req{ id, basic_doc_json };
+        req.durability_level = couchbase::durability_level::majority_and_persist_to_active;
         auto resp = test::utils::execute(integration.cluster, req);
         REQUIRE_SUCCESS(resp.ctx.ec());
     }
 
+    if (integration.cluster_version().is_mock()) {
+        // GOCAVES does not implement syncDurability. See https://github.com/couchbaselabs/gocaves/issues/109
+        std::this_thread::sleep_for(std::chrono::seconds{ 1 });
+    }
+
     {
         auto collection =
           couchbase::cluster(integration.cluster).bucket(integration.ctx.bucket).scope(scope_name).collection(collection_name);
@@ -128,8 +143,13 @@ TEST_CASE("integration: get all replicas with missing key", "[integration]")
 {
     test::utils::integration_test_guard integration;
 
-    if (integration.number_of_replicas() == 0 && integration.number_of_nodes() <= integration.number_of_replicas()) {
-        return;
+    if (integration.number_of_replicas() == 0) {
+        SKIP("bucket has zero replicas");
+    }
+    if (integration.number_of_nodes() <= integration.number_of_replicas()) {
+        SKIP(fmt::format("number of nodes ({}) is less or equal to number of replicas ({})",
+                         integration.number_of_nodes(),
+                         integration.number_of_replicas()));
     }
 
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
@@ -152,7 +172,9 @@ TEST_CASE("integration: get any replica with missing key", "[integration]")
     test::utils::integration_test_guard integration;
 
     if (integration.number_of_nodes() <= integration.number_of_replicas()) {
-        return;
+        SKIP(fmt::format("number of nodes ({}) is less or equal to number of replicas ({})",
+                         integration.number_of_nodes(),
+                         integration.number_of_replicas()));
     }
 
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
@@ -173,8 +195,13 @@ TEST_CASE("integration: get any replica low-level version", "[integration]")
 {
     test::utils::integration_test_guard integration;
 
-    if (integration.number_of_replicas() == 0 && integration.number_of_nodes() <= integration.number_of_replicas()) {
-        return;
+    if (integration.number_of_replicas() == 0) {
+        SKIP("bucket has zero replicas");
+    }
+    if (integration.number_of_nodes() <= integration.number_of_replicas()) {
+        SKIP(fmt::format("number of nodes ({}) is less or equal to number of replicas ({})",
+                         integration.number_of_nodes(),
+                         integration.number_of_replicas()));
     }
 
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
@@ -204,8 +231,12 @@ TEST_CASE("integration: get all replicas low-level version", "[integration]")
     test::utils::integration_test_guard integration;
 
     auto number_of_replicas = integration.number_of_replicas();
-    if (number_of_replicas == 0 && integration.number_of_nodes() <= integration.number_of_replicas()) {
-        return;
+    if (number_of_replicas == 0) {
+        SKIP("bucket has zero replicas");
+    }
+    if (integration.number_of_nodes() <= number_of_replicas) {
+        SKIP(fmt::format(
+          "number of nodes ({}) is less or equal to number of replicas ({})", integration.number_of_nodes(), number_of_replicas));
     }
 
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
@@ -217,10 +248,16 @@ TEST_CASE("integration: get all replicas low-level version", "[integration]")
             { "b", 2.0 },
         };
         couchbase::core::operations::upsert_request req{ id, couchbase::core::utils::json::generate_binary(value) };
+        req.durability_level = couchbase::durability_level::majority_and_persist_to_active;
         auto resp = test::utils::execute(integration.cluster, req);
         REQUIRE_SUCCESS(resp.ctx.ec());
     }
 
+    if (integration.cluster_version().is_mock()) {
+        // GOCAVES does not implement syncDurability. See https://github.com/couchbaselabs/gocaves/issues/109
+        std::this_thread::sleep_for(std::chrono::seconds{ 1 });
+    }
+
     {
         couchbase::core::operations::get_all_replicas_request req{ id };
         auto resp = test::utils::execute(integration.cluster, req);

data/ext/couchbase/test/test_integration_search.cxx

@@ -17,16 +17,24 @@
 
 #include "test_helper_integration.hxx"
 
+#include <catch2/matchers/catch_matchers_string.hpp>
+
 #include "core/operations/management/collection_create.hxx"
 #include "core/operations/management/search_index_drop.hxx"
 #include "core/operations/management/search_index_upsert.hxx"
 
+#include <couchbase/query_string_query.hxx>
+
 using Catch::Matchers::StartsWith;
 
 TEST_CASE("integration: search query")
 {
     test::utils::integration_test_guard integration;
 
+    if (!integration.cluster_version().supports_search()) {
+        SKIP("cluster does not support search");
+    }
+
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
 
     {
@@ -348,6 +356,14 @@ TEST_CASE("integration: search query consistency", "[integration]")
 {
     test::utils::integration_test_guard integration;
 
+    if (integration.ctx.deployment == test::utils::deployment_type::elixir) {
+        SKIP("elixir deployment is incompatible with parts of this test");
+    }
+
+    if (!integration.cluster_version().supports_search()) {
+        SKIP("cluster does not support search");
+    }
+
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
 
     const std::string params =
@@ -441,7 +457,7 @@ TEST_CASE("integration: search query consistency", "[integration]")
                 CB_LOG_INFO("ignore consistency_mismatch: {}", resp.ctx.http_body);
                 continue;
             }
-            INFO(resp.ctx.http_body)
+            INFO(resp.ctx.http_body);
             REQUIRE_SUCCESS(resp.ctx.ec);
             switch (resp.rows.size()) {
                 case 1:
@@ -474,8 +490,12 @@ TEST_CASE("integration: search query collections")
 {
     test::utils::integration_test_guard integration;
 
+    if (!integration.cluster_version().supports_search()) {
+        SKIP("cluster does not support search");
+    }
+
     if (!integration.cluster_version().supports_collections()) {
-        return;
+        SKIP("cluster does not support collections");
     }
 
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);

data/ext/couchbase/test/test_integration_subdoc.cxx

@@ -30,7 +30,7 @@ assert_single_lookup_success(test::utils::integration_test_guard& integration,
     couchbase::core::operations::lookup_in_request req{ id };
     req.specs = couchbase::lookup_in_specs{ spec }.specs();
     auto resp = test::utils::execute(integration.cluster, req);
-    INFO(fmt::format("assert_single_lookup_success(\"{}\", \"{}\")", id, req.specs[0].path_))
+    INFO(fmt::format("assert_single_lookup_success(\"{}\", \"{}\")", id, req.specs[0].path_));
     REQUIRE_SUCCESS(resp.ctx.ec());
     REQUIRE_FALSE(resp.cas.empty());
     REQUIRE(resp.fields.size() == 1);
@@ -54,7 +54,7 @@ assert_single_lookup_error(test::utils::integration_test_guard& integration,
     couchbase::core::operations::lookup_in_request req{ id };
     req.specs = couchbase::lookup_in_specs{ spec }.specs();
     auto resp = test::utils::execute(integration.cluster, req);
-    INFO(fmt::format("assert_single_lookup_error(\"{}\", \"{}\")", id, req.specs[0].path_))
+    INFO(fmt::format("assert_single_lookup_error(\"{}\", \"{}\")", id, req.specs[0].path_));
     REQUIRE_SUCCESS(resp.ctx.ec());
     REQUIRE_FALSE(resp.cas.empty());
     REQUIRE(resp.fields.size() == 1);
@@ -197,6 +197,10 @@ TEST_CASE("integration: subdoc get & exists", "[integration]")
 
         SECTION("non json get")
         {
+            if (integration.cluster_version().is_mock()) {
+                SKIP("GOCAVES does not handle subdocument operations for non-JSON documents. See "
+                     "https://github.com/couchbaselabs/gocaves/issues/103");
+            }
             assert_single_lookup_error(integration,
                                        non_json_id,
                                        couchbase::lookup_in_specs::get("non-exist"),
@@ -206,6 +210,10 @@ TEST_CASE("integration: subdoc get & exists", "[integration]")
 
         SECTION("non json exists")
         {
+            if (integration.cluster_version().is_mock()) {
+                SKIP("GOCAVES does not handle subdocument operations for non-JSON documents. See "
+                     "https://github.com/couchbaselabs/gocaves/issues/103");
+            }
             assert_single_lookup_error(integration,
                                        non_json_id,
                                        couchbase::lookup_in_specs::exists("non-exist"),
@@ -218,11 +226,19 @@ TEST_CASE("integration: subdoc get & exists", "[integration]")
     {
         std::vector<std::string> invalid_paths = { "invalid..path", "invalid[-2]" };
         for (const auto& path : invalid_paths) {
-            assert_single_lookup_error(integration,
-                                       id,
-                                       couchbase::lookup_in_specs::get(path),
-                                       couchbase::key_value_status_code::subdoc_path_invalid,
-                                       couchbase::errc::key_value::path_invalid);
+            if (integration.cluster_version().is_mock()) {
+                assert_single_lookup_error(integration,
+                                           id,
+                                           couchbase::lookup_in_specs::get(path),
+                                           couchbase::key_value_status_code::subdoc_path_not_found,
+                                           couchbase::errc::key_value::path_not_found);
+            } else {
+                assert_single_lookup_error(integration,
+                                           id,
+                                           couchbase::lookup_in_specs::get(path),
+                                           couchbase::key_value_status_code::subdoc_path_invalid,
+                                           couchbase::errc::key_value::path_invalid);
+            }
         }
     }
 
@@ -317,6 +333,10 @@ TEST_CASE("integration: subdoc store", "[integration]")
 
     SECTION("non json")
     {
+        if (integration.cluster_version().is_mock()) {
+            SKIP("GOCAVES does not handle subdocument operations for non-JSON documents. See "
+                 "https://github.com/couchbaselabs/gocaves/issues/103");
+        }
         std::string path{ "dict" };
         auto value = couchbase::core::utils::to_binary("non-json");
         couchbase::core::operations::mutate_in_request req{ id };
@@ -411,6 +431,11 @@ TEST_CASE("integration: subdoc mutate in store semantics", "[integration]")
 TEST_CASE("integration: subdoc unique", "[integration]")
 {
     test::utils::integration_test_guard integration;
+
+    if (integration.cluster_version().is_mock()) {
+        SKIP("GOCAVES does not support subdocument create_path feature. See https://github.com/couchbaselabs/gocaves/issues/17");
+    }
+
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
     couchbase::core::document_id id{ integration.ctx.bucket, "_default", "_default", test::utils::uniq_id("subdoc") };
 
@@ -453,7 +478,6 @@ TEST_CASE("integration: subdoc unique", "[integration]")
           couchbase::mutate_in_specs{ couchbase::mutate_in_specs::array_append("a", tao::json::empty_object).create_path() }.specs();
         auto resp = test::utils::execute(integration.cluster, req);
         assert_single_mutate_success(resp, "a");
-        assert_single_lookup_success(integration, id, couchbase::lookup_in_specs::get("a[-1]"), "{}");
     }
 
     {
@@ -472,7 +496,10 @@ TEST_CASE("integration: subdoc counter", "[integration]")
     couchbase::core::document_id id{ integration.ctx.bucket, "_default", "_default", test::utils::uniq_id("subdoc") };
 
     {
-        auto value_json = couchbase::core::utils::to_binary(R"({"dictkey":"dictval","array":[1,2,3,4,[10,20,30,[100,200,300]]]})");
+        auto value_json =
+          integration.cluster_version().is_mock() // kv_engine creates counters automatically
+            ? couchbase::core::utils::to_binary(R"({"dictkey":"dictval","array":[1,2,3,4,[10,20,30,[100,200,300]]],"counter":0})")
+            : couchbase::core::utils::to_binary(R"({"dictkey":"dictval","array":[1,2,3,4,[10,20,30,[100,200,300]]]})");
         couchbase::core::operations::insert_request req{ id, value_json };
         auto resp = test::utils::execute(integration.cluster, req);
         REQUIRE_SUCCESS(resp.ctx.ec());
@@ -497,6 +524,9 @@ TEST_CASE("integration: subdoc counter", "[integration]")
 
     SECTION("max value")
     {
+        if (integration.cluster_version().is_mock()) {
+            SKIP("GOCAVES incorrectly handles limits for subdoc counters. See https://github.com/couchbaselabs/gocaves/issues/104");
+        }
         {
             int64_t max_value = std::numeric_limits<int64_t>::max();
             couchbase::core::operations::mutate_in_request req{ id };
@@ -516,6 +546,9 @@ TEST_CASE("integration: subdoc counter", "[integration]")
 
     SECTION("invalid delta")
     {
+        if (integration.cluster_version().is_mock()) {
+            SKIP("GOCAVES incorrectly handles zero delta for subdoc counters. See https://github.com/couchbaselabs/gocaves/issues/105");
+        }
         couchbase::core::operations::mutate_in_request req{ id };
         req.specs = couchbase::mutate_in_specs{ couchbase::mutate_in_specs::increment("counter", 0) }.specs();
         auto resp = test::utils::execute(integration.cluster, req);
@@ -525,6 +558,9 @@ TEST_CASE("integration: subdoc counter", "[integration]")
 
     SECTION("increase number already too big")
     {
+        if (integration.cluster_version().is_mock()) {
+            SKIP("GOCAVES incorrectly handles big values for subdoc counters. See https://github.com/couchbaselabs/gocaves/issues/106");
+        }
         {
             auto big_value = R"({"counter":)" + std::to_string(std::numeric_limits<int64_t>::max()) + "999999999999999999999999999999}";
             auto value_json = couchbase::core::utils::to_binary(big_value);
@@ -621,7 +657,11 @@ TEST_CASE("integration: subdoc multi lookup", "[integration]")
           }
             .specs();
         auto resp = test::utils::execute(integration.cluster, req);
-        REQUIRE(resp.ctx.ec() == couchbase::errc::common::invalid_argument);
+        if (integration.cluster_version().is_mock()) {
+            REQUIRE(resp.ctx.ec() == couchbase::errc::common::unsupported_operation);
+        } else {
+            REQUIRE(resp.ctx.ec() == couchbase::errc::common::invalid_argument);
+        }
     }
 
     SECTION("missing key")
@@ -647,7 +687,10 @@ TEST_CASE("integration: subdoc multi mutation", "[integration]")
     couchbase::core::document_id id{ integration.ctx.bucket, "_default", "_default", test::utils::uniq_id("subdoc") };
 
     {
-        auto value_json = couchbase::core::utils::to_binary(R"({"dictkey":"dictval","array":[1,2,3,4,[10,20,30,[100,200,300]]]})");
+        auto value_json =
+          integration.cluster_version().is_mock() // kv_engine creates counters automatically
+            ? couchbase::core::utils::to_binary(R"({"dictkey":"dictval","array":[1,2,3,4,[10,20,30,[100,200,300]]],"counter":0})")
+            : couchbase::core::utils::to_binary(R"({"dictkey":"dictval","array":[1,2,3,4,[10,20,30,[100,200,300]]]})");
         couchbase::core::operations::insert_request req{ id, value_json };
         auto resp = test::utils::execute(integration.cluster, req);
         REQUIRE_SUCCESS(resp.ctx.ec());
@@ -676,6 +719,9 @@ TEST_CASE("integration: subdoc multi mutation", "[integration]")
 
     SECTION("replace with errors")
     {
+        if (integration.cluster_version().is_mock()) {
+            SKIP("GOCAVES incorrectly uses error indexes for subdoc mutations. See https://github.com/couchbaselabs/gocaves/issues/107");
+        }
         couchbase::core::operations::mutate_in_request req{ id };
         req.specs =
           couchbase::mutate_in_specs{
@@ -695,6 +741,11 @@ TEST_CASE("integration: subdoc multi mutation", "[integration]")
 TEST_CASE("integration: subdoc expiry")
 {
     test::utils::integration_test_guard integration;
+
+    if (integration.cluster_version().is_mock()) {
+        SKIP("GOCAVES does not support subdoc mutations with expiry. See https://github.com/couchbaselabs/gocaves/issues/85");
+    }
+
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
     couchbase::core::document_id id{ integration.ctx.bucket, "_default", "_default", test::utils::uniq_id("subdoc") };
 

data/ext/couchbase/test/test_integration_tracer.cxx

@@ -17,6 +17,8 @@
 
 #include "test_helper_integration.hxx"
 
+#include <catch2/generators/catch_generators.hpp>
+
 #include "core/platform/uuid.h"
 
 #include <couchbase/lookup_in_specs.hxx>
@@ -247,6 +249,9 @@ TEST_CASE("integration: enable external tracer", "[integration]")
     {
         SECTION("query")
         {
+            if (!guard.cluster_version().supports_query()) {
+                SKIP("cluster does not support query");
+            }
             tracer->reset();
             couchbase::core::operations::query_request req{ R"(SELECT "ruby rules" AS greeting)" };
             req.parent_span = parent_span;

data/ext/couchbase/test/test_integration_transcoders.cxx

@@ -17,6 +17,10 @@
 
 #include "test_helper_integration.hxx"
 
+#include <catch2/matchers/catch_matchers.hpp>
+#include <catch2/matchers/catch_matchers_exception.hpp>
+#include <catch2/matchers/catch_matchers_string.hpp>
+
 #include <couchbase/cluster.hxx>
 #include <couchbase/codec/raw_binary_transcoder.hxx>
 
@@ -24,7 +28,7 @@
 
 #include "profile.hxx"
 
-using Catch::Contains;
+using Catch::Matchers::ContainsSubstring;
 
 TEST_CASE("integration: upsert/get with json transcoder", "[integration]")
 {
@@ -427,6 +431,10 @@ TEST_CASE("integration: subdoc with public API", "[integration]")
 {
     test::utils::integration_test_guard integration;
 
+    if (integration.cluster_version().is_mock()) {
+        SKIP("GOCAVES incorrectly uses error indexes for subdoc mutations. See https://github.com/couchbaselabs/gocaves/issues/107");
+    }
+
     test::utils::open_bucket(integration.cluster, integration.ctx.bucket);
 
     auto collection = couchbase::cluster(integration.cluster)
@@ -497,10 +505,10 @@ TEST_CASE("integration: subdoc with public API", "[integration]")
         REQUIRE(ctx.first_error_path().has_value());
         REQUIRE(ctx.first_error_path() == "missing_field");
         REQUIRE(resp.cas().empty());
-        REQUIRE_THROWS_WITH(resp.has_value(0), Contains("path_invalid"));
-        REQUIRE_THROWS_WITH(resp.has_value("views"), Contains("path_invalid"));
-        REQUIRE_THROWS_WITH(resp.content_as<std::uint32_t>(0), Contains("path_invalid"));
-        REQUIRE_THROWS_WITH(resp.content_as<std::uint32_t>("views"), Contains("path_invalid"));
+        REQUIRE_THROWS_WITH(resp.has_value(0), ContainsSubstring("path_invalid"));
+        REQUIRE_THROWS_WITH(resp.has_value("views"), ContainsSubstring("path_invalid"));
+        REQUIRE_THROWS_WITH(resp.content_as<std::uint32_t>(0), ContainsSubstring("path_invalid"));
+        REQUIRE_THROWS_WITH(resp.content_as<std::uint32_t>("views"), ContainsSubstring("path_invalid"));
     }
 
     {

data/ext/couchbase/test/{test_transaction_transaction_context.cxx → test_transaction_context.cxx}

@@ -504,7 +504,7 @@ TEST_CASE("transactions: can see some query errors but no transactions failed",
         // eat the expected op_exception
     } catch (...) {
         auto e = std::current_exception();
-        std::cout << "got " << typeid(e).name() << std::endl;
+        INFO(fmt::format("got {}", typeid(e).name()));
         FAIL("expected op_exception to be thrown from the future");
     }
     REQUIRE_NOTHROW(tx.existing_error());

data/ext/couchbase/test/test_transaction_examples.cxx

@@ -0,0 +1,195 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2023-Present Couchbase, 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 "test_helper_integration.hxx"
+
+#include <couchbase/cluster.hxx>
+#include <couchbase/fmt/cas.hxx>
+#include <couchbase/transactions/attempt_context.hxx>
+
+#include <tao/json.hpp>
+
+namespace blocking_txn
+{
+//! [blocking-txn]
+#include <couchbase/cluster.hxx>
+#include <couchbase/fmt/cas.hxx>
+#include <couchbase/transactions/attempt_context.hxx>
+
+#include <tao/json.hpp>
+
+int
+main(int argc, const char* argv[])
+{
+    if (argc != 4) {
+        fmt::print("USAGE: ./blocking-txn couchbase://127.0.0.1 Administrator password\n");
+        return 1;
+    }
+
+    int retval = 0;
+
+    const std::string connection_string{ argv[1] };
+    const std::string username{ argv[2] };
+    const std::string password{ argv[3] };
+
+    // run IO context on separate thread
+    asio::io_context io;
+    auto guard = asio::make_work_guard(io);
+    std::thread io_thread([&io]() { io.run(); });
+
+    auto options = couchbase::cluster_options(username, password);
+    // customize through the 'options'.
+    // For example, optimize timeouts for WAN
+    options.apply_profile("wan_development");
+
+    // [1] connect to cluster using the given connection string and the options
+    auto [cluster, ec] = couchbase::cluster::connect(io, connection_string, options).get();
+    if (ec) {
+        fmt::print("unable to connect to the cluster: {}\n", ec.message());
+        return 1;
+    }
+
+    // [2] persist three documents to the default collection of bucket "default"
+    auto collection = cluster.bucket("default").default_collection();
+    constexpr auto id_1 = "my-doc_1";
+    constexpr auto id_2 = "my_doc_2";
+    constexpr auto id_3 = "my_doc_3";
+    const tao::json::value content = { { "some", "content" } };
+
+    for (const auto& id : { id_1, id_2, id_3 }) {
+        if (auto [ctx, res] = collection.upsert(id, content).get(); ctx.ec()) {
+            fmt::print(stderr, "upsert \"{}\" failed before starting transaction: {}\n", id, ctx.ec().message());
+            return 1;
+        }
+    }
+
+    { // [3] blocking transaction
+        //! [simple-blocking-txn]
+        auto [tx_err, tx_res] = cluster.transactions()->run(
+          // [3.1] closure argument to run() method encapsulates logic, that has to be run in transaction
+          [&](couchbase::transactions::attempt_context& ctx) {
+              // [3.2] get document
+              auto [err_ctx, doc] = ctx.get(collection, id_1);
+              if (err_ctx.ec()) {
+                  fmt::print(stderr, "failed to get document \"{}\": {}\n", id_1, err_ctx.ec().message());
+                  // [3.3] don't continue the transaction logic
+                  return;
+              }
+              // [3.4] replace document's content
+              ctx.replace(doc, ::tao::json::value{ { "some", "other content" } });
+          });
+        // [3.5] check the overall status of the transaction
+        if (tx_err.ec()) {
+            fmt::print(stderr, "error in transaction {}, cause: {}\n", tx_err.ec().message(), tx_err.cause().message());
+            retval = 1;
+        } else {
+            fmt::print("transaction {} completed successfully", tx_res.transaction_id);
+        }
+        //! [simple-blocking-txn]
+    }
+
+    { // [4] asynchronous transaction
+        //! [simple-async-txn]
+        // [4.1] create promise to retrieve result from the transaction
+        auto barrier = std::make_shared<std::promise<std::error_code>>();
+        auto f = barrier->get_future();
+        cluster.transactions()->run(
+          // [4.2] closure argument to run() method encapsulates logic, that has to be run in transaction
+          [&](couchbase::transactions::async_attempt_context& ctx) {
+              // [4.3] get document
+              ctx.get(collection, id_1, [&](auto err_ctx_1, auto doc) {
+                  if (err_ctx_1.ec()) {
+                      fmt::print(stderr, "failed to get document \"{}\": {}\n", id_1, err_ctx_1.ec().message());
+                      return;
+                  }
+                  // [4.4] replace document's content
+                  ctx.replace(doc, ::tao::json::value{ { "some", "other async content" } }, [&](auto err_ctx_2, auto res) {
+                      if (err_ctx_2.ec()) {
+                          fmt::print(stderr, "error replacing content in doc {}: {}\n", id_1, err_ctx_2.ec().message());
+                      } else {
+                          fmt::print("successfully replaced: {}, cas={}\n", id_1, res.cas());
+                      }
+                  });
+              });
+              ctx.get(collection, id_2, [&](auto err_ctx_1, auto doc) {
+                  if (err_ctx_1.ec()) {
+                      fmt::print("error getting doc {}: {}", id_2, err_ctx_1.ec().message());
+                      return;
+                  }
+                  ctx.replace(doc, ::tao::json::value{ { "some", "other async content" } }, [&](auto err_ctx_2, auto res) {
+                      if (err_ctx_2.ec()) {
+                          fmt::print(stderr, "error replacing content in doc {}: {}\n", id_2, err_ctx_2.ec().message());
+                      } else {
+                          fmt::print("successfully replaced: {}, cas={}\n", id_2, res.cas());
+                      }
+                  });
+              });
+              ctx.get(collection, id_3, [&](auto err_ctx_1, auto doc) {
+                  if (err_ctx_1.ec()) {
+                      fmt::print("error getting doc {}: {}", id_3, err_ctx_1.ec().message());
+                      return;
+                  }
+                  ctx.replace(doc, ::tao::json::value{ { "some", "other async content" } }, [&](auto err_ctx_2, auto res) {
+                      if (err_ctx_2.ec()) {
+                          fmt::print(stderr, "error replacing content in doc {}: {}\n", id_3, err_ctx_2.ec().message());
+                      } else {
+                          fmt::print("successfully replaced: {}, cas={}\n", id_3, res.cas());
+                      }
+                  });
+              });
+          },
+          // [4.5], second closure represents transaction completion logic
+          [barrier](auto tx_err, auto tx_res) {
+              if (tx_err.ec()) {
+                  fmt::print(stderr, "error in async transaction {}, {}\n", tx_res.transaction_id, tx_err.ec().message());
+              }
+              barrier->set_value(tx_err.ec());
+          });
+        if (auto async_err = f.get()) {
+            retval = 1;
+        }
+        //! [simple-async-txn]
+    }
+
+    // [5], close cluster connection
+    cluster.close();
+    guard.reset();
+
+    io_thread.join();
+    return retval;
+}
+
+//! [blocking-txn]
+} // namespace blocking_txn
+
+TEST_CASE("example: basic transaction", "[integration]")
+{
+    test::utils::integration_test_guard integration;
+    if (!integration.cluster_version().supports_collections()) {
+        SKIP("cluster does not support collections");
+    }
+
+    const auto env = test::utils::test_context::load_from_environment();
+    const char* argv[] = {
+        "blocking-txn", // name of the "executable"
+        env.connection_string.c_str(),
+        env.username.c_str(),
+        env.password.c_str(),
+    };
+
+    REQUIRE(blocking_txn::main(4, argv) == 0);
+}

data/ext/couchbase/test/{test_transaction_transaction_simple.cxx → test_transaction_simple.cxx}

@@ -14,15 +14,27 @@
  *   limitations under the License.
  */
 
-#include "../core/transactions/atr_ids.hxx"
-#include "simple_object.hxx"
 #include "test_helper_integration.hxx"
-#include <core/transactions.hxx>
-#include <tao/json.hpp>
+
+#include "simple_object.hxx"
+
+#include "core/transactions.hxx"
+#include "core/transactions/atr_ids.hxx"
 
 #include <spdlog/spdlog.h>
+#include <tao/json.hpp>
+
 #include <stdexcept>
 
+#if defined(__GNUC__)
+#if __GNUC__ <= 10
+#pragma GCC diagnostic ignored "-Wparentheses"
+#endif
+#if __GNUC__ < 9
+#pragma GCC diagnostic ignored "-Wuseless-cast"
+#endif
+#endif
+
 using namespace couchbase::core::transactions;
 static const tao::json::value content{
     { "some_number", 0 },
@@ -969,4 +981,4 @@ TEST_CASE("transactions: sergey example", "[transactions]")
         auto remove_res = ctx.get_optional(id_to_remove);
         CHECK_FALSE(remove_res.has_value());
     }));
-}
+}