couchbase 4.2.9 → 4.2.11-rc.1

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

@@ -53,8 +53,7 @@ class collection_query_index_manager
 {
   public:
     /**
-     * Get all indexes within a collection.
-     *
+     * Get all indexes within the collection.
      *
      * @param options optional parameters
      * @param handler the handler that implements @ref get_all_query_indexes_handler
@@ -64,13 +63,23 @@ class collection_query_index_manager
      */
     void get_all_indexes(const get_all_query_indexes_options& options, get_all_query_indexes_handler&& handler) const;
 
+    /**
+     * Get all indexes within the collection..
+     *
+     * @param options optional parameters
+     * @return future object that carries result of the operation
+     *
+     * @since 1.0.0
+     * @committed
+     */
     [[nodiscard]] auto get_all_indexes(const get_all_query_indexes_options& options) const
       -> std::future<std::pair<manager_error_context, std::vector<couchbase::management::query_index>>>;
+
     /**
      * Create an index on the collection.
      *
      * @param index_name name of the index
-     * @param fields the fields to create the index over
+     * @param keys the keys to create the index over
      * @param options optional parameters
      * @param handler the handler that implements @ref create_query_index_handler
      *
@@ -78,16 +87,26 @@ class collection_query_index_manager
      * @committed
      */
     void create_index(std::string index_name,
-                      std::vector<std::string> fields,
+                      std::vector<std::string> keys,
                       const create_query_index_options& options,
                       create_query_index_handler&& handler) const;
 
-    [[nodiscard]] auto create_index(std::string index_name,
-                                    std::vector<std::string> fields,
-                                    const create_query_index_options& options) const -> std::future<manager_error_context>;
+    /**
+     * Create an index on the collection.
+     *
+     * @param index_name name of the index
+     * @param keys the keys to create the index over
+     * @param options optional parameters
+     * @return future object that carries result of the operation
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto create_index(std::string index_name, std::vector<std::string> keys, const create_query_index_options& options) const
+      -> std::future<manager_error_context>;
 
     /**
-     * Create a primary index on a collection.
+     * Create a primary index on the collection.
      *
      * @param options optional parameters
      * @param handler the handler that implements @ref create_query_index_handler
@@ -97,10 +116,19 @@ class collection_query_index_manager
      */
     void create_primary_index(const create_primary_query_index_options& options, create_query_index_handler&& handler) const;
 
+    /**
+     * Create a primary index on the collection.
+     *
+     * @param options optional parameters
+     * @return future object that carries result of the operation
+     *
+     * @since 1.0.0
+     * @committed
+     */
     [[nodiscard]] auto create_primary_index(const create_primary_query_index_options& options) const -> std::future<manager_error_context>;
 
     /**
-     * Drop primary index on a collection.
+     * Drop primary index on the collection.
      *
      * @param options optional parameters
      * @param handler the handler that implements @ref drop_query_index_handler
@@ -110,10 +138,19 @@ class collection_query_index_manager
      */
     void drop_primary_index(const drop_primary_query_index_options& options, drop_query_index_handler&& handler) const;
 
+    /**
+     * Drop primary index on the collection.
+     *
+     * @param options optional parameters
+     * @return future object that carries result of the operation
+     *
+     * @since 1.0.0
+     * @committed
+     */
     [[nodiscard]] auto drop_primary_index(const drop_primary_query_index_options& options) const -> std::future<manager_error_context>;
 
     /**
-     * Drop index in collection.
+     * Drop specified query index in the collection.
      *
      * @param index_name name of the index to drop
      * @param options optional parameters
@@ -124,14 +161,25 @@ class collection_query_index_manager
      */
     void drop_index(std::string index_name, const drop_query_index_options& options, drop_query_index_handler&& handler) const;
 
+    /**
+     * Drop specified query index in the collection.
+     *
+     * @param index_name name of the index to drop
+     * @param options optional parameters
+     * @return future object that carries result of the operation
+     *
+     * @since 1.0.0
+     * @committed
+     */
     [[nodiscard]] auto drop_index(std::string index_name, const drop_query_index_options& options) const
       -> std::future<manager_error_context>;
+
     /**
      * Builds all currently deferred indexes in this collection.
      *
      * By default, this method will build the indexes on the collection.
      *
-     * @param options the custom options
+     * @param options optional parameters
      * @param handler the handler that implements @ref build_deferred_query_indexes_handler
      *
      * @since 1.0.0
@@ -139,6 +187,17 @@ class collection_query_index_manager
      */
     void build_deferred_indexes(const build_query_index_options& options, build_deferred_query_indexes_handler&& handler) const;
 
+    /**
+     * Builds all currently deferred indexes in this collection.
+     *
+     * By default, this method will build the indexes on the collection.
+     *
+     * @param options optional parameters
+     * @return future object that carries result of the operation
+     *
+     * @since 1.0.0
+     * @committed
+     */
     [[nodiscard]] auto build_deferred_indexes(const build_query_index_options& options) const -> std::future<manager_error_context>;
 
     /**
@@ -155,6 +214,16 @@ class collection_query_index_manager
                        const watch_query_indexes_options& options,
                        watch_query_indexes_handler&& handler) const;
 
+    /**
+     * Polls the state of a set of indexes, until they all are online.
+     *
+     * @param index_names names of the indexes to watch
+     * @param options optional parameters
+     * @return future object that carries result of the operation
+     *
+     * @since 1.0.0
+     * @committed
+     */
     [[nodiscard]] auto watch_indexes(std::vector<std::string> index_names, const watch_query_indexes_options& options) const
       -> std::future<manager_error_context>;
 

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

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

@@ -0,0 +1,206 @@
+/* -*- 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/service_type.hxx>
+
+#include <chrono>
+#include <optional>
+#include <string>
+#include <utility>
+
+namespace couchbase
+{
+enum class endpoint_state {
+    /**
+     * The endpoint is connected and ready.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    connected,
+
+    /**
+     * The endpoint is disconnected but trying to connect right now.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    connecting,
+
+    /**
+     * The endpoint is disconnected (not reachable) and not trying to connect.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    disconnected,
+
+    /**
+     * The endpoint is currently disconnecting.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    disconnecting,
+};
+
+class endpoint_diagnostics
+{
+  public:
+    endpoint_diagnostics() = default;
+
+    /**
+     * @since 1.0.0
+     * @internal
+     */
+    endpoint_diagnostics(service_type type,
+                         std::string id,
+                         std::optional<std::chrono::microseconds> last_activity,
+                         std::string local,
+                         std::string remote,
+                         std::optional<std::string> endpoint_namespace,
+                         endpoint_state state,
+                         std::optional<std::string> details)
+      : type_{ type }
+      , id_{ std::move(id) }
+      , last_activity_{ last_activity }
+      , local_{ std::move(local) }
+      , remote_{ std::move(remote) }
+      , namespace_{ std::move(endpoint_namespace) }
+      , state_{ state }
+      , details_{ std::move(details) }
+    {
+    }
+
+    /**
+     * Returns the service type for this endpoint.
+     *
+     * @return the service type.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto type() const -> service_type
+    {
+        return type_;
+    }
+
+    /**
+     *
+     * Returns the ID for this endpoint.
+     *
+     * @return the endpoint ID.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto id() const -> std::string
+    {
+        return id_;
+    }
+
+    /**
+     * Returns the time since the last activity, if there has been one.
+     *
+     * @return the duration since the last activity.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto last_activity() const -> std::optional<std::chrono::microseconds>
+    {
+        return last_activity_;
+    }
+
+    /**
+     * Returns the local socket address for this endpoint.
+     *
+     * @return the local socket address.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto local() const -> std::string
+    {
+        return local_;
+    }
+
+    /**
+     * Returns the remote socket address for this endpoint.
+     *
+     * @return the remote socket address.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto remote() const -> std::string
+    {
+        return remote_;
+    }
+
+    /**
+     * Returns the namespace of this endpoint (likely the bucket name if present).
+     *
+     * @return the namespace.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto endpoint_namespace() const -> std::optional<std::string>
+    {
+        return namespace_;
+    }
+
+    /**
+     * Returns the current state of the endpoint.
+     *
+     * @return the endpoint state.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto state() const -> endpoint_state
+    {
+        return state_;
+    }
+
+    /**
+     * Returns any additional details about the endpoint, if available.
+     *
+     * @return endpoint details.
+     *
+     * @since 1.0.0
+     * @committed
+     */
+    [[nodiscard]] auto details() const -> std::optional<std::string>
+    {
+        return details_;
+    }
+
+  private:
+    service_type type_{};
+    std::string id_{};
+    std::optional<std::chrono::microseconds> last_activity_{};
+    std::string local_{};
+    std::string remote_{};
+    std::optional<std::string> namespace_{};
+    endpoint_state state_{};
+    std::optional<std::string> details_{};
+};
+} // namespace couchbase