couchbase 4.2.9 → 4.2.10

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

@@ -22,11 +22,14 @@
 #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>
@@ -141,6 +144,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 @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.
@@ -159,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.
@@ -175,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.
      *
@@ -207,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.
      *

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

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

@@ -20,6 +20,7 @@
 #include <couchbase/common_options.hxx>
 #include <couchbase/manager_error_context.hxx>
 
+#include <cstdint>
 #include <functional>
 #include <optional>
 
@@ -27,17 +28,44 @@ namespace couchbase
 {
 struct create_collection_options : public common_options<create_collection_options> {
   public:
+    /**
+     * Immutable value object representing consistent options.
+     *
+     * @since 1.0.0
+     * @internal
+     */
     struct built : public common_options<create_collection_options>::built {
     };
 
+    /**
+     * Validates the 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 settings to use when creating the collection
+ */
 struct create_collection_settings {
-    std::uint32_t max_expiry{ 0 };
+    /**
+     * The maximum expiry, in seconds, for documents in this collection. Values greater than or equal to -1 are valid.
+     * Value of 0 sets max_expiry to the bucket-level setting and value of -1 to set it as no-expiry.
+     */
+    std::int32_t max_expiry{ 0 };
+
+    /**
+     * Whether history retention should be enabled. If unset, the bucket-level setting is used.
+     */
     std::optional<bool> history{};
 };
 

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

@@ -0,0 +1,75 @@
+/* -*- 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.
+ */
+
+#pragma once
+
+#include <couchbase/common_options.hxx>
+#include <couchbase/diagnostics_result.hxx>
+
+#include <optional>
+#include <utility>
+
+namespace couchbase
+{
+struct diagnostics_options : public common_options<diagnostics_options> {
+    /**
+     * Sets a custom report ID that will be used in the report. If no report ID is provided, the client will generate a
+     * unique one.
+     *
+     * @param report_id the report ID that should be used.
+     * @return reference to this object, for use in chaining.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    auto report_id(std::string report_id) -> diagnostics_options&
+    {
+        report_id_ = std::move(report_id);
+        return self();
+    }
+
+    /**
+     * Immutable value object representing consistent options.
+     *
+     * @since 1.0.0
+     * @internal
+     */
+    struct built : public common_options<diagnostics_options>::built {
+        std::optional<std::string> report_id;
+    };
+
+    /**
+     * Validates the 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(), report_id_ };
+    }
+
+  private:
+    std::optional<std::string> report_id_{};
+};
+
+using diagnostics_handler = std::function<void(diagnostics_result)>;
+} // namespace couchbase

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

@@ -0,0 +1,124 @@
+/* -*- 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.
+ */
+
+#pragma once
+
+#include <couchbase/codec/tao_json_serializer.hxx>
+#include <couchbase/endpoint_diagnostics.hxx>
+#include <couchbase/service_type.hxx>
+
+#include <cstdint>
+#include <map>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace couchbase
+{
+class diagnostics_result
+{
+  public:
+    /**
+     * @since 1.0.0
+     * @internal
+     */
+    diagnostics_result() = default;
+
+    /**
+     * @since 1.0.0
+     * @internal
+     */
+    diagnostics_result(std::string id,
+                       std::uint16_t version,
+                       std::string sdk,
+                       std::map<service_type, std::vector<endpoint_diagnostics>> endpoints)
+      : id_{ std::move(id) }
+      , version_{ version }
+      , sdk_{ std::move(sdk) }
+      , endpoints_{ std::move(endpoints) }
+    {
+    }
+
+    /**
+     * Returns the ID of this report.
+     *
+     * @return the report ID.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto id() const -> std::string
+    {
+        return id_;
+    }
+
+    /**
+     * Returns the version of this report (useful when exporting to JSON).
+     *
+     * @return the report version
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto version() const -> std::uint16_t
+    {
+        return version_;
+    }
+
+    /**
+     * Returns the identifier of this SDK (useful when exporting to JSON).
+     *
+     * @return the SDK identifier.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto sdk() const -> std::string
+    {
+        return sdk_;
+    }
+
+    /**
+     * Returns the diagnostics for each individual endpoint, organised by service type.
+     *
+     * @return the service type to endpoint diagnostics reports map.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto endpoints() const -> std::map<service_type, std::vector<endpoint_diagnostics>>
+    {
+        return endpoints_;
+    }
+
+    /**
+     * Exports the diagnostics report as JSON.
+     *
+     * @return the JSON report.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto as_json() const -> codec::tao_json_serializer::document_type;
+
+  private:
+    std::string id_{};
+    std::uint16_t version_{};
+    std::string sdk_{};
+    std::map<service_type, std::vector<endpoint_diagnostics>> endpoints_{};
+};
+} // namespace couchbase