couchbase 3.5.7 → 3.6.0

data/ext/couchbase/core/websocket_codec.hxx

@@ -0,0 +1,77 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ * Copyright 2024-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
+ *
+ *     https://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 <gsl/span>
+
+#include <cstddef>
+#include <memory>
+#include <string>
+#include <string_view>
+#include <vector>
+
+namespace couchbase::core
+{
+class websocket_codec;
+class websocket_handler;
+
+class websocket_callbacks
+{
+public:
+  websocket_callbacks() = default;
+  websocket_callbacks(const websocket_callbacks&) = default;
+  websocket_callbacks(websocket_callbacks&&) noexcept = default;
+  auto operator=(const websocket_callbacks&) -> websocket_callbacks& = default;
+  auto operator=(websocket_callbacks&&) noexcept -> websocket_callbacks& = default;
+  virtual ~websocket_callbacks() = default;
+
+  virtual void on_text(const websocket_codec& ws, gsl::span<std::byte> payload) = 0;
+  virtual void on_binary(const websocket_codec& ws, gsl::span<std::byte> payload) = 0;
+  virtual void on_ping(const websocket_codec& ws, gsl::span<std::byte> payload) = 0;
+  virtual void on_pong(const websocket_codec& ws, gsl::span<std::byte> payload) = 0;
+  virtual void on_close(const websocket_codec& ws, gsl::span<std::byte> payload) = 0;
+
+  virtual void on_ready(const websocket_codec& ws) = 0;
+  virtual void on_error(const websocket_codec& ws, const std::string& message) = 0;
+};
+
+class websocket_codec
+{
+public:
+  explicit websocket_codec(websocket_callbacks* callbacks);
+  websocket_codec(const websocket_codec&) = delete;
+  websocket_codec(websocket_codec&&) = delete;
+  auto operator=(const websocket_codec&) -> websocket_codec& = delete;
+  auto operator=(websocket_codec&&) noexcept -> websocket_codec& = delete;
+  ~websocket_codec();
+
+  [[nodiscard]] auto session_key() const -> const std::string&;
+
+  void feed(gsl::span<std::byte> chunk);
+  void feed(std::string_view chunk);
+
+  [[nodiscard]] auto text(std::string_view message) const -> std::vector<std::byte>;
+  [[nodiscard]] auto binary(gsl::span<std::byte> message) const -> std::vector<std::byte>;
+  [[nodiscard]] auto ping(gsl::span<std::byte> message = {}) const -> std::vector<std::byte>;
+  [[nodiscard]] auto pong(gsl::span<std::byte> message = {}) const -> std::vector<std::byte>;
+  [[nodiscard]] auto close(gsl::span<std::byte> message) const -> std::vector<std::byte>;
+
+private:
+  std::string session_key_;
+  websocket_callbacks* callbacks_;
+  std::unique_ptr<websocket_handler> handler_;
+};
+} // namespace couchbase::core

data/ext/couchbase/couchbase/analytics_options.hxx

@@ -246,7 +246,8 @@ struct analytics_options : public common_options<analytics_options> {
   }
 
   /**
-   * Set list of positional parameters for a query.
+   * Set list of positional parameters for a query. Any existing positional parameters will be
+   * overridden.
    *
    * @tparam Parameters types for the parameters
    * @param parameters the sequence of positional parameters. Each entry will be encoded into JSON.
@@ -260,14 +261,13 @@ struct analytics_options : public common_options<analytics_options> {
            std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
   auto positional_parameters(const Parameters&... parameters) -> analytics_options&
   {
-    named_parameters_.clear();
     positional_parameters_.clear();
     encode_positional_parameters<Serializer>(parameters...);
     return self();
   }
 
   /**
-   * Set list of named parameters for a query.
+   * Set list of named parameters for a query. Any existing named parameters will be overridden.
    *
    * @tparam Parameters types for the parameter pairs
    * @param parameters the sequence of name-value pairs. Each value will be encoded into JSON.
@@ -282,11 +282,77 @@ struct analytics_options : public common_options<analytics_options> {
   auto named_parameters(const Parameters&... parameters) -> analytics_options&
   {
     named_parameters_.clear();
-    positional_parameters_.clear();
     encode_named_parameters<Serializer>(parameters...);
     return self();
   }
 
+  /**
+   * Adds a positional parameter to the current list of positional parameters.
+   *
+   * @tparam Parameter type for the parameter.
+   * @param parameter the positional parameter. It will be encoded into JSON.
+   * @return this options builder for chaining purposes.
+   *
+   * @since 1.1.0
+   * @committed
+   */
+  template<typename Serializer = codec::tao_json_serializer,
+           typename Parameter,
+           std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
+  auto add_positional_parameter(const Parameter& parameter) -> analytics_options&
+  {
+    encode_positional_parameters<Serializer>(parameter);
+    return self();
+  }
+
+  /**
+   * Adds a named parameter to the current list of named parameters.
+   *
+   * @tparam Value type for the named parameter's value.
+   * @param name the named parameter's name
+   * @param value the named parameter's value. It will be encoded into JSON.
+   * @return this options builder for chaining purposes.
+   *
+   * @since 1.1.0
+   * @committed
+   */
+  template<typename Serializer = codec::tao_json_serializer,
+           typename Value,
+           std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
+  auto add_named_parameter(const std::string& name, const Value& value) -> analytics_options&
+  {
+    encode_named_parameters<Serializer>(std::make_pair(name, value));
+    return self();
+  }
+
+  /**
+   * Clears the list of positional parameters.
+   *
+   * @return this options builder for chaining purposes.
+   *
+   * @since 1.1.0
+   * @committed
+   */
+  auto clear_positional_parameters() -> analytics_options&
+  {
+    positional_parameters_.clear();
+    return self();
+  }
+
+  /**
+   * Clears the list of named parameters.
+   *
+   * @return this options builder for chaining purposes.
+   *
+   * @since 1.1.0
+   * @committed
+   */
+  auto clear_named_parameters() -> analytics_options&
+  {
+    named_parameters_.clear();
+    return self();
+  }
+
   /**
    * Set map of raw options for a query.
    *
@@ -325,7 +391,6 @@ struct analytics_options : public common_options<analytics_options> {
    */
   auto encoded_positional_parameters(std::vector<codec::binary> parameters) -> analytics_options&
   {
-    named_parameters_.clear();
     positional_parameters_ = std::move(parameters);
     return self();
   }
@@ -348,7 +413,6 @@ struct analytics_options : public common_options<analytics_options> {
     -> analytics_options&
   {
     named_parameters_ = std::move(parameters);
-    positional_parameters_.clear();
     return self();
   }
 

data/ext/couchbase/couchbase/application_telemetry_options.hxx

@@ -0,0 +1,124 @@
+/* -*- 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 <chrono>
+#include <cstddef>
+#include <string>
+
+namespace couchbase
+{
+class application_telemetry_options
+{
+public:
+  static constexpr std::chrono::milliseconds default_ping_interval{ std::chrono::seconds{ 30 } };
+  static constexpr std::chrono::milliseconds default_ping_timeout{ std::chrono::seconds{ 2 } };
+  static constexpr std::chrono::milliseconds default_backoff_interval{ std::chrono::hours{ 1 } };
+
+  /**
+   * Whether to enable application telemetry.
+   *
+   * @param enable true if the application service telemetry have to be enabled.
+   *
+   * @since 1.1.0
+   */
+  auto enable(bool enable) -> application_telemetry_options&
+  {
+    enabled_ = enable;
+    return *this;
+  }
+
+  /**
+   * How often the SDK should ping application service telemetry collector.
+   *
+   * @param interval ping interval in milliseconds.
+   *
+   * @since 1.1.0
+   */
+  auto ping_interval(std::chrono::milliseconds interval) -> application_telemetry_options&
+  {
+    ping_interval_ = interval;
+    return *this;
+  }
+
+  /**
+   * How long the SDK should wait for ping response (pong frame) back from application service
+   * telemetry collector.
+   *
+   * @param timeout ping timeout in milliseconds.
+   *
+   * @since 1.1.0
+   */
+  auto ping_timeout(std::chrono::milliseconds timeout) -> application_telemetry_options&
+  {
+    ping_timeout_ = timeout;
+    return *this;
+  }
+
+  /**
+   * Override the endpoint for the application service telementry.
+   *
+   * The endpoint must use WebSocket protocol and the string should start from `ws://` and might
+   * have URL path.
+   *
+   * @param endpoint connection string for the telementry collector.
+   *
+   * @since 1.1.0
+   */
+  auto override_endpoint(std::string endpoint) -> application_telemetry_options&
+  {
+    endpoint_ = std::move(endpoint);
+    return *this;
+  }
+
+  /**
+   * How long should the SDK wait between connection attempts to the collector to avoid performance
+   * and stability issues on the collector side.
+   *
+   * @param interval backoff interval in milliseconds
+   *
+   * @since 1.1.0
+   */
+  auto backoff_interval(std::chrono::milliseconds interval) -> application_telemetry_options&
+  {
+    backoff_interval_ = interval;
+    return *this;
+  }
+  struct built {
+    bool enabled;
+    std::chrono::milliseconds ping_interval;
+    std::chrono::milliseconds ping_timeout;
+    std::chrono::milliseconds backoff_interval;
+    std::string endpoint;
+  };
+
+  [[nodiscard]] auto build() const -> built
+  {
+    return {
+      enabled_, ping_interval_, ping_timeout_, backoff_interval_, endpoint_,
+    };
+  }
+
+private:
+  bool enabled_{ true };
+  std::chrono::milliseconds ping_interval_{ default_ping_interval };
+  std::chrono::milliseconds ping_timeout_{ default_ping_timeout };
+  std::chrono::milliseconds backoff_interval_{ default_backoff_interval };
+  std::string endpoint_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/cluster_options.hxx

@@ -17,6 +17,7 @@
 
 #pragma once
 
+#include <couchbase/application_telemetry_options.hxx>
 #include <couchbase/behavior_options.hxx>
 #include <couchbase/certificate_authenticator.hxx>
 #include <couchbase/compression_options.hxx>
@@ -221,6 +222,19 @@ public:
     return transactions_;
   }
 
+  /**
+   * Returns the Application Telemetry options.
+   *
+   * @return application telemetry options.
+   *
+   * @since 1.1.0
+   * @committed
+   */
+  [[nodiscard]] auto application_telemetry() -> application_telemetry_options&
+  {
+    return application_telemetry_;
+  }
+
   /**
    * Override default retry strategy
    *
@@ -254,6 +268,7 @@ public:
     behavior_options::built behavior;
     transactions::transactions_config::built transactions;
     std::shared_ptr<retry_strategy> default_retry_strategy;
+    application_telemetry_options::built application_telemetry;
   };
 
   [[nodiscard]] auto build() const -> built
@@ -274,6 +289,7 @@ public:
       behavior_.build(),
       transactions_.build(),
       default_retry_strategy_,
+      application_telemetry_.build(),
     };
   }
 
@@ -294,6 +310,7 @@ private:
   behavior_options behavior_{};
   transactions::transactions_config transactions_{};
   std::shared_ptr<retry_strategy> default_retry_strategy_{ nullptr };
+  application_telemetry_options application_telemetry_{};
 };
 
 #ifndef COUCHBASE_CXX_CLIENT_DOXYGEN

data/ext/couchbase/couchbase/error_codes.hxx

@@ -1142,6 +1142,7 @@ enum class transaction_op {
   rollback_not_permitted = 1317,
   transaction_already_aborted = 1318,
   transaction_already_committed = 1319,
+  document_unretrievable = 1320,
 
   /**
    * @internal

data/ext/couchbase/couchbase/logger.hxx

@@ -17,6 +17,8 @@
 
 #pragma once
 
+#include <functional>
+#include <string>
 #include <string_view>
 
 namespace couchbase::logger
@@ -31,6 +33,20 @@ enum class log_level {
   off,
 };
 
+struct log_location {
+  std::string file;
+  std::string function;
+  int line;
+};
+
+using log_callback = std::function<void(std::string_view, log_level, log_location)>;
+
+void
+register_log_callback(const log_callback& callback);
+
+void
+unregister_log_callback();
+
 void
 set_level(log_level level);
 

data/ext/couchbase/couchbase/management/bucket_settings.hxx

@@ -126,6 +126,7 @@ struct bucket_settings {
   std::optional<bool> history_retention_collection_default{};
   std::optional<std::uint32_t> history_retention_bytes;
   std::optional<std::uint32_t> history_retention_duration{};
+  std::optional<std::uint16_t> num_vbuckets{};
 
   /**
    * UNCOMMITTED: This API may change in the future

data/ext/couchbase/couchbase/query_options.hxx

@@ -450,7 +450,8 @@ struct query_options : public common_options<query_options> {
   }
 
   /**
-   * Set list of positional parameters for a query.
+   * Set list of positional parameters for a query. Any existing positional parameters will be
+   * overridden.
    *
    * @tparam Parameters types for the parameters
    * @param parameters the sequence of positional parameters. Each entry will be encoded into JSON.
@@ -464,14 +465,13 @@ struct query_options : public common_options<query_options> {
            std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
   auto positional_parameters(const Parameters&... parameters) -> query_options&
   {
-    named_parameters_.clear();
     positional_parameters_.clear();
     encode_positional_parameters<Serializer>(parameters...);
     return self();
   }
 
   /**
-   * Set list of named parameters for a query.
+   * Set list of named parameters for a query. Any existing named parameters will be overridden.
    *
    * @tparam Parameters types for the parameter pairs
    * @param parameters the sequence of name-value pairs. Each value will be encoded into JSON.
@@ -486,11 +486,77 @@ struct query_options : public common_options<query_options> {
   auto named_parameters(const Parameters&... parameters) -> query_options&
   {
     named_parameters_.clear();
-    positional_parameters_.clear();
     encode_named_parameters<Serializer>(parameters...);
     return self();
   }
 
+  /**
+   * Adds a positional parameter to the current list of positional parameters.
+   *
+   * @tparam Parameter type for the parameter.
+   * @param parameter the positional parameter. It will be encoded into JSON.
+   * @return this options builder for chaining purposes.
+   *
+   * @since 1.1.0
+   * @committed
+   */
+  template<typename Serializer = codec::tao_json_serializer,
+           typename Parameter,
+           std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
+  auto add_positional_parameter(const Parameter& parameter) -> query_options&
+  {
+    encode_positional_parameters<Serializer>(parameter);
+    return self();
+  }
+
+  /**
+   * Adds a named parameter to the current list of named parameters.
+   *
+   * @tparam Value type for the named parameter's value.
+   * @param name the named parameter's name
+   * @param value the named parameter's value. It will be encoded into JSON.
+   * @return this options builder for chaining purposes.
+   *
+   * @since 1.1.0
+   * @committed
+   */
+  template<typename Serializer = codec::tao_json_serializer,
+           typename Value,
+           std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
+  auto add_named_parameter(const std::string& name, const Value& value) -> query_options&
+  {
+    encode_named_parameters<Serializer>(std::make_pair(name, value));
+    return self();
+  }
+
+  /**
+   * Clears the list of positional parameters.
+   *
+   * @return this options builder for chaining purposes.
+   *
+   * @since 1.1.0
+   * @committed
+   */
+  auto clear_positional_parameters() -> query_options&
+  {
+    positional_parameters_.clear();
+    return self();
+  }
+
+  /**
+   * Clears the list of named parameters.
+   *
+   * @return this options builder for chaining purposes.
+   *
+   * @since 1.1.0
+   * @committed
+   */
+  auto clear_named_parameters() -> query_options&
+  {
+    named_parameters_.clear();
+    return self();
+  }
+
   /**
    * Set map of raw options for a query.
    *
@@ -529,7 +595,6 @@ struct query_options : public common_options<query_options> {
    */
   auto encoded_positional_parameters(std::vector<codec::binary> parameters) -> query_options&
   {
-    named_parameters_.clear();
     positional_parameters_ = std::move(parameters);
     return self();
   }
@@ -552,7 +617,6 @@ struct query_options : public common_options<query_options> {
     -> query_options&
   {
     named_parameters_ = std::move(parameters);
-    positional_parameters_.clear();
     return self();
   }
 

data/ext/couchbase/couchbase/transactions/async_attempt_context.hxx

@@ -15,6 +15,12 @@
  */
 #pragma once
 
+#include <couchbase/transactions/transaction_get_multi_options.hxx>
+#include <couchbase/transactions/transaction_get_multi_replicas_from_preferred_server_group_options.hxx>
+#include <couchbase/transactions/transaction_get_multi_replicas_from_preferred_server_group_result.hxx>
+#include <couchbase/transactions/transaction_get_multi_replicas_from_preferred_server_group_spec.hxx>
+#include <couchbase/transactions/transaction_get_multi_result.hxx>
+#include <couchbase/transactions/transaction_get_multi_spec.hxx>
 #include <couchbase/transactions/transaction_get_result.hxx>
 #include <couchbase/transactions/transaction_query_options.hxx>
 #include <couchbase/transactions/transaction_query_result.hxx>
@@ -40,8 +46,14 @@ using async_err_handler = std::function<void(error)>;
  */
 class async_attempt_context
 {
-
 public:
+  virtual ~async_attempt_context() = default;
+  async_attempt_context() = default;
+  async_attempt_context(async_attempt_context&&) noexcept = default;
+  async_attempt_context(const async_attempt_context&) = default;
+  auto operator=(async_attempt_context&&) -> async_attempt_context& = default;
+  auto operator=(const async_attempt_context&) -> async_attempt_context& = default;
+
   /**
    * Get document from a collection.
    *
@@ -80,6 +92,18 @@ public:
                                                        const std::string& id,
                                                        async_result_handler&& handler) = 0;
 
+  virtual void get_multi(
+    const std::vector<transaction_get_multi_spec>& specs,
+    const transaction_get_multi_options& options,
+    std::function<void(error, std::optional<transaction_get_multi_result>)>&& cb) = 0;
+
+  virtual void get_multi_replicas_from_preferred_server_group(
+    const std::vector<transaction_get_multi_replicas_from_preferred_server_group_spec>& specs,
+    const transaction_get_multi_replicas_from_preferred_server_group_options& options,
+    std::function<void(
+      error,
+      std::optional<transaction_get_multi_replicas_from_preferred_server_group_result>)>&& cb) = 0;
+
   /**
    * Remove a document from a collection.
    *
@@ -114,7 +138,8 @@ public:
               Document&& content,
               async_result_handler&& handler)
   {
-    return insert_raw(coll, id, Transcoder::encode(content), std::move(handler));
+    return insert_raw(
+      coll, id, Transcoder::encode(std::forward<Document>(content)), std::move(handler));
   }
   /**
    * Replace the contents of a document in a collection.
@@ -134,7 +159,8 @@ public:
            std::enable_if_t<!std::is_same_v<codec::encoded_value, Document>, bool> = true>
   void replace(transaction_get_result doc, Document&& content, async_result_handler&& handler)
   {
-    return replace_raw(std::move(doc), Transcoder::encode(content), std::move(handler));
+    return replace_raw(
+      std::move(doc), Transcoder::encode(std::forward<Document>(content)), std::move(handler));
   }
   /**
    * Perform a query, within a scope.
@@ -178,8 +204,6 @@ public:
     return query(std::move(statement), {}, std::move(handler));
   }
 
-  virtual ~async_attempt_context() = default;
-
 protected:
   /** @private */
   virtual void insert_raw(const collection& coll,

data/ext/couchbase/couchbase/transactions/attempt_context.hxx

@@ -15,11 +15,18 @@
  */
 #pragma once
 
+#include <couchbase/transactions/transaction_get_multi_options.hxx>
+#include <couchbase/transactions/transaction_get_multi_replicas_from_preferred_server_group_options.hxx>
+#include <couchbase/transactions/transaction_get_multi_replicas_from_preferred_server_group_result.hxx>
+#include <couchbase/transactions/transaction_get_multi_replicas_from_preferred_server_group_spec.hxx>
+#include <couchbase/transactions/transaction_get_multi_result.hxx>
+#include <couchbase/transactions/transaction_get_multi_spec.hxx>
 #include <couchbase/transactions/transaction_get_result.hxx>
 #include <couchbase/transactions/transaction_query_options.hxx>
 #include <couchbase/transactions/transaction_query_result.hxx>
 
 #include <stdexcept>
+#include <vector>
 
 namespace couchbase
 {
@@ -62,8 +69,8 @@ public:
    *
    * @see transactions::transaction_get_result for more complete example
    */
-  virtual auto get(const couchbase::collection& coll,
-                   const std::string& id) -> std::pair<error, transaction_get_result> = 0;
+  virtual auto get(const couchbase::collection& coll, const std::string& id)
+    -> std::pair<error, transaction_get_result> = 0;
 
   /**
    * Get a document copy from the selected server group.
@@ -91,6 +98,17 @@ public:
                                                        const std::string& id)
     -> std::pair<error, transaction_get_result> = 0;
 
+  virtual auto get_multi(const std::vector<transaction_get_multi_spec>& specs,
+                         const transaction_get_multi_options& options)
+    -> std::pair<error, std::optional<transaction_get_multi_result>> = 0;
+
+  virtual auto get_multi_replicas_from_preferred_server_group(
+    const std::vector<transaction_get_multi_replicas_from_preferred_server_group_spec>& specs,
+    const transaction_get_multi_replicas_from_preferred_server_group_options& options)
+    -> std::pair<
+      error,
+      std::optional<transaction_get_multi_replicas_from_preferred_server_group_result>> = 0;
+
   /**
    * Insert a document into a collection.
    *
@@ -109,9 +127,8 @@ public:
   template<typename Transcoder = codec::default_json_transcoder,
            typename Document,
            std::enable_if_t<!std::is_same_v<codec::encoded_value, Document>, bool> = true>
-  auto insert(const couchbase::collection& coll,
-              const std::string& id,
-              const Document& content) -> std::pair<error, transaction_get_result>
+  auto insert(const couchbase::collection& coll, const std::string& id, const Document& content)
+    -> std::pair<error, transaction_get_result>
   {
     codec::encoded_value data;
     try {
@@ -151,8 +168,8 @@ public:
   template<typename Transcoder = codec::default_json_transcoder,
            typename Document,
            std::enable_if_t<!std::is_same_v<codec::encoded_value, Document>, bool> = true>
-  auto replace(const transaction_get_result& doc,
-               const Document& content) -> std::pair<error, transaction_get_result>
+  auto replace(const transaction_get_result& doc, const Document& content)
+    -> std::pair<error, transaction_get_result>
   {
     codec::encoded_value data;
     try {