couchbase 4.2.11 → 4.3.1

package/deps/couchbase-cxx-client/core/transactions/transactions.cxx

@@ -26,6 +26,8 @@
 #include "internal/transactions_cleanup.hxx"
 #include "internal/utils.hxx"
 
+#include <system_error>
+
 namespace couchbase::core::transactions
 {
 transactions::transactions(core::cluster cluster, const couchbase::transactions::transactions_config& config)
@@ -38,35 +40,60 @@ transactions::transactions(core::cluster cluster, const couchbase::transactions:
   , config_(config)
   , cleanup_(new transactions_cleanup(cluster_, config_))
 {
-    CB_TXN_LOG_DEBUG(
-      "couchbase transactions {} ({}) creating new transaction object", couchbase::core::meta::sdk_id(), couchbase::core::meta::os());
-    // if the config specifies custom metadata collection, lets be sure to open that bucket
-    // on the cluster before we start.  NOTE: we actually do call get_and_open_buckets which opens all the buckets
-    // on the cluster (that we have permissions to open) in the cleanup.   However, that is happening asynchronously
-    // so there's a chance we will fail to have opened the custom metadata collection bucket before trying to make a
-    // transaction.   We have to open this one _now_.
-    if (config_.metadata_collection) {
-        auto barrier = std::make_shared<std::promise<std::error_code>>();
-        auto f = barrier->get_future();
-        std::atomic<bool> callback_called{ false };
-        cluster_.open_bucket(config_.metadata_collection->bucket, [&callback_called, barrier](std::error_code ec) {
-            if (callback_called.load()) {
-                return;
+}
+
+transactions::~transactions() = default;
+
+void
+transactions::create(core::cluster cluster,
+                     const couchbase::transactions::transactions_config::built& config,
+                     utils::movable_function<void(std::error_code, std::shared_ptr<transactions>)>&& cb)
+{
+    if (config.metadata_collection) {
+        // if the config specifies custom metadata collection, lets be sure to open that bucket
+        // on the cluster before we start.  NOTE: we actually do call get_and_open_buckets which opens all the buckets
+        // on the cluster (that we have permissions to open) in the cleanup.   However, that is happening asynchronously
+        // so there's a chance we will fail to have opened the custom metadata collection bucket before trying to make a
+        // transaction. We have to open this one _now_.
+
+        auto bucket_name = config.metadata_collection->bucket;
+        return cluster.open_bucket(bucket_name, [cluster, config, bucket_name, cb = std::move(cb)](std::error_code ec) mutable {
+            if (ec) {
+                CB_TXN_LOG_ERROR("error opening metadata_collection bucket '{}' specified in the config!", bucket_name);
+                return cb(ec, {});
             }
-            callback_called = true;
-            barrier->set_value(ec);
+
+            CB_TXN_LOG_DEBUG("couchbase transactions {} ({}) creating new transaction object",
+                             couchbase::core::meta::sdk_id(),
+                             couchbase::core::meta::os());
+            return cb({}, std::make_shared<transactions>(std::move(cluster), config));
         });
-        auto err = f.get();
-        if (err) {
-            auto err_msg =
-              fmt::format("error opening metadata_collection bucket '{}' specified in the config!", config_.metadata_collection->bucket);
-            CB_TXN_LOG_DEBUG("{}", err_msg);
-            throw std::runtime_error(err_msg);
-        }
     }
+
+    return cb({}, std::make_shared<transactions>(std::move(cluster), config));
 }
 
-transactions::~transactions() = default;
+void
+transactions::create(core::cluster cluster,
+                     const couchbase::transactions::transactions_config& config,
+                     utils::movable_function<void(std::error_code, std::shared_ptr<transactions>)>&& cb)
+{
+    return create(std::move(cluster), config.build(), std::move(cb));
+}
+
+std::future<std::pair<std::error_code, std::shared_ptr<transactions>>>
+transactions::create(core::cluster cluster, const couchbase::transactions::transactions_config::built& config)
+{
+    auto barrier = std::make_shared<std::promise<std::pair<std::error_code, std::shared_ptr<transactions>>>>();
+    create(std::move(cluster), config, [barrier](auto ec, auto txns) mutable { barrier->set_value({ ec, txns }); });
+    return barrier->get_future();
+}
+
+std::future<std::pair<std::error_code, std::shared_ptr<transactions>>>
+transactions::create(core::cluster cluster, const couchbase::transactions::transactions_config& config)
+{
+    return create(std::move(cluster), config.build());
+}
 
 template<typename Handler>
 ::couchbase::transactions::transaction_result
@@ -175,6 +202,16 @@ transactions::run(async_logic&& code, txn_complete_callback&& cb)
     return run(config, std::move(code), std::move(cb));
 }
 
+void
+transactions::notify_fork(fork_event event)
+{
+    if (event == fork_event::prepare) {
+        cleanup_->stop();
+    } else {
+        cleanup_->start();
+    }
+}
+
 void
 transactions::close()
 {

package/deps/couchbase-cxx-client/core/transactions/transactions_cleanup.cxx

@@ -45,18 +45,8 @@ transactions_cleanup::transactions_cleanup(core::cluster cluster, const couchbas
   : cluster_(std::move(cluster))
   , config_(config)
   , client_uuid_(uid_generator::next())
-  , running_(config.cleanup_config.cleanup_client_attempts || config.cleanup_config.cleanup_lost_attempts)
 {
-    if (config.cleanup_config.cleanup_client_attempts) {
-        cleanup_thr_ = std::thread(std::bind(&transactions_cleanup::attempts_loop, this));
-    }
-    if (config_.metadata_collection) {
-        add_collection(
-          { config_.metadata_collection->bucket, config_.metadata_collection->scope, config_.metadata_collection->collection });
-    }
-    for (auto& k : config_.cleanup_config.collections) {
-        add_collection(k);
-    }
+    start();
 }
 
 static std::uint64_t
@@ -249,7 +239,9 @@ transactions_cleanup::create_client_record(const couchbase::transactions::transa
         wrap_durable_request(req, config_);
         auto barrier = std::make_shared<std::promise<result>>();
         auto f = barrier->get_future();
-        auto ec = config_.cleanup_hooks->client_record_before_create(keyspace.bucket);
+        auto ec = wait_for_hook([this, bucket = keyspace.bucket](auto handler) mutable {
+            return config_.cleanup_hooks->client_record_before_create(bucket, std::move(handler));
+        });
         if (ec) {
             throw client_error(*ec, "client_record_before_create hook raised error");
         }
@@ -285,7 +277,9 @@ transactions_cleanup::get_active_clients(const couchbase::transactions::transact
             .specs();
         auto barrier = std::make_shared<std::promise<result>>();
         auto f = barrier->get_future();
-        auto ec = config_.cleanup_hooks->client_record_before_get(keyspace.bucket);
+        auto ec = wait_for_hook([this, bucket = keyspace.bucket](auto handler) mutable {
+            return config_.cleanup_hooks->client_record_before_get(bucket, std::move(handler));
+        });
         if (ec) {
             throw client_error(*ec, "client_record_before_get hook raised error");
         }
@@ -363,7 +357,9 @@ transactions_cleanup::get_active_clients(const couchbase::transactions::transact
             mut_specs.push_back(couchbase::mutate_in_specs::remove(FIELD_CLIENTS + "." + details.expired_client_ids[idx]).xattr());
         }
         mutate_req.specs = mut_specs.specs();
-        ec = config_.cleanup_hooks->client_record_before_update(keyspace.bucket);
+        ec = wait_for_hook([this, bucket = keyspace.bucket](auto handler) mutable {
+            return config_.cleanup_hooks->client_record_before_update(bucket, std::move(handler));
+        });
         if (ec) {
             throw client_error(*ec, "client_record_before_update hook raised error");
         }
@@ -401,7 +397,9 @@ transactions_cleanup::remove_client_record_from_all_buckets(const std::string& u
               std::chrono::milliseconds(10), std::chrono::milliseconds(250), std::chrono::milliseconds(500), [this, keyspace, uuid]() {
                   try {
                       // proceed to remove the client uuid if it exists
-                      auto ec = config_.cleanup_hooks->client_record_before_remove_client(keyspace.bucket);
+                      auto ec = wait_for_hook([this, bucket = keyspace.bucket](auto handler) mutable {
+                          return config_.cleanup_hooks->client_record_before_remove_client(bucket, std::move(handler));
+                      });
                       if (ec) {
                           throw client_error(*ec, "client_record_before_remove_client hook raised error");
                       }
@@ -546,7 +544,23 @@ transactions_cleanup::add_collection(couchbase::transactions::transaction_keyspa
 }
 
 void
-transactions_cleanup::close()
+transactions_cleanup::start()
+{
+    running_ = config_.cleanup_config.cleanup_client_attempts || config_.cleanup_config.cleanup_lost_attempts;
+    if (config_.cleanup_config.cleanup_client_attempts) {
+        cleanup_thr_ = std::thread(std::bind(&transactions_cleanup::attempts_loop, this));
+    }
+    if (config_.metadata_collection) {
+        add_collection(
+          { config_.metadata_collection->bucket, config_.metadata_collection->scope, config_.metadata_collection->collection });
+    }
+    for (const auto& k : config_.cleanup_config.collections) {
+        add_collection(k);
+    }
+}
+
+void
+transactions_cleanup::stop()
 {
     {
         std::unique_lock<std::mutex> lock(mutex_);
@@ -563,6 +577,12 @@ transactions_cleanup::close()
             t.join();
         }
     }
+}
+
+void
+transactions_cleanup::close()
+{
+    stop();
     CB_LOST_ATTEMPT_CLEANUP_LOG_DEBUG("all lost attempt cleanup threads closed");
     remove_client_record_from_all_buckets(client_uuid_);
 }

package/deps/couchbase-cxx-client/core/transactions/utils.cxx

@@ -92,6 +92,15 @@ wrap_operation_future(std::future<result>& fut, bool ignore_subdoc_errors)
     return res;
 }
 
+std::optional<error_class>
+wait_for_hook(std::function<void(utils::movable_function<void(std::optional<error_class>)>)> hook)
+{
+    auto hook_barrier = std::make_shared<std::promise<std::optional<error_class>>>();
+    auto hook_future = hook_barrier->get_future();
+    hook([hook_barrier](std::optional<error_class> ec) mutable { return hook_barrier->set_value(ec); });
+    return hook_future.get();
+}
+
 template<>
 bool
 is_error(const core::operations::mutate_in_response& resp)

package/deps/couchbase-cxx-client/core/transactions.hxx

@@ -18,20 +18,24 @@
 
 #include <couchbase/transactions.hxx>
 
-#include "couchbase/transactions/transaction_options.hxx"
-#include "couchbase/transactions/transaction_result.hxx"
-#include "couchbase/transactions/transactions_config.hxx"
+#include <couchbase/fork_event.hxx>
+#include <couchbase/transactions/transaction_options.hxx>
+#include <couchbase/transactions/transaction_result.hxx>
+#include <couchbase/transactions/transactions_config.hxx>
+
 #include "transactions/async_attempt_context.hxx"
 #include "transactions/attempt_context.hxx"
 #include "transactions/exceptions.hxx"
 
 #include "core/cluster.hxx"
 #include "core/logger/logger.hxx"
+#include "core/utils/movable_function.hxx"
 
 #include <spdlog/common.h>
 
 #include <cmath>
 #include <functional>
+#include <system_error>
 #include <thread>
 
 // workaround for MSVC define overlap with log levels
@@ -127,6 +131,11 @@ using txn_complete_callback =
 class transactions : public couchbase::transactions::transactions
 {
   public:
+    /**
+     * @brief Destructor
+     */
+    ~transactions();
+
     /**
      * @brief Create a transactions object.
      *
@@ -134,14 +143,30 @@ class transactions : public couchbase::transactions::transactions
      *
      * @param cluster The cluster to use for the transactions.
      * @param config The configuration parameters to use for the transactions.
+     * @param cb Called when the transactions object has been created or an error has occurred during the creation.
      */
-    transactions(core::cluster cluster, const couchbase::transactions::transactions_config::built& config);
-    transactions(core::cluster cluster, const couchbase::transactions::transactions_config& config);
+    static void create(core::cluster cluster,
+                       const couchbase::transactions::transactions_config::built&,
+                       utils::movable_function<void(std::error_code, std::shared_ptr<transactions>)>&& cb);
+    static void create(core::cluster cluster,
+                       const couchbase::transactions::transactions_config&,
+                       utils::movable_function<void(std::error_code, std::shared_ptr<transactions>)>&& cb);
 
     /**
-     * @brief Destructor
+     * @brief Create a transactions object.
+     *
+     * Creates a transactions object, which can be used to run transactions within the current thread.
+     *
+     * @param cluster The cluster to use for the transactions.
+     * @param config The configuration parameters to use for the transactions.
+     * @return a future containing the error that occurred or the transactions object.
      */
-    ~transactions();
+    static std::future<std::pair<std::error_code, std::shared_ptr<transactions>>> create(
+      core::cluster cluster,
+      const couchbase::transactions::transactions_config::built& config);
+    static std::future<std::pair<std::error_code, std::shared_ptr<transactions>>> create(
+      core::cluster cluster,
+      const couchbase::transactions::transactions_config& config);
 
     /**
      * @brief Run a transaction
@@ -199,6 +224,8 @@ class transactions : public couchbase::transactions::transactions
         ctx.rollback();
     }
 
+    void notify_fork(fork_event event);
+
     /**
      * @brief Shut down the transactions object
      *
@@ -245,6 +272,12 @@ class transactions : public couchbase::transactions::transactions
         return cluster_;
     }
 
+    /**
+     * @internal
+     */
+    transactions(core::cluster cluster, const couchbase::transactions::transactions_config::built& config);
+    transactions(core::cluster cluster, const couchbase::transactions::transactions_config& config);
+
   private:
     core::cluster cluster_;
     couchbase::transactions::transactions_config::built config_;

package/deps/couchbase-cxx-client/couchbase/cluster.hxx

@@ -23,6 +23,7 @@
 #include <couchbase/bucket_manager.hxx>
 #include <couchbase/cluster_options.hxx>
 #include <couchbase/diagnostics_options.hxx>
+#include <couchbase/fork_event.hxx>
 #include <couchbase/ping_options.hxx>
 #include <couchbase/query_index_manager.hxx>
 #include <couchbase/query_options.hxx>
@@ -40,6 +41,11 @@ namespace couchbase
 namespace core
 {
 class cluster;
+
+namespace transactions
+{
+class transactions;
+}
 } // namespace core
 class cluster_impl;
 #endif
@@ -90,6 +96,8 @@ class cluster
     auto operator=(const cluster& other) -> cluster& = default;
     auto operator=(cluster&& other) -> cluster& = default;
 
+    void notify_fork(fork_event event);
+
     void close() const;
 
     /**
@@ -102,6 +110,17 @@ class cluster
      */
     explicit cluster(core::cluster core);
 
+    /**
+     * Wraps low-level implementation of the SDK & transactions
+     *
+     * @param core pointer to the low-level SDK handle
+     * @param transactions pointer to the lowe-level transactions handle
+     *
+     * @since 1.0.0
+     * @volatile
+     */
+    explicit cluster(core::cluster core, std::shared_ptr<core::transactions::transactions> transactions);
+
     /**
      * Opens a {@link bucket} with the given name.
      *

package/deps/couchbase-cxx-client/couchbase/collection.hxx

@@ -37,6 +37,9 @@
 #include <couchbase/query_options.hxx>
 #include <couchbase/remove_options.hxx>
 #include <couchbase/replace_options.hxx>
+#include <couchbase/scan_options.hxx>
+#include <couchbase/scan_result.hxx>
+#include <couchbase/scan_type.hxx>
 #include <couchbase/touch_options.hxx>
 #include <couchbase/unlock_options.hxx>
 #include <couchbase/upsert_options.hxx>
@@ -925,6 +928,39 @@ class collection
     [[nodiscard]] auto exists(std::string document_id, const exists_options& options = {}) const
       -> std::future<std::pair<key_value_error_context, exists_result>>;
 
+    /**
+     * Performs a key-value scan operation on the collection.
+     *
+     * @param scan_type the type of the scan. Can be @ref range_scan, @ref prefix_scan or @ref sampling_scan
+     * @param options the options to customize
+     * @param handler callable that implements @ref scan_handler
+     *
+     * @note Use this API for low concurrency batch queries where latency is not critical as the system may have to scan
+     * a lot of documents to find the matching documents. For low latency range queries, it is recommended that you use
+     * SQL++ with the necessary indexes.
+     *
+     * @since 1.0.0
+     * @volatile
+     */
+    void scan(const scan_type& scan_type, const scan_options& options, scan_handler&& handler) const;
+
+    /**
+     * Performs a key-value scan operation on the collection.
+     *
+     * @param scan_type the type of the scan. Can be @ref range_scan, @ref prefix_scan or @ref sampling_scan
+     * @param options the options to customize
+     * @return future object that carries result of the operation
+     *
+     * @note Use this API for low concurrency batch queries where latency is not critical as the system may have to scan
+     * a lot of documents to find the matching documents. For low latency range queries, it is recommended that you use
+     * SQL++ with the necessary indexes.
+     *
+     * @since 1.0.0
+     * @volatile
+     */
+    [[nodiscard]] auto scan(const scan_type& scan_type, const scan_options& options = {}) const
+      -> std::future<std::pair<std::error_code, scan_result>>;
+
     [[nodiscard]] auto query_indexes() const -> collection_query_index_manager;
 
   private:

package/deps/couchbase-cxx-client/couchbase/fork_event.hxx

@@ -0,0 +1,39 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-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.
+ */
+
+#pragma once
+
+namespace couchbase
+{
+enum class fork_event {
+    /**
+     * Notify the cluster that the process is about to fork.
+     */
+    prepare,
+
+    /**
+     * Notify the context that the process has forked and is the parent.
+     */
+    parent,
+
+    /**
+     * Notify the context that the process has forked and is the child.
+     */
+    child,
+};
+
+} // namespace couchbase

package/deps/couchbase-cxx-client/couchbase/query_options.hxx

@@ -60,7 +60,7 @@ struct query_options : public common_options<query_options> {
         std::optional<std::string> client_context_id;
         std::optional<query_scan_consistency> scan_consistency;
         std::vector<mutation_token> mutation_state;
-        const query_profile profile;
+        std::optional<query_profile> profile;
         std::vector<codec::binary> positional_parameters;
         std::map<std::string, codec::binary, std::less<>> named_parameters;
         std::map<std::string, codec::binary, std::less<>> raw;
@@ -555,7 +555,7 @@ struct query_options : public common_options<query_options> {
     std::optional<std::chrono::milliseconds> scan_wait_{};
     std::optional<query_scan_consistency> scan_consistency_{};
     std::vector<mutation_token> mutation_state_{};
-    query_profile profile_{ query_profile::off };
+    std::optional<query_profile> profile_{};
     std::vector<codec::binary> positional_parameters_{};
     std::map<std::string, codec::binary, std::less<>> raw_{};
     std::map<std::string, codec::binary, std::less<>> named_parameters_{};

package/deps/couchbase-cxx-client/couchbase/scan_options.hxx

@@ -0,0 +1,163 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2024. 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.
+ */
+
+#pragma once
+
+#include <couchbase/common_options.hxx>
+#include <couchbase/mutation_state.hxx>
+#include <couchbase/mutation_token.hxx>
+#include <couchbase/scan_result.hxx>
+
+#include <cstdint>
+#include <functional>
+#include <optional>
+#include <vector>
+
+namespace couchbase
+{
+
+/**
+ * Options for @ref collection#scan().
+ *
+ * @since 1.0.0
+ * @committed
+ */
+struct scan_options : public common_options<scan_options> {
+  public:
+    /**
+     * Specifies whether only document IDs should be included in the results. Defaults to false.
+     *
+     * @param ids_only if set to true the content will not be included in the results
+     * @return the options builder for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto ids_only(bool ids_only) -> scan_options&
+    {
+        ids_only_ = ids_only;
+        return self();
+    }
+
+    /**
+     * Sets the {@link mutation_token}s this scan should be consistent with.
+     *
+     * These mutation tokens are returned from mutations (i.e. as part of a {@link mutation_result}) and if you want your
+     * scan to include those you need to pass the mutation tokens into a {@link mutation_state}.
+     *
+     * @param state the mutation state containing the mutation tokens.
+     * @return the options builder for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto consistent_with(const mutation_state& state) -> scan_options&
+    {
+        mutation_state_ = state.tokens();
+        return self();
+    }
+
+    /**
+     * Allows to limit the maximum amount of bytes that are sent from the server in each partition batch. Defaults to 15,000.
+     *
+     * @param batch_byte_limit the byte limit
+     * @return the options builder for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto batch_byte_limit(std::uint32_t batch_byte_limit) -> scan_options&
+    {
+        batch_byte_limit_ = batch_byte_limit;
+        return self();
+    }
+
+    /**
+     * Allows to limit the maximum number of scan items that are sent from the server in each partition batch. Defaults to 50.
+     *
+     * @param batch_item_limit the item limit
+     * @return the options builder for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto batch_item_limit(std::uint32_t batch_item_limit) -> scan_options&
+    {
+        batch_item_limit_ = batch_item_limit;
+        return self();
+    }
+
+    /**
+     * Specifies the maximum number of partitions that can be scanned concurrently. Defaults to 1.
+     *
+     * @param concurrency the maximum number of concurrent partition scans
+     * @return the options builder for chaining purposes.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto concurrency(std::uint16_t concurrency) -> scan_options&
+    {
+        concurrency_ = concurrency;
+        return self();
+    }
+
+    /**
+     * Immutable value object representing consistent options.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    struct built : public common_options<scan_options>::built {
+        bool ids_only;
+        std::vector<mutation_token> mutation_state;
+        std::optional<std::uint32_t> batch_byte_limit;
+        std::optional<std::uint32_t> batch_item_limit;
+        std::optional<std::uint16_t> concurrency;
+    };
+
+    /**
+     * Validates options and returns them as an immutable value.
+     *
+     * @return consistent options as an immutable value.
+     *
+     * @exception std::system_error with code @ref errc::common::invalid_argument if the options are not valid.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto build() const -> built
+    {
+        return { build_common_options(), ids_only_, mutation_state_, batch_byte_limit_, batch_item_limit_, concurrency_ };
+    }
+
+  private:
+    bool ids_only_{ false };
+    std::vector<mutation_token> mutation_state_{};
+    std::optional<std::uint32_t> batch_byte_limit_{};
+    std::optional<std::uint32_t> batch_item_limit_{};
+    std::optional<std::uint16_t> concurrency_{};
+};
+
+/**
+ * The signature for the handler of the @ref collection#scan() operation.
+ *
+ * @since 1.0.0
+ * @volatile
+ */
+using scan_handler = std::function<void(std::error_code, scan_result)>;
+} // namespace couchbase