couchbase 4.2.8 → 4.2.10

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

@@ -17,32 +17,33 @@
 
 #pragma once
 
+#include <couchbase/analytics_index_manager.hxx>
 #include <couchbase/analytics_options.hxx>
 #include <couchbase/bucket.hxx>
 #include <couchbase/bucket_manager.hxx>
 #include <couchbase/cluster_options.hxx>
+#include <couchbase/diagnostics_options.hxx>
+#include <couchbase/ping_options.hxx>
 #include <couchbase/query_index_manager.hxx>
 #include <couchbase/query_options.hxx>
+#include <couchbase/search_index_manager.hxx>
 #include <couchbase/search_options.hxx>
 #include <couchbase/search_query.hxx>
+#include <couchbase/search_request.hxx>
 #include <couchbase/transactions.hxx>
 
 #include <memory>
 
-#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
-namespace couchbase::core
+namespace couchbase
 {
-namespace transactions
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+namespace core
 {
-class transactions;
-} // namespace transactions
-
 class cluster;
-} // namespace couchbase::core
+} // namespace core
+class cluster_impl;
 #endif
 
-namespace couchbase
-{
 /**
  * The {@link cluster} is the main entry point when connecting to a Couchbase cluster.
  *
@@ -55,21 +56,18 @@ class cluster
     /**
      * Connect to a Couchbase cluster.
      *
-     * @tparam Handler callable type that implements @ref cluster_connect_handler signature
-     *
      * @param io IO context
      * @param connection_string connection string used to locate the Couchbase cluster object.
      * @param options options to customize connection (note, that connection_string takes precedence over this options).
-     * @param handler the handler that implements @ref cluster_connect_handler
+     * @param handler the handler
      *
      * @since 1.0.0
      * @committed
      */
-    template<typename Handler>
-    static void connect(asio::io_context& io, const std::string& connection_string, const cluster_options& options, Handler&& handler)
-    {
-        return core::impl::initiate_cluster_connect(io, connection_string, options, std::forward<Handler>(handler));
-    }
+    static void connect(asio::io_context& io,
+                        const std::string& connection_string,
+                        const cluster_options& options,
+                        cluster_connect_handler&& handler);
 
     /**
      * Connect to a Couchbase cluster.
@@ -84,13 +82,7 @@ class cluster
      * @committed
      */
     [[nodiscard]] static auto connect(asio::io_context& io, const std::string& connection_string, const cluster_options& options)
-      -> std::future<std::pair<cluster, std::error_code>>
-    {
-        auto barrier = std::make_shared<std::promise<std::pair<cluster, std::error_code>>>();
-        auto future = barrier->get_future();
-        connect(io, connection_string, options, [barrier](auto c, auto ec) { barrier->set_value({ std::move(c), ec }); });
-        return future;
-    }
+      -> std::future<std::pair<cluster, std::error_code>>;
 
     cluster() = default;
     cluster(const cluster& other) = default;
@@ -98,7 +90,7 @@ class cluster
     auto operator=(const cluster& other) -> cluster& = default;
     auto operator=(cluster&& other) -> cluster& = default;
 
-    void close();
+    void close() const;
 
     /**
      * Wraps low-level implementation of the SDK to provide common API.
@@ -108,10 +100,7 @@ class cluster
      * @since 1.0.0
      * @volatile
      */
-    explicit cluster(std::shared_ptr<couchbase::core::cluster> core)
-      : core_(std::move(core))
-    {
-    }
+    explicit cluster(core::cluster core);
 
     /**
      * Opens a {@link bucket} with the given name.
@@ -122,16 +111,11 @@ class cluster
      * @since 1.0.0
      * @committed
      */
-    [[nodiscard]] auto bucket(std::string_view bucket_name) const -> bucket
-    {
-        return { core_, bucket_name };
-    }
+    [[nodiscard]] auto bucket(std::string_view bucket_name) const -> bucket;
 
     /**
      * Performs a query against the query (N1QL) services.
      *
-     * @tparam Handler callable type that implements @ref query_handler signature
-     *
      * @param statement the N1QL query statement.
      * @param options options to customize the query request.
      * @param handler the handler that implements @ref query_handler
@@ -142,11 +126,7 @@ class cluster
      * @since 1.0.0
      * @committed
      */
-    template<typename Handler>
-    void query(std::string statement, const query_options& options, Handler&& handler) const
-    {
-        return core::impl::initiate_query_operation(core_, std::move(statement), {}, options.build(), std::forward<Handler>(handler));
-    }
+    void query(std::string statement, const query_options& options, query_handler&& handler) const;
 
     /**
      * Performs a query against the query (N1QL) services.
@@ -159,19 +139,14 @@ class cluster
      * @committed
      */
     [[nodiscard]] auto query(std::string statement, const query_options& options) const
-      -> std::future<std::pair<query_error_context, query_result>>
-    {
-        auto barrier = std::make_shared<std::promise<std::pair<query_error_context, query_result>>>();
-        auto future = barrier->get_future();
-        query(std::move(statement), options, [barrier](auto ctx, auto result) {
-            barrier->set_value({ std::move(ctx), std::move(result) });
-        });
-        return future;
-    }
+      -> std::future<std::pair<query_error_context, query_result>>;
 
     /**
      * Performs a query against the full text search services.
      *
+     * Consider using the newer @ref cluster::search() interface instead, which can be used
+     * for both traditional FTS queries, and to perform a @ref vector_search
+     *
      * @param index_name name of the search index
      * @param query query object, see hierarchy of @ref search_query for more details.
      * @param options options to customize the query request.
@@ -190,6 +165,9 @@ class cluster
     /**
      * Performs a query against the full text search services.
      *
+     * Consider using the newer @ref cluster::search() interface instead, which can be used
+     * for both traditional FTS queries, and to perform a vector search.
+     *
      * @param index_name name of the search index
      * @param query query object, see hierarchy of @ref search_query for more details.
      * @param options options to customize the query request.
@@ -206,6 +184,47 @@ class cluster
     [[nodiscard]] auto search_query(std::string index_name, const class search_query& query, const search_options& options = {}) const
       -> std::future<std::pair<search_error_context, search_result>>;
 
+    /**
+     * Performs a request against the full text search services.
+     *
+     * This can be used to perform a traditional FTS query, and/or a vector search.
+     *
+     * @param index_name name of the search index
+     * @param request request object, see @ref search_request for more details.
+     * @param options options to customize the query request.
+     * @param handler the handler that implements @ref search_handler
+     *
+     * @exception errc::common::ambiguous_timeout
+     * @exception errc::common::unambiguous_timeout
+     *
+     * @see https://docs.couchbase.com/server/current/fts/fts-introduction.html
+     *
+     * @since 1.0.0
+     * @volatile
+     */
+    void search(std::string index_name, search_request request, const search_options& options, search_handler&& handler) const;
+
+    /**
+     * Performs a request against the full text search services.
+     *
+     * This can be used to perform a traditional FTS query, and/or a vector search.
+     *
+     * @param index_name name of the search index
+     * @param request request object, see @ref search_request for more details.
+     * @param options options to customize the query request.
+     * @return future object that carries result of the operation
+     *
+     * @exception errc::common::ambiguous_timeout
+     * @exception errc::common::unambiguous_timeout
+     *
+     * @see https://docs.couchbase.com/server/current/fts/fts-introduction.html
+     *
+     * @since 1.0.0
+     * @volatile
+     */
+    [[nodiscard]] auto search(std::string index_name, search_request request, const search_options& = {}) const
+      -> std::future<std::pair<search_error_context, search_result>>;
+
     /**
      * Performs a query against the analytics services.
      *
@@ -238,6 +257,66 @@ class cluster
     [[nodiscard]] auto analytics_query(std::string statement, const analytics_options& options = {}) const
       -> std::future<std::pair<analytics_error_context, analytics_result>>;
 
+    /**
+     * Performs application-level ping requests against services in the Couchbase cluster.
+     *
+     * @note This operation performs active I/O against services and endpoints to assess their health. If you do not
+     * wish to performs I/O, consider using @ref diagnostics() instead.
+     *
+     * @param options custom options to change the default behavior.
+     * @param handler the handler that implements @ref ping_handler.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    void ping(const ping_options& options, ping_handler&& handler) const;
+
+    /**
+     * Performs application-level ping requests against services in the Couchbase cluster.
+     *
+     * @note This operation performs active I/O against services and endpoints to assess their health. If you do not
+     * wish to performs I/O, consider using @ref diagnostics() instead.
+     *
+     * @param options custom options to change the default behavior.
+     * @return future object that carries result of the operation.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto ping(const ping_options& options = {}) const -> std::future<ping_result>;
+
+    /**
+     * Assembles a diagnostics report on the current state of the cluster from the SDK's point of view.
+     *
+     * @note This operation does not perform any I/O to produce the report. It will only use the current known state of
+     * the cluster to assemble the report So, if for example, no SQL++ queries have been run, the Query service's socket
+     * pool might be empty and as a result not show up in the report. If you wish to actively assess the health of the
+     * cluster by performing I/O, consider using @ref ping() instead.
+     *
+     * @param options custom options to change the default behavior.
+     * @param handler the handler that implements @ref diagnostics_handler.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    void diagnostics(const diagnostics_options& options, diagnostics_handler&& handler) const;
+
+    /**
+     * Assembles a diagnostics report on the current state of the cluster from the SDK's point of view.
+     *
+     * @note This operation does not perform any I/O to produce the report. It will only use the current known state of
+     * the cluster to assemble the report So, if for example, no SQL++ queries have been run, the Query service's socket
+     * pool might be empty and as a result not show up in the report. If you wish to actively assess the health of the
+     * cluster by performing I/O, consider using @ref ping() instead.
+     *
+     * @param options custom options to change the default behavior.
+     * @return future object that carries result of the operation.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto diagnostics(const diagnostics_options& options = {}) const -> std::future<diagnostics_result>;
+
     /**
      * Provides access to the N1QL index management services.
      *
@@ -246,52 +325,51 @@ class cluster
      * @since 1.0.0
      * @committed
      */
-    [[nodiscard]] auto query_indexes() const -> query_index_manager
-    {
-        return query_index_manager{ core_ };
-    }
+    [[nodiscard]] auto query_indexes() const -> query_index_manager;
 
     /**
-     * Provides access to the bucket management services.
+     * Provides access ot the Analytics index management services.
      *
      * @return a manager instance
      *
      * @since 1.0.0
      * @committed
      */
-    [[nodiscard]] auto buckets() const -> bucket_manager
-    {
-        return bucket_manager{ core_ };
-    }
+    [[nodiscard]] auto analytics_indexes() const -> analytics_index_manager;
 
     /**
-     * Provides access to transaction services.
-     *
-     * See {@link transactions} for details on using the transactions object.
+     * Provides access to the bucket management services.
      *
-     * @return an {@link transactions} object
+     * @return a manager instance
      *
      * @since 1.0.0
      * @committed
      */
+    [[nodiscard]] auto buckets() const -> bucket_manager;
 
-    [[nodiscard]] auto transactions() -> std::shared_ptr<couchbase::transactions::transactions>;
+    /**
+     * Provides access to search index management services
+     *
+     * @return a manager instance
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto search_indexes() const -> search_index_manager;
 
     /**
-     * Provide access to core cluster object
+     * Provides access to transaction services.
      *
-     * This is used internally, during testing, and may be removed as the API evolves.
+     * See {@link transactions} for details on using the transactions object.
      *
-     * @return pointer to core cluster
-     * @volatile
+     * @return an {@link transactions} object
+     *
+     * @since 1.0.0
+     * @committed
      */
-    [[nodiscard]] auto core() -> std::shared_ptr<couchbase::core::cluster>
-    {
-        return core_;
-    }
+    [[nodiscard]] auto transactions() const -> std::shared_ptr<couchbase::transactions::transactions>;
 
   private:
-    std::shared_ptr<couchbase::core::cluster> core_{};
-    std::shared_ptr<couchbase::core::transactions::transactions> transactions_{};
+    std::shared_ptr<cluster_impl> impl_{};
 };
 } // namespace couchbase

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

@@ -25,6 +25,7 @@
 #include <couchbase/metrics_options.hxx>
 #include <couchbase/network_options.hxx>
 #include <couchbase/password_authenticator.hxx>
+#include <couchbase/retry_strategy.hxx>
 #include <couchbase/security_options.hxx>
 #include <couchbase/timeout_options.hxx>
 #include <couchbase/tracing_options.hxx>
@@ -312,31 +313,4 @@ class cluster;
  * @uncommitted
  */
 using cluster_connect_handler = std::function<void(cluster, std::error_code)>;
-
-#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
-namespace core
-{
-class cluster;
-}
-
-namespace core::impl
-{
-
-/**
- * @since 1.0.0
- * @internal
- */
-void
-initiate_cluster_connect(asio::io_context& io,
-                         const std::string& connection_string,
-                         const couchbase::cluster_options& options,
-                         cluster_connect_handler&& handler);
-/**
- * @since 1.0.0
- * @internal
- */
-void
-initiate_cluster_close(std::shared_ptr<couchbase::core::cluster> core);
-#endif
-} // namespace core::impl
 } // namespace couchbase

package/deps/couchbase-cxx-client/couchbase/codec/json_transcoder.hxx

@@ -40,7 +40,7 @@ class json_transcoder
     {
         if (encoded.flags != 0 && !codec_flags::has_common_flags(encoded.flags, codec_flags::json_common_flags)) {
             throw std::system_error(errc::common::decoding_failure,
-                                    "json_transcoder excepts document to have JSON common flags, flags=" + std::to_string(encoded.flags));
+                                    "json_transcoder expects document to have JSON common flags, flags=" + std::to_string(encoded.flags));
         }
 
         return Serializer::template deserialize<Document>(encoded.data);

package/deps/couchbase-cxx-client/couchbase/codec/raw_binary_transcoder.hxx

@@ -21,6 +21,7 @@
 #include <couchbase/codec/encoded_value.hxx>
 #include <couchbase/codec/transcoder_traits.hxx>
 #include <couchbase/error_codes.hxx>
+
 #include <type_traits>
 
 namespace couchbase::codec
@@ -40,7 +41,7 @@ class raw_binary_transcoder
     {
         if (!codec_flags::has_common_flags(encoded.flags, codec_flags::binary_common_flags)) {
             throw std::system_error(errc::common::decoding_failure,
-                                    "raw_binary_transcoder excepts document to have BINARY common flags, flags=" +
+                                    "raw_binary_transcoder expects document to have BINARY common flags, flags=" +
                                       std::to_string(encoded.flags));
         }
 

package/deps/couchbase-cxx-client/couchbase/codec/raw_json_transcoder.hxx

@@ -0,0 +1,78 @@
+/* -*- 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/codec/codec_flags.hxx>
+#include <couchbase/codec/encoded_value.hxx>
+#include <couchbase/codec/transcoder_traits.hxx>
+#include <couchbase/error_codes.hxx>
+
+#include <cstddef>
+#include <string>
+#include <string_view>
+#include <type_traits>
+#include <vector>
+
+namespace couchbase
+{
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+namespace core::utils
+{
+std::vector<std::byte>
+to_binary(std::string_view value) noexcept;
+} // namespace core::utils
+#endif
+
+namespace codec
+{
+class raw_json_transcoder
+{
+  public:
+    template<typename Document, std::enable_if_t<std::is_same_v<Document, std::string> || std::is_same_v<Document, binary>, bool> = true>
+    static auto encode(const Document& document) -> encoded_value
+    {
+        if constexpr (std::is_same_v<Document, std::string>) {
+            return { core::utils::to_binary(document), codec_flags::json_common_flags };
+        } else {
+            return { std::move(document), codec_flags::json_common_flags };
+        }
+    }
+
+    template<typename Document, std::enable_if_t<std::is_same_v<Document, std::string> || std::is_same_v<Document, binary>, bool> = true>
+    static auto decode(const encoded_value& encoded) -> Document
+    {
+        if (!codec_flags::has_common_flags(encoded.flags, codec_flags::json_common_flags)) {
+            throw std::system_error(errc::common::decoding_failure,
+                                    "raw_json_transcoder expects document to have JSON common flags, flags=" +
+                                      std::to_string(encoded.flags));
+        }
+        if constexpr (std::is_same_v<Document, std::string>) {
+            return std::string{ reinterpret_cast<const char*>(encoded.data.data()), encoded.data.size() };
+        } else {
+            return encoded.data;
+        }
+    }
+};
+
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+template<>
+struct is_transcoder<raw_json_transcoder> : public std::true_type {
+};
+#endif
+} // namespace codec
+} // namespace couchbase

package/deps/couchbase-cxx-client/couchbase/codec/raw_string_transcoder.hxx

@@ -0,0 +1,72 @@
+/* -*- 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/codec/codec_flags.hxx>
+#include <couchbase/codec/encoded_value.hxx>
+#include <couchbase/codec/transcoder_traits.hxx>
+#include <couchbase/error_codes.hxx>
+
+#include <cstddef>
+#include <string>
+#include <string_view>
+#include <type_traits>
+#include <vector>
+
+namespace couchbase
+{
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+namespace core::utils
+{
+std::vector<std::byte>
+to_binary(std::string_view value) noexcept;
+} // namespace core::utils
+#endif
+
+namespace codec
+{
+class raw_string_transcoder
+{
+  public:
+    using document_type = std::string;
+
+    static auto encode(document_type document) -> encoded_value
+    {
+        return { core::utils::to_binary(document), codec_flags::string_common_flags };
+    }
+
+    template<typename Document = document_type, std::enable_if_t<std::is_same_v<Document, document_type>, bool> = true>
+    static auto decode(const encoded_value& encoded) -> Document
+    {
+        if (!codec_flags::has_common_flags(encoded.flags, codec_flags::string_common_flags)) {
+            throw std::system_error(errc::common::decoding_failure,
+                                    "raw_string_transcoder expects document to have STRING common flags, flags=" +
+                                      std::to_string(encoded.flags));
+        }
+
+        return std::string{ reinterpret_cast<const char*>(encoded.data.data()), encoded.data.size() };
+    }
+};
+
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+template<>
+struct is_transcoder<raw_string_transcoder> : public std::true_type {
+};
+#endif
+} // namespace codec
+} // namespace couchbase