couchbase 3.3.0 → 3.4.0

data/ext/couchbase/couchbase/transactions/transaction_result.hxx

@@ -0,0 +1,34 @@
+/*
+ *     Copyright 2021-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
+
+#include <couchbase/transaction_error_context.hxx>
+#include <string>
+
+namespace couchbase::transactions
+{
+/**
+ * Results of a transaction
+ * @volatile
+ *
+ * Contains internal information on a transaction,
+ * returned by @ref core::transactions::run()
+ */
+struct transaction_result {
+    std::string transaction_id;
+    bool unstaging_complete;
+};
+} // namespace couchbase::transactions

data/ext/couchbase/couchbase/transactions/transactions_cleanup_config.hxx

@@ -0,0 +1,140 @@
+/*
+ *     Copyright 2021-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
+
+#include <chrono>
+#include <list>
+
+#include <couchbase/transactions/transaction_keyspace.hxx>
+namespace couchbase::transactions
+{
+
+class transactions_cleanup_config
+{
+  public:
+    /**
+     * @brief Enable/disable the lost attempts cleanup loop.
+     * @see @ref cleanup_window() for description of the cleanup lost attempts loop.
+     *
+     * @param value If false, do not start the lost attempts cleanup threads.
+     * @return reference to this, so calls can be chained.
+     */
+    transactions_cleanup_config& cleanup_lost_attempts(bool value)
+    {
+        cleanup_lost_attempts_ = value;
+        return *this;
+    }
+    /**
+     * @brief Get lost attempts cleanup loop status.
+     * @see @ref cleanup_window() for description of the lost attempts cleanup loop.
+     *
+     * @return If false, no lost attempts cleanup threads will be launched.
+     */
+    [[nodiscard]] bool cleanup_lost_attempts() const
+    {
+        return cleanup_lost_attempts_;
+    }
+
+    /**
+     * @brief Set state for the client attempts cleanup loop.
+     * @see @ref cleanup_client_attempts()
+     *
+     * @param value If true, run the cleanup client attempts loop.
+     * @return reference to this, so calls can be chained.
+     */
+    transactions_cleanup_config& cleanup_client_attempts(bool value)
+    {
+        cleanup_client_attempts_ = value;
+        return *this;
+    }
+
+    /**
+     * @brief Get state of client attempts cleanup loop.
+     *
+     * A transactions object will create a background thread to do any cleanup necessary
+     * for the transactions it has attempted.  This can be disabled if set to false.
+     *
+     * @return true if the thread is enabled, false if not.
+     */
+    [[nodiscard]] bool cleanup_client_attempts() const
+    {
+        return cleanup_client_attempts_;
+    }
+
+    /**
+     * @brief Get cleanup window
+     *
+     * Each @ref transactions instance has background threads which looks for evidence of
+     * transactions that somehow were not cleaned up during ordinary processing.  There is one
+     * of these per bucket.  The thread looks through the active transaction records on that bucket
+     * once during each window.  There are potentially 1024 of these records, so over one cleanup
+     * window period, the thread will look for all 1024 of these, and examine any it finds.  Note
+     * you can disable this by setting @ref cleanup_lost_attempts() false.
+     *
+     * @return The cleanup window.
+     */
+    [[nodiscard]] std::chrono::milliseconds cleanup_window() const
+    {
+        return cleanup_window_;
+    }
+
+    /**
+     * @brief Set cleanup window
+     *
+     * @see cleanup_window() for more info.
+     * @param duration An std::chrono::duration representing the cleanup window duration.
+     * @return reference to this, so calls can be chained.
+     */
+    template<typename T>
+    transactions_cleanup_config& cleanup_window(T duration)
+    {
+        cleanup_window_ = std::chrono::duration_cast<std::chrono::milliseconds>(duration);
+        return *this;
+    }
+
+    /**
+     * @brief Add a collection to be cleaned
+     *
+     * This can be called multiple times, to add several collections, if needed.
+     *
+     */
+    transactions_cleanup_config& add_collection(const couchbase::transactions::transaction_keyspace& keyspace)
+    {
+        collections_.emplace_back(keyspace);
+        return *this;
+    }
+
+    /** @internal */
+    struct built {
+        bool cleanup_lost_attempts;
+        bool cleanup_client_attempts;
+        std::chrono::milliseconds cleanup_window;
+        std::list<couchbase::transactions::transaction_keyspace> collections;
+    };
+
+    /** @internal */
+    [[nodiscard]] auto build() const -> built
+    {
+        return { cleanup_lost_attempts_, cleanup_client_attempts_, cleanup_window_, collections_ };
+    }
+
+  private:
+    bool cleanup_lost_attempts_{ true };
+    bool cleanup_client_attempts_{ true };
+    std::chrono::milliseconds cleanup_window_{ std::chrono::seconds(60) };
+    std::list<couchbase::transactions::transaction_keyspace> collections_{};
+};
+} // namespace couchbase::transactions

data/ext/couchbase/couchbase/transactions/transactions_config.hxx

@@ -0,0 +1,255 @@
+/*
+ *     Copyright 2021-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
+
+#include <couchbase/transactions/transaction_keyspace.hxx>
+#include <couchbase/transactions/transactions_cleanup_config.hxx>
+#include <couchbase/transactions/transactions_query_config.hxx>
+
+#include <chrono>
+#include <memory>
+#include <optional>
+
+namespace couchbase::core::transactions
+{
+/** @internal */
+struct attempt_context_testing_hooks;
+
+/** @internal */
+struct cleanup_testing_hooks;
+} // namespace couchbase::core::transactions
+
+namespace couchbase::transactions
+{
+/**
+ * @brief Configuration parameters for transactions.
+ */
+class transactions_config
+{
+  public:
+    transactions_config();
+
+    ~transactions_config();
+
+    transactions_config(const transactions_config& c);
+
+    transactions_config(transactions_config&& c) noexcept;
+
+    transactions_config& operator=(const transactions_config& c);
+
+    /**
+     * @brief Get the default durability level for all transaction operations
+     *
+     * @return The default durability level used for write operations.
+     */
+    [[nodiscard]] couchbase::durability_level durability_level() const
+    {
+        return level_;
+    }
+
+    /**
+     * @brief Set the default durability level for all transaction operations
+     *
+     * @param level The default durability level desired for write operations.
+     * @return reference to this, so calls can be chained.
+     */
+    transactions_config& durability_level(enum couchbase::durability_level level)
+    {
+        level_ = level;
+        return *this;
+    }
+
+    /**
+     * @brief Set kv_timeout
+     *
+     * @see kv_timeout()
+     * @param duration An std::chrono::duration representing the desired default kv operation timeout.
+     * @return reference to this, so calls can be chained.
+     */
+    template<typename T>
+    transactions_config& kv_timeout(T duration)
+    {
+        kv_timeout_ = std::chrono::duration_cast<std::chrono::milliseconds>(duration);
+        return *this;
+    }
+
+    /**
+     * @brief Get kv_timeout
+     *
+     * This is the default kv operation timeout used throughout the transactions.  Note all the operations
+     * have an options class which allows you to override this value for a particular operation, if desired.
+     *
+     * @return The default kv operation timeout.
+     */
+    [[nodiscard]] std::optional<std::chrono::milliseconds> kv_timeout() const
+    {
+        return kv_timeout_;
+    }
+
+    /**
+     * @brief Get expiration time for transactions
+     *
+     * Transactions can conflict (or other operations on those documents), and may retry.
+     * This is the maximum time a transaction can take, including any retries.  The transaction will throw
+     * an @ref transaction_expired and rollback when this occurs.
+     *
+     * @return expiration time for transactions.
+     */
+    [[nodiscard]] std::chrono::nanoseconds expiration_time() const
+    {
+        return expiration_time_;
+    }
+    /**
+     * @brief Set the expiration time for transactions.
+     *
+     * @param duration desired expiration for transactions. see @expiration_time().
+     * @return reference to this, so calls can be chained.
+     */
+    template<typename T>
+    transactions_config& expiration_time(T duration)
+    {
+        expiration_time_ = std::chrono::duration_cast<std::chrono::nanoseconds>(duration);
+        return *this;
+    }
+
+    /**
+     * Set the transaction's metadata collection.
+     *
+     * @param keyspace The collection to use for the transaction metadata.
+     * @return reference to this, so calls can be chained.
+     */
+    transactions_config& metadata_collection(const couchbase::transactions::transaction_keyspace& keyspace)
+    {
+        metadata_collection_ = keyspace;
+        return *this;
+    }
+
+    [[nodiscard]] std::optional<couchbase::transactions::transaction_keyspace> metadata_collection() const
+    {
+        return metadata_collection_;
+    }
+
+    /**
+     * Get the query config values
+     *
+     * @return The query configuration for transactions.
+     */
+    [[nodiscard]] const transactions_query_config& query_config() const
+    {
+        return query_config_;
+    }
+
+    /**
+     * Get the query config values
+     *
+     * @return The query configuration for transactions.
+     */
+    [[nodiscard]] transactions_query_config& query_config()
+    {
+        return query_config_;
+    }
+
+    /**
+     * Set the query configuration for transactions.
+     *
+     * @param config The transactions query configuration to use.
+     * @return reference to this, so calls can be chained.
+     */
+    transactions_config& query_config(const transactions_query_config& config)
+    {
+        query_config_ = config;
+        return *this;
+    }
+
+    /**
+     * Get the cleanup configuration for transactions.
+     *
+     * @return The cleanup configuration.
+     */
+    [[nodiscard]] const transactions_cleanup_config& cleanup_config() const
+    {
+        return cleanup_config_;
+    }
+
+    /**
+     * Get the cleanup configuration for transactions.
+     *
+     * @return The cleanup configuration.
+     */
+    [[nodiscard]] transactions_cleanup_config& cleanup_config()
+    {
+        return cleanup_config_;
+    }
+
+    /**
+     * Set the cleanup configuration.
+     *
+     * @param cleanup_config The cleanup configuration to use.
+     * @return reference to this, so calls can be chained.
+     */
+    transactions_config& cleanup_config(const transactions_cleanup_config& cleanup_config)
+    {
+        cleanup_config_ = cleanup_config;
+        return *this;
+    }
+
+    /** @internal */
+    transactions_config& test_factories(std::shared_ptr<core::transactions::attempt_context_testing_hooks> hooks,
+                                        std::shared_ptr<core::transactions::cleanup_testing_hooks> cleanup_hooks)
+    {
+        attempt_context_hooks_ = hooks;
+        cleanup_hooks_ = cleanup_hooks;
+        return *this;
+    }
+
+    /** @internal */
+    [[nodiscard]] core::transactions::attempt_context_testing_hooks& attempt_context_hooks() const
+    {
+        return *attempt_context_hooks_;
+    }
+
+    /** @internal */
+    [[nodiscard]] core::transactions::cleanup_testing_hooks& cleanup_hooks() const
+    {
+        return *cleanup_hooks_;
+    }
+
+    /** @internal */
+    struct built {
+        couchbase::durability_level level;
+        std::chrono::nanoseconds expiration_time;
+        std::optional<std::chrono::milliseconds> kv_timeout;
+        std::shared_ptr<core::transactions::attempt_context_testing_hooks> attempt_context_hooks;
+        std::shared_ptr<core::transactions::cleanup_testing_hooks> cleanup_hooks;
+        std::optional<couchbase::transactions::transaction_keyspace> metadata_collection;
+        transactions_query_config::built query_config;
+        transactions_cleanup_config::built cleanup_config;
+    };
+
+    /** @internal */
+    [[nodiscard]] built build() const;
+
+  private:
+    couchbase::durability_level level_{ couchbase::durability_level::majority };
+    std::chrono::nanoseconds expiration_time_{ std::chrono::seconds(15) };
+    std::optional<std::chrono::milliseconds> kv_timeout_;
+    std::shared_ptr<core::transactions::attempt_context_testing_hooks> attempt_context_hooks_;
+    std::shared_ptr<core::transactions::cleanup_testing_hooks> cleanup_hooks_;
+    std::optional<couchbase::transactions::transaction_keyspace> metadata_collection_;
+    transactions_query_config query_config_{};
+    transactions_cleanup_config cleanup_config_{};
+};
+} // namespace couchbase::transactions

data/ext/couchbase/couchbase/transactions/transactions_query_config.hxx

@@ -0,0 +1,61 @@
+/*
+ *     Copyright 2021-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
+
+#include <couchbase/query_scan_consistency.hxx>
+
+namespace couchbase::transactions
+{
+class transactions_query_config
+{
+  public:
+    /**
+     * Set scan consistency for transactions.
+     *
+     * @param consistency the query_scan_consistency to use.
+     * @return reference to this, so calls can be chained.
+     */
+    transactions_query_config& scan_consistency(query_scan_consistency consistency)
+    {
+        scan_consistency_ = consistency;
+        return *this;
+    }
+
+    /**
+     * Get the scan consistency
+     *
+     * @return the query_scan_consistency
+     */
+    [[nodiscard]] query_scan_consistency scan_consistency() const
+    {
+        return scan_consistency_;
+    }
+
+    /** @internal */
+    struct built {
+        query_scan_consistency scan_consistency;
+    };
+
+    /** @internal */
+    [[nodiscard]] auto build() const -> built
+    {
+        return { scan_consistency_ };
+    }
+
+  private:
+    query_scan_consistency scan_consistency_{ query_scan_consistency::request_plus };
+};
+} // namespace couchbase::transactions

data/ext/couchbase/couchbase/transactions.hxx

@@ -0,0 +1,43 @@
+/* -*- 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
+
+#include <couchbase/transactions/async_attempt_context.hxx>
+#include <couchbase/transactions/attempt_context.hxx>
+#include <couchbase/transactions/transaction_options.hxx>
+#include <couchbase/transactions/transaction_result.hxx>
+
+#include <functional>
+
+namespace couchbase::transactions
+{
+using txn_logic = std::function<void(attempt_context&)>;
+using async_txn_logic = std::function<void(async_attempt_context&)>;
+using async_txn_complete_logic = std::function<void(couchbase::transaction_error_context, transaction_result)>;
+
+class transactions
+{
+  public:
+    virtual ~transactions() = default;
+    virtual std::pair<transaction_error_context, transaction_result> run(txn_logic&& logic,
+                                                                         const transaction_options& cfg = transaction_options()) = 0;
+    virtual void run(async_txn_logic&& logic,
+                     async_txn_complete_logic&& complete_callback,
+                     const transaction_options& cfg = transaction_options()) = 0;
+};
+} // namespace couchbase::transactions

data/ext/couchbase/couchbase/unlock_options.hxx

@@ -0,0 +1,97 @@
+/* -*- 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
+
+#include <couchbase/codec/encoded_value.hxx>
+#include <couchbase/common_options.hxx>
+#include <couchbase/expiry.hxx>
+#include <couchbase/key_value_error_context.hxx>
+
+#include <chrono>
+#include <functional>
+#include <memory>
+#include <optional>
+#include <vector>
+
+namespace couchbase
+{
+
+/**
+ * Options for @ref collection#unlock().
+ *
+ * @since 1.0.0
+ * @committed
+ */
+struct unlock_options : public common_options<unlock_options> {
+    /**
+     * Immutable value object representing consistent options.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    struct built : public common_options<unlock_options>::built {
+    };
+
+    /**
+     * Validates options and returns them as an immutable value.
+     *
+     * @return consistent options as an immutable value
+     *
+     * @exception std::system_error with code errc::common::invalid_argument if the options are not valid
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    [[nodiscard]] auto build() const -> built
+    {
+        return { build_common_options() };
+    }
+};
+
+/**
+ * The signature for the handler of the @ref collection#unlock() operation
+ *
+ * @since 1.0.0
+ * @uncommitted
+ */
+using unlock_handler = std::function<void(couchbase::key_value_error_context)>;
+
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+namespace core
+{
+class cluster;
+namespace impl
+{
+
+/**
+ * @since 1.0.0
+ * @internal
+ */
+void
+initiate_unlock_operation(std::shared_ptr<couchbase::core::cluster> core,
+                          std::string bucket_name,
+                          std::string scope_name,
+                          std::string collection_name,
+                          std::string document_key,
+                          couchbase::cas cas,
+                          unlock_options::built options,
+                          unlock_handler&& handler);
+#endif
+} // namespace impl
+} // namespace core
+} // namespace couchbase