couchbase 3.8.0 → 3.8.2

data/ext/couchbase/core/transactions/waitable_op_list.hxx

@@ -79,6 +79,15 @@ public:
     // we have the lock.  Block all further ops
     allow_ops_ = false;
   }
+  // Peek at whether query mode has already been entered.  Briefly acquires mutex_ but, unlike
+  // get_mode(), never waits on cv_query_ for the query node to be set, so it returns immediately.
+  // Used by defensive invariant checks: a KV mutation must never be staged once query mode is
+  // entered.
+  auto query_mode_entered() const -> bool
+  {
+    const std::scoped_lock lock(mutex_);
+    return mode_.mode == attempt_mode::modes::QUERY;
+  }
   auto get_mode() -> attempt_mode
   {
     std::unique_lock<std::mutex> lock(mutex_);
@@ -143,8 +152,10 @@ public:
   {
     // when begin work errors out, it is fatal, so reset to kv mode here, allowing
     // rollback to function properly.
-    std::unique_lock<std::mutex> lock;
+    const std::scoped_lock lock(mutex_);
     mode_.mode = attempt_mode::modes::KV;
+    // query_node is intentionally left populated: a retry runs with a fresh waitable_op_list, and
+    // get_mode()'s wait predicate keys on query_node, so clearing it here would serve no purpose.
     cv_query_.notify_all();
   }
 
@@ -199,6 +210,6 @@ private:
   std::condition_variable cv_ops_;
   std::condition_variable cv_query_;
   std::condition_variable cv_in_flight_;
-  std::mutex mutex_;
+  mutable std::mutex mutex_;
 };
 } // namespace couchbase::core::transactions

data/ext/couchbase/core/utils/contains_string.cxx

@@ -0,0 +1,61 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   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.
+ */
+
+#include "contains_string.hxx"
+
+namespace couchbase::core::utils
+{
+
+namespace
+{
+constexpr auto ascii_lower = [](unsigned char c) -> unsigned char {
+  return (c >= 'A' && c <= 'Z') ? static_cast<unsigned char>(c + ('a' - 'A')) : c;
+};
+} // namespace
+
+auto
+contains_string(std::string_view input, std::string_view substr, bool ignore_case) -> bool
+{
+  if (substr.empty()) {
+    return true;
+  }
+
+  if (input.empty() || substr.size() > input.size()) {
+    return false;
+  }
+
+  if (!ignore_case) {
+    return input.find(substr) != std::string_view::npos;
+  }
+
+  const auto end = input.size() - substr.size() + 1;
+  for (std::size_t i = 0; i < end; i++) {
+    bool match = true;
+    for (std::size_t j = 0; j < substr.size(); j++) {
+      if (ascii_lower(static_cast<unsigned char>(input[i + j])) !=
+          ascii_lower(static_cast<unsigned char>(substr[j]))) {
+        match = false;
+        break;
+      }
+    }
+    if (match) {
+      return true;
+    }
+  }
+  return false;
+}
+} // namespace couchbase::core::utils

data/ext/couchbase/core/utils/contains_string.hxx

@@ -0,0 +1,26 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   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 <string_view>
+
+namespace couchbase::core::utils
+{
+auto
+contains_string(std::string_view input, std::string_view substr, bool ignore_case = false) -> bool;
+} // namespace couchbase::core::utils

data/ext/couchbase/couchbase/cluster.hxx

@@ -97,6 +97,39 @@ public:
   auto operator=(const cluster& other) -> cluster& = default;
   auto operator=(cluster&& other) -> cluster& = default;
 
+  /**
+   * Notify the cluster of a fork-related event, so it can keep its I/O usable
+   * across @c fork().
+   *
+   * Call it three times, in this order: @ref fork_event::prepare in the parent
+   * before forking, then @ref fork_event::child in the child and @ref
+   * fork_event::parent in the parent.
+   *
+   * NOTE: @ref fork_event::child reconnects this cluster on a fresh set of
+   * sockets, because the inherited ones belong to the parent. Any @ref bucket,
+   * @ref scope or @ref collection handle obtained before the fork still refers to
+   * the pre-fork connections, so in the child those handles must be re-acquired
+   * from the cluster -- using a stale one fails with @ref
+   * errc::network::cluster_closed. Handles held in the parent stay valid.
+   *
+   * This function must not be called while operations are in flight on this
+   * cluster from another thread.
+   *
+   * On platforms without @c fork(), Windows in particular, this function does
+   * nothing. It remains callable everywhere so that portable code does not have to
+   * guard the calls, but nothing about the cluster changes.
+   *
+   * @param event the fork-related event that is about to happen, or just happened.
+   *
+   * @throws std::system_error if the I/O backend cannot be carried across the fork.
+   * There is no recovery for this: the cluster's io_context is unusable afterwards
+   * and the only thing left to do with the cluster is destroy it. It is reported
+   * rather than swallowed because a caller that went on using such a cluster would
+   * be operating on a reactor that no longer tracks its sockets.
+   *
+   * @since 1.0.0
+   * @uncommitted
+   */
   void notify_fork(fork_event event);
 
   void close(std::function<void()>&& handler);

data/ext/couchbase/couchbase/collection.hxx

@@ -35,6 +35,8 @@
 #include <couchbase/lookup_in_specs.hxx>
 #include <couchbase/mutate_in_options.hxx>
 #include <couchbase/mutate_in_specs.hxx>
+#include <couchbase/node_id_for_options.hxx>
+#include <couchbase/node_ids_options.hxx>
 #include <couchbase/query_options.hxx>
 #include <couchbase/remove_options.hxx>
 #include <couchbase/replace_options.hxx>
@@ -1090,6 +1092,77 @@ public:
   [[nodiscard]] auto scan(const scan_type& scan_type, const scan_options& options = {}) const
     -> std::future<std::pair<error, scan_result>>;
 
+  /**
+   * Resolves a document key to the identity of the cluster node that currently
+   * owns it, using the client-side vBucket map (no network round-trip).
+   *
+   * @param document_id the document id to resolve
+   * @param options options to customize the request
+   * @param handler the handler that receives the result
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  void node_id_for(std::string document_id,
+                   const node_id_for_options& options,
+                   node_id_for_handler&& handler) const;
+
+  /**
+   * Resolves a document key to the identity of the cluster node that currently
+   * owns it, using the client-side vBucket map (no network round-trip).
+   *
+   * @param document_id the document id to resolve
+   * @param options options to customize the request
+   * @return future carrying the error (if any) and node_id
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_id_for(std::string document_id,
+                                 const node_id_for_options& options = {}) const
+    -> std::future<std::pair<error, node_id>>;
+
+  /**
+   * Returns the set of cluster nodes that currently serve key-value
+   * traffic for this collection's bucket, drawn from the client-side
+   * topology snapshot (no network round-trip).
+   *
+   * Each entry corresponds to one cluster node and is the same node_id
+   * the SDK reports on KV results and errors that touched that node, so
+   * the returned set is directly comparable to the keys of any
+   * application-side state that is keyed by node_id (e.g. a per-node
+   * circuit breaker registry). A periodic sweep that diffs the
+   * registry's keys against this set is the canonical way to retire
+   * tracker state for a node that has been removed from the cluster
+   * topology.
+   *
+   * Nodes that do not expose a key-value port for the configured
+   * transport (TLS or plain) are excluded from the returned set, since
+   * they do not serve KV operations and therefore have no meaningful
+   * identity from the SDK's point of view.
+   *
+   * @param options options to customize the request
+   * @param handler the handler that receives the result
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  void node_ids(const node_ids_options& options, node_ids_handler&& handler) const;
+
+  /**
+   * Returns the set of cluster nodes that currently serve key-value
+   * traffic for this collection's bucket, drawn from the client-side
+   * topology snapshot (no network round-trip).
+   *
+   * @param options options to customize the request
+   * @return future carrying the error (if any) and the set of node_ids
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_ids(const node_ids_options& options = {}) const
+    -> std::future<std::pair<error, std::vector<node_id>>>;
+
   [[nodiscard]] auto query_indexes() const -> collection_query_index_manager;
 
 private:

data/ext/couchbase/couchbase/error.hxx

@@ -18,6 +18,7 @@
 #pragma once
 
 #include <couchbase/error_context.hxx>
+#include <couchbase/node_id.hxx>
 
 #include <memory>
 #include <optional>
@@ -32,12 +33,26 @@ public:
   error() = default;
   error(std::error_code ec, std::string message = {}, error_context ctx = {});
   error(std::error_code ec, std::string message, error_context ctx, error cause);
+  error(std::error_code ec, std::string message, error_context ctx, couchbase::node_id node_id);
 
   [[nodiscard]] auto ec() const -> std::error_code;
   [[nodiscard]] auto message() const -> const std::string&;
   [[nodiscard]] auto ctx() const -> const error_context&;
   [[nodiscard]] auto cause() const -> std::optional<error>;
 
+  /**
+   * Returns the identity of the cluster node where the error occurred.
+   *
+   * The returned node_id is default-constructed (falsy) when the node
+   * could not be determined (e.g. for non-KV errors).
+   *
+   * @return identity of the node that returned the error
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_id() const -> const couchbase::node_id&;
+
   explicit operator bool() const;
   auto operator==(const error& other) const -> bool;
 
@@ -46,6 +61,7 @@ private:
   std::string message_{};
   error_context ctx_{};
   std::shared_ptr<error> cause_{};
+  couchbase::node_id node_id_{};
 };
 
 } // namespace couchbase

data/ext/couchbase/couchbase/node_id.hxx

@@ -0,0 +1,123 @@
+/* -*- 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
+ *
+ *       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 <cstdint>
+#include <functional>
+#include <string>
+
+namespace couchbase
+{
+
+/**
+ * Uniquely identifies a cluster node.
+ *
+ * On Couchbase Server 8.0.1+ the identifier is the server-assigned node UUID.
+ * On older releases, a stable opaque token is derived from the node's hostname
+ * and management port.
+ *
+ * The type is equality-comparable, ordered, and hashable.
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
+class node_id
+{
+public:
+  /**
+   * Creates an empty (invalid) node_id.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  node_id() = default;
+
+  /**
+   * User-facing identifier string.
+   *
+   * Returns node_uuid when the server provides one, otherwise a stable
+   * hex-encoded hash derived from hostname and management port.
+   *
+   * @return opaque identifier string (empty for default-constructed instances)
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto id() const -> const std::string&;
+
+  /**
+   * The server-assigned node UUID (empty on servers before 8.0.1).
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_uuid() const -> const std::string&;
+
+  /**
+   * The hostname of the node.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto hostname() const -> const std::string&;
+
+  /**
+   * The port of the node's key-value service.
+   *
+   * This reflects the port actually used by the client: the TLS port when the
+   * cluster connection is TLS-enabled, otherwise the plain port.
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto port() const -> std::uint16_t;
+
+  /**
+   * Returns true when the node_id was properly initialized (not default-constructed).
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  explicit operator bool() const;
+
+  auto operator==(const node_id& other) const -> bool;
+  auto operator!=(const node_id& other) const -> bool;
+  auto operator<(const node_id& other) const -> bool;
+
+private:
+  friend class internal_node_id;
+
+  node_id(std::string node_uuid, std::string hostname, std::uint16_t port);
+
+  std::string node_uuid_{};
+  std::string hostname_{};
+  std::uint16_t port_{ 0 };
+  // Computed once at construction: node_uuid_ if non-empty, otherwise a
+  // deterministic hex-encoded CRC32 hash of "hostname:port".
+  std::string id_{};
+};
+
+} // namespace couchbase
+
+template<>
+struct std::hash<couchbase::node_id> {
+  auto operator()(const couchbase::node_id& nid) const noexcept -> std::size_t
+  {
+    return std::hash<std::string>{}(nid.id());
+  }
+};

data/ext/couchbase/couchbase/node_id_for_options.hxx

@@ -0,0 +1,61 @@
+/* -*- 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
+ *
+ *       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/error.hxx>
+#include <couchbase/node_id.hxx>
+
+#include <functional>
+
+namespace couchbase
+{
+
+/**
+ * Options for @ref collection#node_id_for().
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
+struct node_id_for_options : public common_options<node_id_for_options> {
+  /**
+   * Immutable value object representing consistent options.
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  struct built : public common_options<node_id_for_options>::built {
+  };
+
+  /**
+   * Validates options and returns them as an immutable value.
+   *
+   * @return consistent options as an immutable value
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> built
+  {
+    return { build_common_options() };
+  }
+};
+
+using node_id_for_handler = std::function<void(error, node_id)>;
+
+} // namespace couchbase

data/ext/couchbase/couchbase/node_ids_options.hxx

@@ -0,0 +1,62 @@
+/* -*- 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
+ *
+ *       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/error.hxx>
+#include <couchbase/node_id.hxx>
+
+#include <functional>
+#include <vector>
+
+namespace couchbase
+{
+
+/**
+ * Options for @ref collection#node_ids().
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
+struct node_ids_options : public common_options<node_ids_options> {
+  /**
+   * Immutable value object representing consistent options.
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  struct built : public common_options<node_ids_options>::built {
+  };
+
+  /**
+   * Validates options and returns them as an immutable value.
+   *
+   * @return consistent options as an immutable value
+   *
+   * @since 1.3.2
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> built
+  {
+    return { build_common_options() };
+  }
+};
+
+using node_ids_handler = std::function<void(error, std::vector<node_id>)>;
+
+} // namespace couchbase

data/ext/couchbase/couchbase/result.hxx

@@ -18,6 +18,9 @@
 #pragma once
 
 #include <couchbase/cas.hxx>
+#include <couchbase/node_id.hxx>
+
+#include <utility>
 
 namespace couchbase
 {
@@ -48,6 +51,19 @@ public:
   {
   }
 
+  /**
+   * @param cas
+   * @param node_id identity of the node that served the request
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  result(couchbase::cas cas, couchbase::node_id node_id)
+    : cas_(cas)
+    , node_id_(std::move(node_id))
+  {
+  }
+
   /**
    * @return
    *
@@ -59,8 +75,34 @@ public:
     return cas_;
   }
 
+  /**
+   * Returns the identity of the cluster node that served this request.
+   *
+   * The returned node_id is default-constructed (falsy) when the node
+   * could not be determined.
+   *
+   * @return identity of the serving node
+   *
+   * @since 1.3.2
+   * @uncommitted
+   */
+  [[nodiscard]] auto node_id() const -> const couchbase::node_id&
+  {
+    return node_id_;
+  }
+
+  /**
+   * @since 1.3.2
+   * @internal
+   */
+  void node_id(couchbase::node_id id)
+  {
+    node_id_ = std::move(id);
+  }
+
 private:
   couchbase::cas cas_{ 0U };
+  couchbase::node_id node_id_{};
 };
 
 } // namespace couchbase

data/ext/rcb_crud.cxx

@@ -734,6 +734,7 @@ cb_Backend_document_append(VALUE self,
     cb_extract_content(req, content);
     cb_extract_timeout(req, options);
     cb_extract_durability_level(req, options);
+    cb_extract_cas(req, options);
 
     auto parent_span = cb_create_parent_span(req, self);
 
@@ -807,6 +808,7 @@ cb_Backend_document_prepend(VALUE self,
     cb_extract_content(req, content);
     cb_extract_timeout(req, options);
     cb_extract_durability_level(req, options);
+    cb_extract_cas(req, options);
 
     auto parent_span = cb_create_parent_span(req, self);
 

data/ext/rcb_logger.cxx

@@ -184,19 +184,19 @@ cb_Backend_set_log_level(VALUE /* self */, VALUE log_level)
 {
   Check_Type(log_level, T_SYMBOL);
   if (ID type = rb_sym2id(log_level); type == rb_intern("trace")) {
-    spdlog::set_level(spdlog::level::trace);
+    core::logger::set_log_levels(core::logger::level::trace);
   } else if (type == rb_intern("debug")) {
-    spdlog::set_level(spdlog::level::debug);
+    core::logger::set_log_levels(core::logger::level::debug);
   } else if (type == rb_intern("info")) {
-    spdlog::set_level(spdlog::level::info);
+    core::logger::set_log_levels(core::logger::level::info);
   } else if (type == rb_intern("warn")) {
-    spdlog::set_level(spdlog::level::warn);
+    core::logger::set_log_levels(core::logger::level::warn);
   } else if (type == rb_intern("error")) {
-    spdlog::set_level(spdlog::level::err);
+    core::logger::set_log_levels(core::logger::level::err);
   } else if (type == rb_intern("critical")) {
-    spdlog::set_level(spdlog::level::critical);
+    core::logger::set_log_levels(core::logger::level::critical);
   } else if (type == rb_intern("off")) {
-    spdlog::set_level(spdlog::level::off);
+    core::logger::set_log_levels(core::logger::level::off);
   } else {
     rb_raise(rb_eArgError, "Unsupported log level type: %+" PRIsVALUE, log_level);
     return Qnil;
@@ -207,23 +207,21 @@ cb_Backend_set_log_level(VALUE /* self */, VALUE log_level)
 static VALUE
 cb_Backend_get_log_level(VALUE /* self */)
 {
-  switch (spdlog::get_level()) {
-    case spdlog::level::trace:
+  switch (core::logger::get_lowest_log_level()) {
+    case core::logger::level::trace:
       return rb_id2sym(rb_intern("trace"));
-    case spdlog::level::debug:
+    case core::logger::level::debug:
       return rb_id2sym(rb_intern("debug"));
-    case spdlog::level::info:
+    case core::logger::level::info:
       return rb_id2sym(rb_intern("info"));
-    case spdlog::level::warn:
+    case core::logger::level::warn:
       return rb_id2sym(rb_intern("warn"));
-    case spdlog::level::err:
+    case core::logger::level::err:
       return rb_id2sym(rb_intern("error"));
-    case spdlog::level::critical:
+    case core::logger::level::critical:
       return rb_id2sym(rb_intern("critical"));
-    case spdlog::level::off:
+    case core::logger::level::off:
       return rb_id2sym(rb_intern("off"));
-    case spdlog::level::n_levels:
-      return Qnil;
   }
   return Qnil;
 }