couchbase 3.8.1 → 3.9.0

data/ext/couchbase/core/search_scoring.hxx

@@ -0,0 +1,66 @@
+/* -*- 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 <cstdint>
+#include <optional>
+#include <variant>
+
+namespace couchbase::core
+{
+/**
+ * Disables scoring.
+ */
+struct search_scoring_none {
+};
+
+/**
+ * Reciprocal Rank Fusion.
+ */
+struct search_scoring_reciprocal_rank_fusion {
+  std::optional<std::uint32_t> rank_constant{};
+  std::optional<std::uint32_t> window_size{};
+};
+
+/**
+ * Relative Score Fusion.
+ */
+struct search_scoring_relative_score_fusion {
+  std::optional<std::uint32_t> window_size{};
+};
+
+/**
+ * The value of the top-level "score" field of a search request. `std::monostate` means the field
+ * was not set.
+ */
+using search_scoring_mode = std::variant<std::monostate,
+                                         search_scoring_none,
+                                         search_scoring_reciprocal_rank_fusion,
+                                         search_scoring_relative_score_fusion>;
+
+/**
+ * Whether the strategy is one of the score fusion strategies, and therefore requires the
+ * "scoreFusion" cluster capability.
+ */
+[[nodiscard]] inline auto
+is_score_fusion(const search_scoring_mode& scoring) -> bool
+{
+  return std::holds_alternative<search_scoring_reciprocal_rank_fusion>(scoring) ||
+         std::holds_alternative<search_scoring_relative_score_fusion>(scoring);
+}
+} // namespace couchbase::core

data/ext/couchbase/core/stream_error_details.hxx

@@ -0,0 +1,69 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2026. 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 <string>
+
+namespace couchbase::core
+{
+/**
+ * Service-reported diagnostics lifted out of a streaming response, so a streaming failure can be
+ * reported with the same context the buffered path provides.
+ *
+ * A stream parses two JSON sections that can carry errors: the preamble (everything before the row
+ * array, which is where a rejected request reports itself) and the trailer (which is where a
+ * request that failed part-way through reports itself). Whichever section produced the latest
+ * diagnostics is what these fields describe; `raw` is the JSON text they came from, and stands in
+ * for the buffered path's whole-body capture.
+ */
+struct stream_error_details {
+  std::uint64_t first_error_code{};
+  std::string first_error_message{};
+  std::string client_context_id{};
+  std::string raw{};
+};
+
+/**
+ * Stamps stream diagnostics onto a query/analytics error context. Templated on the context because
+ * the two services carry structurally identical contexts under different types.
+ *
+ * Each field is only written when the stream actually reported it, so these diagnostics augment the
+ * context rather than erasing it. That matters for the prepared-statement path, which reaches the
+ * streaming handle by replaying an already-buffered response: its context arrives fully populated
+ * (http_command captures the response body for every request), and there is no raw JSON left for
+ * the replay to report, so an unconditional write would clear the body it already had.
+ *
+ * client_context_id is deliberately left alone: the context already holds the id the request was
+ * sent with, which is the one to correlate against server logs, and the echoed value can differ.
+ */
+template<typename Context>
+void
+apply_error_details(Context& ctx, const stream_error_details& details)
+{
+  if (details.first_error_code != 0) {
+    ctx.first_error_code = details.first_error_code;
+  }
+  if (!details.first_error_message.empty()) {
+    ctx.first_error_message = details.first_error_message;
+  }
+  if (!details.raw.empty()) {
+    ctx.http_body = details.raw;
+  }
+}
+} // namespace couchbase::core

data/ext/couchbase/core/timeout_defaults.hxx

@@ -22,7 +22,6 @@
 namespace couchbase::core::timeout_defaults
 {
 constexpr std::chrono::milliseconds bootstrap_timeout{ 10'000 };
-constexpr std::chrono::milliseconds dispatch_timeout{ 30'000 };
 
 constexpr std::chrono::milliseconds resolve_timeout{ 2'000 };
 constexpr std::chrono::milliseconds connect_timeout{ 2'000 };

data/ext/couchbase/core/topology/capabilities.hxx

@@ -57,6 +57,7 @@ enum class cluster_capability {
   n1ql_read_from_replica,
   search_vector_search,
   search_scoped_search_index,
+  search_score_fusion,
 };
 
 struct configuration_capabilities {
@@ -121,6 +122,11 @@ struct configuration_capabilities {
     return has_cluster_capability(cluster_capability::search_vector_search);
   }
 
+  [[nodiscard]] auto supports_score_fusion() const -> bool
+  {
+    return has_cluster_capability(cluster_capability::search_score_fusion);
+  }
+
   [[nodiscard]] auto is_analytics_cluster(const cluster_options& options) const -> bool;
 };
 

data/ext/couchbase/core/topology/capabilities_fmt.hxx

@@ -142,6 +142,9 @@ struct fmt::formatter<couchbase::core::cluster_capability> {
       case couchbase::core::cluster_capability::search_scoped_search_index:
         name = "search_scoped_search_index";
         break;
+      case couchbase::core::cluster_capability::search_score_fusion:
+        name = "search_score_fusion";
+        break;
     }
     return format_to(ctx.out(), "{}", name);
   }

data/ext/couchbase/core/topology/configuration.cxx

@@ -173,21 +173,23 @@ configuration::node::endpoint(const std::string& network, service_type type, boo
 }
 
 auto
-configuration::node::effective_node_id(bool is_tls) const -> couchbase::node_id
+configuration::node::effective_node_id(transport t) const -> couchbase::node_id
 {
+  const bool is_tls = (t == transport::tls);
   return internal_node_id::build(node_uuid, hostname, port_or(service_type::key_value, is_tls, 0));
 }
 
 auto
-configuration::effective_node_ids(bool is_tls) const -> std::vector<couchbase::node_id>
+configuration::effective_node_ids(transport t) const -> std::vector<couchbase::node_id>
 {
+  const bool is_tls = (t == transport::tls);
   std::vector<couchbase::node_id> result;
   result.reserve(nodes.size());
   for (const auto& n : nodes) {
     if (n.port_or(service_type::key_value, is_tls, 0) == 0) {
       continue;
     }
-    result.push_back(n.effective_node_id(is_tls));
+    result.push_back(n.effective_node_id(t));
   }
   return result;
 }
@@ -300,7 +302,16 @@ configuration::server_by_vbucket(std::uint16_t vbucket, std::size_t index) const
   if (!vbmap.has_value() || vbucket >= vbmap->size()) {
     return {};
   }
-  if (auto server_index = vbmap->at(vbucket)[index]; server_index >= 0) {
+  // A chain row may be shorter than num_replicas + 1: the server publishes the
+  // new replica count as soon as the bucket is reconfigured, while the vbucket
+  // map keeps its old width until the rebalance that places the replicas.
+  // Callers derive the index from num_replicas, so a surplus index must read as
+  // "no server" rather than past the end of the row.
+  const auto& chain = vbmap->at(vbucket);
+  if (index >= chain.size()) {
+    return {};
+  }
+  if (auto server_index = chain[index]; server_index >= 0) {
     return static_cast<std::size_t>(server_index);
   }
   return {};
@@ -310,7 +321,9 @@ auto
 configuration::map_key(const std::string& key, std::size_t index) const
   -> std::pair<std::uint16_t, std::optional<std::size_t>>
 {
-  if (!vbmap.has_value()) {
+  // The number of vbuckets comes from the map itself, so a map without rows
+  // cannot be asked which vbucket a key belongs to.
+  if (!vbmap.has_value() || vbmap->empty()) {
     return { 0, {} };
   }
   const std::uint32_t crc = utils::hash_crc32(key.data(), key.size());
@@ -322,7 +335,9 @@ auto
 configuration::map_key(const std::vector<std::byte>& key, std::size_t index) const
   -> std::pair<std::uint16_t, std::optional<std::size_t>>
 {
-  if (!vbmap.has_value()) {
+  // The number of vbuckets comes from the map itself, so a map without rows
+  // cannot be asked which vbucket a key belongs to.
+  if (!vbmap.has_value() || vbmap->empty()) {
     return { 0, {} };
   }
   const std::uint32_t crc = utils::hash_crc32(key.data(), key.size());

data/ext/couchbase/core/topology/configuration.hxx

@@ -31,6 +31,21 @@
 
 namespace couchbase::core::topology
 {
+
+/**
+ * Selects which side of the (plain, TLS) port pair to use when deriving a
+ * node identity from a topology snapshot.
+ *
+ * Internal-only strong type: a bare @c bool here is bug-bait because the same
+ * flag flows through 6+ layers from origin() into effective_node_id() and a
+ * silent sign flip would corrupt the pre-8.0 fallback hash without any
+ * compile-time warning.
+ */
+enum class transport {
+  plain,
+  tls,
+};
+
 struct configuration {
   enum class node_locator_type {
     unknown,
@@ -92,11 +107,17 @@ struct configuration {
      * KV port for older servers.
      *
      * The KV port selected mirrors what mcbp_session uses for the same node
-     * (TLS port when @p is_tls, plain port otherwise), ensuring that the
-     * node_id surfaced on the request side via collection::node_id_for
-     * matches the node_id attached to results and errors.
+     * (TLS port when @p t is @c transport::tls, plain port otherwise),
+     * ensuring that the node_id surfaced on the request side via
+     * collection::node_id_for matches the node_id attached to results and
+     * errors.
+     *
+     * Returns a default-constructed (falsy) @c node_id when this node does
+     * not expose a KV port for the requested transport — the contract that
+     * "falsy = unknown / not identifiable" is enforced by
+     * @c internal_node_id::build for the empty case.
      */
-    [[nodiscard]] auto effective_node_id(bool is_tls) const -> couchbase::node_id;
+    [[nodiscard]] auto effective_node_id(transport t) const -> couchbase::node_id;
   };
 
   [[nodiscard]] auto select_network(const std::string& bootstrap_hostname) const -> std::string;
@@ -104,16 +125,16 @@ struct configuration {
   /**
    * Returns one node_id per cluster node that currently serves the
    * key-value service over the requested transport. Nodes that do not
-   * expose a KV port for @p is_tls are filtered out — without a KV port
-   * the fallback hash would be derived from a meaningless port=0 and
-   * could collide with a sibling node that is also missing its KV port.
+   * expose a KV port for @p t are filtered out — without a KV port the
+   * fallback hash would be derived from a meaningless port=0 and could
+   * collide with a sibling node that is also missing its KV port.
    *
    * The returned vector preserves topology order; callers that want a
    * set semantic should hash the entries themselves (couchbase::node_id
    * is hashable). Topology nodes are unique by construction, so no
    * dedup is performed here.
    */
-  [[nodiscard]] auto effective_node_ids(bool is_tls) const -> std::vector<couchbase::node_id>;
+  [[nodiscard]] auto effective_node_ids(transport t) const -> std::vector<couchbase::node_id>;
 
   using vbucket_map = typename std::vector<std::vector<std::int16_t>>;
 

data/ext/couchbase/core/topology/configuration_json.hxx

@@ -324,6 +324,9 @@ struct traits<couchbase::core::topology::configuration> {
           } else if (name == "scopedSearchIndex") {
             result.capabilities.cluster.insert(
               couchbase::core::cluster_capability::search_scoped_search_index);
+          } else if (name == "scoreFusion") {
+            result.capabilities.cluster.insert(
+              couchbase::core::cluster_capability::search_score_fusion);
           }
         }
       }

data/ext/couchbase/core/topology/error_map_json.hxx

@@ -17,6 +17,7 @@
 
 #pragma once
 
+#include "core/logger/redaction.hxx"
 #include "error_map.hxx"
 
 #include <gsl/narrow>
@@ -86,7 +87,8 @@ struct traits<couchbase::core::error_map> {
             R"(skipping unknown attribute "{}" in error map for code={} and name="{}")",
             attr_val,
             code,
-            name);
+            // the name of an error in the error map, not a Couchbase resource name
+            couchbase::core::logger::not_sensitive(name));
         }
       }
       result.errors.emplace(

data/ext/couchbase/core/tracing/threshold_logging_tracer.cxx

@@ -21,6 +21,7 @@
 
 #include "constants.hxx"
 #include "core/logger/logger.hxx"
+#include "core/logger/redaction.hxx"
 #include "core/meta/version.hxx"
 #include "core/platform/uuid.h"
 #include "core/service_type_fmt.hxx"
@@ -31,11 +32,24 @@
 #include <memory>
 #include <tao/json/value.hpp>
 
+#include <array>
 #include <chrono>
+#include <cstdint>
+#include <optional>
 #include <utility>
 
 namespace couchbase::core::tracing
 {
+auto
+format_dispatch_operation_id(std::uint32_t opaque) -> std::string
+{
+  // A uint32 in "0x<hex>" form is at most "0x" plus 8 hex digits, so a 12-byte buffer never
+  // overflows and the string is built without a heap allocation until the final copy out.
+  std::array<char, 12> buffer{};
+  const auto result = fmt::format_to_n(buffer.data(), buffer.size(), "0x{:x}", opaque);
+  return { buffer.data(), result.out };
+}
+
 struct reported_span {
   std::chrono::microseconds duration;
   tao::json::value payload;
@@ -62,6 +76,7 @@ private:
   std::uint64_t last_server_duration_us_{ 0 };
   std::uint64_t total_server_duration_us_{ 0 };
   std::optional<std::string> operation_id_{};
+  std::optional<std::uint32_t> operation_id_opaque_{};
   std::optional<std::string> last_local_id_{};
   std::optional<std::string> service_{};
   std::optional<std::string> peer_hostname_{};
@@ -107,6 +122,40 @@ public:
     }
   }
 
+  [[nodiscard]] auto try_set_dispatch_operation_id(std::uint32_t opaque) -> bool override
+  {
+    // Capture the raw opaque; it is formatted lazily in operation_id(), and only when this span is
+    // actually reported (i.e. exceeds the threshold), which keeps the formatting off the hot path.
+    operation_id_opaque_ = opaque;
+    return true;
+  }
+
+  [[nodiscard]] auto try_set_dispatch_local_id(const std::string& local_id) -> bool override
+  {
+    // Capture directly, bypassing the tag-name string that add_tag() would materialize on the hot
+    // path (see request_span::try_set_dispatch_local_id).
+    last_local_id_ = local_id;
+    return true;
+  }
+
+  [[nodiscard]] auto try_set_dispatch_result(std::uint64_t server_duration_us,
+                                             const std::string& peer_address,
+                                             std::uint16_t peer_port) -> bool override
+  {
+    // Mirror the add_tag() bookkeeping without materializing any tag-name strings, including the
+    // same rule for the running total: it is accumulated only on non-dispatch spans, so a dispatch
+    // span records last_server_duration_us_ and leaves the total to be rolled up on its parent in
+    // end(). (In current wiring this setter only runs on the dispatch span, but the guard is kept
+    // so the two paths stay behaviourally identical.)
+    last_server_duration_us_ = server_duration_us;
+    if (name() != tracing::operation::step_dispatch) {
+      total_server_duration_us_ += server_duration_us;
+    }
+    peer_hostname_ = peer_address;
+    peer_port_ = peer_port;
+    return true;
+  }
+
   void end() override;
 
   void set_last_local_id(const std::string& id)
@@ -119,6 +168,11 @@ public:
     operation_id_ = id;
   }
 
+  void set_operation_id_opaque(std::uint32_t opaque)
+  {
+    operation_id_opaque_ = opaque;
+  }
+
   void set_peer_hostname(const std::string& hostname)
   {
     peer_hostname_ = hostname;
@@ -160,7 +214,14 @@ public:
 
   [[nodiscard]] auto operation_id() const -> std::optional<std::string>
   {
-    return operation_id_;
+    if (operation_id_.has_value()) {
+      return operation_id_;
+    }
+    if (operation_id_opaque_.has_value()) {
+      // Build the string only here — on the reporting path, never on the hot path.
+      return format_dispatch_operation_id(operation_id_opaque_.value());
+    }
+    return {};
   }
 
   [[nodiscard]] auto last_local_id() const -> std::optional<std::string>
@@ -216,8 +277,8 @@ convert(const std::shared_ptr<threshold_logging_span>& span) -> reported_span
     entry["total_server_duration_us"] = span->total_server_duration_us();
   }
 
-  if (span->operation_id().has_value()) {
-    entry["last_operation_id"] = span->operation_id().value();
+  if (const auto operation_id = span->operation_id(); operation_id.has_value()) {
+    entry["last_operation_id"] = operation_id.value();
   }
 
   if (span->last_local_id().has_value()) {
@@ -321,7 +382,8 @@ private:
         queue.pop();
       }
       report["top"] = entries;
-      CB_LOG_WARNING("Operations over threshold: {}", utils::json::generate(report));
+      CB_LOG_WARNING("Operations over threshold: {}",
+                     logger::system_data(utils::json::generate(report)));
     }
   }
 
@@ -380,6 +442,10 @@ threshold_logging_span::end()
       }
       if (operation_id_.has_value()) {
         p->set_operation_id(operation_id_.value());
+      } else if (operation_id_opaque_.has_value()) {
+        // Propagate the raw opaque so the parent still reports the operation id, while keeping the
+        // (rarely needed) formatting deferred to the parent's reporting path.
+        p->set_operation_id_opaque(operation_id_opaque_.value());
       }
       if (peer_hostname_.has_value()) {
         p->set_peer_hostname(peer_hostname_.value());

data/ext/couchbase/core/tracing/threshold_logging_tracer.hxx

@@ -23,6 +23,7 @@
 
 #include <asio/io_context.hpp>
 
+#include <cstdint>
 #include <memory>
 #include <string>
 
@@ -31,6 +32,15 @@ namespace couchbase::core::tracing
 class threshold_logging_span;
 class threshold_logging_tracer_impl;
 
+/**
+ * Format a dispatch operation identifier (the request opaque) into the "0x<hex>" form used in
+ * threshold reports. The built-in span captures the raw opaque on the hot path and formats it here,
+ * lazily, only when a span is actually reported. Declared in the header so the formatting contract
+ * can be unit-tested directly.
+ */
+[[nodiscard]] auto
+format_dispatch_operation_id(std::uint32_t opaque) -> std::string;
+
 class threshold_logging_tracer
   : public couchbase::tracing::request_tracer
   , public std::enable_shared_from_this<threshold_logging_tracer>

data/ext/couchbase/core/transactions/active_transaction_record.cxx

@@ -30,40 +30,6 @@
 
 namespace couchbase::core::transactions
 {
-/**
- * ${Mutation.CAS} is written by kvengine with
- * 'macroToString(htonll(info.cas))'.  Discussed this with KV team and, though
- * there is consensus that this is off (htonll is definitely wrong, and a string
- * is an odd choice), there are clients (SyncGateway) that consume the current
- * string, so it can't be changed.  Note that only little-endian servers are
- * supported for Couchbase, so the 8 byte long inside the string will always be
- * little-endian ordered.
- *
- * Looks like: "0x000058a71dd25c15"
- * Want:        0x155CD21DA7580000   (1539336197457313792 in base10, an epoch
- * time in millionths of a second)
- *
- * returns epoch time in ms
- */
-auto
-parse_mutation_cas(const std::string& cas) -> std::uint64_t
-{
-  if (cas.empty()) {
-    return 0;
-  }
-
-  std::uint64_t val = stoull(cas, nullptr, 16);
-  /* byteswap */
-  std::size_t ii = 0;
-  std::uint64_t ret = 0;
-  for (ii = 0; ii < sizeof(std::uint64_t); ii++) {
-    ret <<= 8ULL;
-    ret |= val & 0xffULL;
-    val >>= 8ULL;
-  }
-  return ret / 1000000;
-}
-
 auto
 process_document_ids(const tao::json::value& entry,
                      const std::string& key) -> std::optional<std::vector<doc_record>>