couchbase 3.8.2 → 3.9.0

data/ext/couchbase/core/mcbp/queue_request.cxx

@@ -16,13 +16,17 @@
  */
 
 #include "queue_request.hxx"
+
 #include "../operation_map.hxx"
-#include "core/logger/logger.hxx"
 #include "operation_queue.hxx"
 #include "queue_response.hxx"
 
 #include <couchbase/error_codes.hxx>
 
+#include <spdlog/fmt/bundled/core.h>
+
+#include <couchbase/fmt/retry_reason.hxx>
+
 #include <atomic>
 
 namespace couchbase::core::mcbp
@@ -127,32 +131,42 @@ void
 queue_request::cancel(std::error_code error)
 {
   if (internal_cancel()) {
-    callback_({}, shared_from_this(), error);
+    // Move callback_ before invoking to release any captured state (e.g. shared_ptr cycles)
+    // as soon as the callback returns rather than retaining it for the lifetime of the request.
+    auto cb = std::move(callback_);
+    cb({}, shared_from_this(), error);
   }
 }
 
 void
 queue_request::set_deadline(std::shared_ptr<asio::steady_timer> timer)
 {
+  const std::scoped_lock lock(processing_mutex_);
   deadline_ = std::move(timer);
 }
 
 void
 queue_request::set_retry_backoff(std::shared_ptr<asio::steady_timer> timer)
 {
+  const std::scoped_lock lock(processing_mutex_);
   retry_backoff_ = std::move(timer);
 }
 
 void
 queue_request::try_callback(std::shared_ptr<queue_response> response, std::error_code error)
 {
-  cancel_timer(deadline_);
-  cancel_timer(retry_backoff_);
+  {
+    const std::scoped_lock lock(processing_mutex_);
+    cancel_timer(deadline_);
+    cancel_timer(retry_backoff_);
+  }
 
   if (persistent_) {
     if (error) {
       if (internal_cancel()) {
-        return callback_(std::move(response), shared_from_this(), error);
+        // Move callback_ before invoking to release any captured state (e.g. shared_ptr cycles).
+        auto cb = std::move(callback_);
+        return cb(std::move(response), shared_from_this(), error);
       }
     } else if (!is_completed_) {
       return callback_(std::move(response), shared_from_this(), error);
@@ -160,7 +174,10 @@ queue_request::try_callback(std::shared_ptr<queue_response> response, std::error
     return;
   }
   if (bool expected_state{ false }; is_completed_.compare_exchange_strong(expected_state, true)) {
-    return callback_(std::move(response), shared_from_this(), error);
+    // Move callback_ before invoking to release any captured state (e.g. shared_ptr cycles)
+    // as soon as the callback returns.
+    auto cb = std::move(callback_);
+    return cb(std::move(response), shared_from_this(), error);
   }
 }
 

data/ext/couchbase/core/mcbp/queue_request.hxx

@@ -27,6 +27,7 @@
 #include <asio/steady_timer.hpp>
 
 #include <atomic>
+#include <functional>
 #include <memory>
 #include <mutex>
 #include <set>
@@ -36,6 +37,11 @@ namespace couchbase::core
 class operation_map;
 } // namespace couchbase::core
 
+namespace couchbase::tracing
+{
+class request_span;
+} // namespace couchbase::tracing
+
 namespace couchbase::core::mcbp
 {
 class operation_queue;
@@ -73,6 +79,13 @@ public:
   std::string collection_name_{};
   std::string scope_name_{};
   std::size_t replica_index_{ 0 };
+
+  // Set by collections_component when a request is dispatched through the collection-id cache.
+  // Invoked by the KV response path on an unknown_collection status to invalidate the cached id,
+  // re-resolve it (GetCollectionID) and retry the request. Returns true if a retry was scheduled.
+  // Left empty for requests that bypass the cache (e.g. the GetCollectionID resolution requests
+  // themselves), which must not recurse.
+  std::function<bool()> on_unknown_collection_{};
   // This tracks when the request was dispatched so that we can properly prioritize older requests
   // to try and meet timeout requirements.
   std::chrono::steady_clock::time_point dispatched_time_{};
@@ -86,6 +99,14 @@ public:
   // the request and calculating any back-off time period.
   std::shared_ptr<couchbase::retry_strategy> retry_strategy_{};
 
+  // The parent tracing span for this operation, set by crud_component before dispatching.
+  // Kept alive here so the span outlives any retry loops.
+  std::shared_ptr<couchbase::tracing::request_span> parent_span_{ nullptr };
+
+  // The per-dispatch child span representing a single attempt on a specific node.
+  // Reset and recreated on every retry by crud_component.
+  std::shared_ptr<couchbase::tracing::request_span> dispatch_span_{ nullptr };
+
 private:
   // Static routing properties
   queue_callback callback_;

data/ext/couchbase/core/meta/features.hxx

@@ -268,3 +268,16 @@
  * Support for the stable OpenTelemetry conventions (Observability RFC revisions 26 & 27)
  */
 #define COUCHBASE_CXX_CLIENT_STABLE_OTEL_CONVENTIONS 1
+
+/**
+ * An HTTP 400 that matches no more specific error is reported as
+ * couchbase::errc::common::invalid_argument (SDK-RFC 58 revision 22).
+ */
+#define COUCHBASE_CXX_CLIENT_HTTP_400_IS_INVALID_ARGUMENT 1
+
+/**
+ * The implementations for couchbase::transactions::transactions and
+ * couchbase::core::transactions::transactions are separate, i.e.,
+ * couchbase::core::transactions::transactions does not implement the Public API.
+ */
+#define COUCHBASE_CXX_CLIENT_TRANSACTIONS_PUBLIC_CORE_IMPL_SEPARATION 1

data/ext/couchbase/core/meta/version.cxx

@@ -89,8 +89,11 @@ sdk_build_info() -> std::map<std::string, std::string>
     "false"
 #endif
     ;
-  info["columnar"] =
-#if defined(COUCHBASE_CXX_CLIENT_COLUMNAR)
+  // Whether this build can serve couchbase2:// connection strings, i.e. whether it was compiled
+  // with Cloud Native Gateway support. A build without it rejects the scheme at connect time, so
+  // the answer is worth reporting next to the other build-time switches.
+  info["couchbase2"] =
+#if defined(COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2)
     "true"
 #else
     "false"
@@ -194,7 +197,7 @@ sdk_build_info_json() -> std::string
         name == "version_build" || name == "mozilla_ca_bundle_size") {
       info[name] = std::stoi(value);
     } else if (name == "snapshot" || name == "static_stdlib" || name == "static_openssl" ||
-               name == "mozilla_ca_bundle_embedded") {
+               name == "couchbase2" || name == "mozilla_ca_bundle_embedded") {
       info[name] = value == "true";
     } else {
       info[name] = value;

data/ext/couchbase/core/metrics/logging_meter.cxx

@@ -21,6 +21,7 @@
 
 #include "constants.hxx"
 #include "core/logger/logger.hxx"
+#include "core/logger/redaction.hxx"
 #include "core/tracing/constants.hxx"
 #include "core/utils/json.hxx"
 #include "noop_meter.hxx"
@@ -161,7 +162,7 @@ logging_meter::log_report() const
     }
   }
   if (report.find("operations") != nullptr) {
-    CB_LOG_INFO("Metrics: {}", utils::json::generate(report));
+    CB_LOG_INFO("Metrics: {}", logger::metadata(utils::json::generate(report)));
   }
 }
 
@@ -228,14 +229,8 @@ logging_meter::get_value_recorder(const std::string& name,
   const std::scoped_lock lock(recorders_mutex_);
   auto& service_recorders = recorders_[service->second];
 
-  auto recorder = service_recorders.find(operation->second);
-  if (recorder != service_recorders.end()) {
-    return recorder->second;
-  }
-
-  service_recorders.try_emplace(operation->second,
-                                std::make_shared<logging_value_recorder>(operation->second, tags));
-  recorder = service_recorders.find(operation->second);
-  return recorder->second;
+  auto [it, _] = service_recorders.try_emplace(
+    operation->second, std::make_shared<logging_value_recorder>(operation->second, tags));
+  return it->second;
 }
 } // namespace couchbase::core::metrics

data/ext/couchbase/core/metrics/meter_wrapper.cxx

@@ -22,6 +22,9 @@
 #include "core/metrics/constants.hxx"
 #include "core/tracing/constants.hxx"
 
+#include <algorithm>
+#include <array>
+#include <cctype>
 #include <map>
 #include <memory>
 #include <string>
@@ -62,23 +65,15 @@ extract_error_name(std::error_code ec) -> std::string
   return ec.message();
 }
 
+} // namespace
+
 auto
-get_standardized_error_type(std::error_code ec) -> std::string
+standardized_error_type(std::error_code ec) -> std::string
 {
   if (!ec) {
     return {};
   }
 
-  // SDK-specific errors
-  if (ec.value() >= 1000) {
-    return "CouchbaseError";
-  }
-
-  // Errors where message and RFC-message don't match
-  if (ec == errc::field_level_encryption::generic_cryptography_failure) {
-    return "CryptoError";
-  }
-
   static const std::array<const std::error_category*, 12> cb_categories = {
     &impl::common_category(),      &impl::key_value_category(),
     &impl::query_category(),       &impl::analytics_category(),
@@ -88,16 +83,30 @@ get_standardized_error_type(std::error_code ec) -> std::string
     &impl::transaction_category(), &impl::transaction_op_category(),
   };
 
-  if (std::any_of(
-        cb_categories.begin(), cb_categories.end(), [&ec](const std::error_category* cat) -> bool {
-          return &ec.category() == cat;
-        })) {
-    return snake_case_to_camel_case(extract_error_name(ec));
+  // Classify only against the Couchbase categories. Numeric error values overlap across the
+  // platform/system/asio categories, so a value-based check alone would misclassify a foreign error
+  // (e.g. a TLS or system error that happens to have value >= 1000) as a Couchbase error.
+  const bool couchbase_error =
+    std::any_of(cb_categories.begin(), cb_categories.end(), [&ec](const std::error_category* cat) {
+      return &ec.category() == cat;
+    });
+  if (!couchbase_error) {
+    return "_OTHER";
+  }
+
+  // The SDK's network errors (couchbase::errc::network) use values >= 1000 and are reported under a
+  // single generic bucket rather than by individual name.
+  if (ec.value() >= 1000) {
+    return "CouchbaseError";
   }
 
-  return "_OTHER";
+  // Errors where message and RFC-message don't match
+  if (ec == errc::field_level_encryption::generic_cryptography_failure) {
+    return "CryptoError";
+  }
+
+  return snake_case_to_camel_case(extract_error_name(ec));
 }
-} // namespace
 
 auto
 metric_attributes::encode() const -> std::map<std::string, std::string>
@@ -124,8 +133,8 @@ metric_attributes::encode() const -> std::map<std::string, std::string>
   if (collection_name) {
     tags.emplace(tracing::attributes::op::collection_name, collection_name.value());
   }
-  if (ec) {
-    tags.emplace(tracing::attributes::op::error_type, get_standardized_error_type(ec));
+  if (!error_type.empty()) {
+    tags.emplace(tracing::attributes::op::error_type, error_type);
   }
 
   return tags;
@@ -150,28 +159,49 @@ meter_wrapper::stop()
   meter_->stop();
 }
 
-void
-meter_wrapper::record_value(const std::map<std::string, std::string>& raw_attrs,
-                            std::chrono::microseconds duration)
+auto
+meter_wrapper::value_recorder_for(const metric_attributes& attrs)
+  -> std::shared_ptr<couchbase::metrics::value_recorder>
 {
-  meter_->get_value_recorder(operation_meter_name, raw_attrs)->record_value(duration.count());
+  {
+    const std::scoped_lock lock(recorder_cache_mutex_);
+    if (auto it = recorder_cache_.find(attrs); it != recorder_cache_.end()) {
+      return it->second;
+    }
+  }
+
+  // Resolve outside the lock: encode() and the pluggable meter's get_value_recorder() are
+  // user-visible code paths, and holding the cache mutex across them would serialize every
+  // first-time resolution and risk deadlock if a custom meter re-entered record_value(). The
+  // meter returns a stable recorder for a given name/tag set, so resolving the same key twice on
+  // a race is harmless.
+  auto recorder = meter_->get_value_recorder(operation_meter_name, attrs.encode());
+
+  const std::scoped_lock lock(recorder_cache_mutex_);
+  // A concurrent caller may have inserted this key while the lock was released; emplace keeps the
+  // first-inserted recorder and returns it, so all callers share one recorder per key.
+  return recorder_cache_.emplace(attrs, std::move(recorder)).first->second;
 }
 
 void
 meter_wrapper::record_value(metric_attributes attrs,
                             std::chrono::steady_clock::time_point start_time)
 {
-  auto [cluster_name, cluster_uuid] = cluster_label_listener_->cluster_labels();
-  if (cluster_name) {
-    attrs.internal.cluster_name = cluster_name;
-  }
-  if (cluster_uuid) {
-    attrs.internal.cluster_uuid = cluster_uuid;
+  // The listener is optional -- the wrapper can be constructed without one -- so only enrich the
+  // attributes with cluster labels when it is present.
+  if (cluster_label_listener_) {
+    auto [cluster_name, cluster_uuid] = cluster_label_listener_->cluster_labels();
+    if (cluster_name) {
+      attrs.internal.cluster_name = cluster_name;
+    }
+    if (cluster_uuid) {
+      attrs.internal.cluster_uuid = cluster_uuid;
+    }
   }
 
-  record_value(attrs.encode(),
-               std::chrono::duration_cast<std::chrono::microseconds>(
-                 std::chrono::steady_clock::now() - start_time));
+  value_recorder_for(attrs)->record_value(std::chrono::duration_cast<std::chrono::microseconds>(
+                                            std::chrono::steady_clock::now() - start_time)
+                                            .count());
 }
 
 auto

data/ext/couchbase/core/metrics/meter_wrapper.hxx

@@ -25,9 +25,12 @@
 
 #include <chrono>
 #include <map>
+#include <memory>
+#include <mutex>
 #include <optional>
 #include <string>
 #include <system_error>
+#include <tuple>
 
 #include "core/cluster_label_listener.hxx"
 
@@ -36,7 +39,11 @@ namespace couchbase::core::metrics
 struct metric_attributes {
   std::string service;
   std::string operation;
-  std::error_code ec;
+  // The standardized error type, precomputed once from the operation's error code (see
+  // standardized_error_type()). Stored rather than the raw error code so that both the encoded tag
+  // set and the recorder-cache key (operator<) use it without recomputing a string per comparison.
+  // Empty denotes "no error".
+  std::string error_type{};
   std::optional<std::string> bucket_name{};
   std::optional<std::string> scope_name{};
   std::optional<std::string> collection_name{};
@@ -49,6 +56,38 @@ struct metric_attributes {
   [[nodiscard]] auto encode() const -> std::map<std::string, std::string>;
 };
 
+// Map an error code to the standardized error-type string used as the metric's error_type tag (see
+// metric_attributes::encode()). The empty string denotes "no error". Exposed so the recorder cache
+// can key on the same bounded set of error types that actually reach the tags.
+[[nodiscard]] auto
+standardized_error_type(std::error_code ec) -> std::string;
+
+inline auto
+operator<(const metric_attributes& lhs, const metric_attributes& rhs) -> bool
+{
+  // Order by the precomputed standardized error type, not the raw error code. encode() only ever
+  // emits the standardized type in the tag set, so keying on it collapses the many distinct codes
+  // that share a type onto one recorder and keeps the cache bounded by the tag cardinality (rather
+  // than one entry per raw code, unbounded for high-cardinality system/asio codes). Because the
+  // type is stored on the attributes, every comparison is a plain string compare -- no per-lookup
+  // string construction or allocation, which is what keeps the cache lookup cheap on the hot path.
+  return std::tie(lhs.service,
+                  lhs.operation,
+                  lhs.error_type,
+                  lhs.bucket_name,
+                  lhs.scope_name,
+                  lhs.collection_name,
+                  lhs.internal.cluster_name,
+                  lhs.internal.cluster_uuid) < std::tie(rhs.service,
+                                                        rhs.operation,
+                                                        rhs.error_type,
+                                                        rhs.bucket_name,
+                                                        rhs.scope_name,
+                                                        rhs.collection_name,
+                                                        rhs.internal.cluster_name,
+                                                        rhs.internal.cluster_uuid);
+}
+
 class meter_wrapper
 {
 public:
@@ -59,8 +98,12 @@ public:
   void stop();
 
   void record_value(metric_attributes attrs, std::chrono::steady_clock::time_point start_time);
-  void record_value(const std::map<std::string, std::string>& raw_attrs,
-                    std::chrono::microseconds duration);
+
+  // Resolve (and cache) the value recorder for a set of attributes. The underlying meter returns a
+  // stable recorder for a given name/tag set, so resolving once per distinct attribute set keeps
+  // the per-operation tag-map construction and recorder lookup off the hot path.
+  [[nodiscard]] auto value_recorder_for(const metric_attributes& attrs)
+    -> std::shared_ptr<couchbase::metrics::value_recorder>;
 
   [[nodiscard]] auto wrapped() -> std::shared_ptr<couchbase::metrics::meter>;
 
@@ -71,5 +114,14 @@ public:
 private:
   std::shared_ptr<couchbase::metrics::meter> meter_;
   std::shared_ptr<cluster_label_listener> cluster_label_listener_;
+  std::mutex recorder_cache_mutex_{};
+  // Keyed by the full attribute set (not just service/operation): the meter is pluggable, and a
+  // custom meter may hand out a distinct recorder per tag combination, so the cache must ask it
+  // once for each distinct attribute set rather than assume any particular dedup granularity. The
+  // key mirrors what encode() emits -- in particular it orders by the standardized error type (see
+  // operator<), not the raw error code -- so the key space is finite (services x operations x
+  // scope/collection x standardized error type x cluster) and the cache stays bounded.
+  std::map<metric_attributes, std::shared_ptr<couchbase::metrics::value_recorder>>
+    recorder_cache_{};
 };
 } // namespace couchbase::core::metrics

data/ext/couchbase/core/operations/analytics_response_parsing.cxx

@@ -0,0 +1,177 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-2021 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 "analytics_response_parsing.hxx"
+
+#include "core/utils/duration_parser.hxx"
+#include "core/utils/json.hxx"
+
+#include <couchbase/error_codes.hxx>
+
+#include <tao/json/value.hpp>
+
+namespace couchbase::core::operations
+{
+
+auto
+parse_analytics_meta(const tao::json::value& payload) -> analytics_response::analytics_meta_data
+{
+  analytics_response::analytics_meta_data meta{};
+
+  if (const auto* i = payload.find("requestID"); i != nullptr) {
+    meta.request_id = i->get_string();
+  }
+  if (const auto* i = payload.find("clientContextID"); i != nullptr) {
+    meta.client_context_id = i->get_string();
+  }
+
+  if (const auto* s = payload.find("status"); s != nullptr && s->is_string()) {
+    const auto& status = s->get_string();
+    if (status == "running") {
+      meta.status = analytics_response::analytics_status::running;
+    } else if (status == "success") {
+      meta.status = analytics_response::analytics_status::success;
+    } else if (status == "errors") {
+      meta.status = analytics_response::analytics_status::errors;
+    } else if (status == "completed") {
+      meta.status = analytics_response::analytics_status::completed;
+    } else if (status == "stopped") {
+      meta.status = analytics_response::analytics_status::stopped;
+    } else if (status == "timedout") {
+      meta.status = analytics_response::analytics_status::timedout;
+    } else if (status == "closed") {
+      meta.status = analytics_response::analytics_status::closed;
+    } else if (status == "fatal") {
+      meta.status = analytics_response::analytics_status::fatal;
+    } else if (status == "aborted") {
+      meta.status = analytics_response::analytics_status::aborted;
+    } else {
+      meta.status = analytics_response::analytics_status::unknown;
+    }
+  } else {
+    meta.status = analytics_response::analytics_status::unknown;
+  }
+
+  if (const auto* s = payload.find("signature"); s != nullptr) {
+    meta.signature = couchbase::core::utils::json::generate(*s);
+  }
+
+  if (const auto* m = payload.find("metrics"); m != nullptr) {
+    meta.metrics.result_count = m->at("resultCount").get_unsigned();
+    meta.metrics.result_size = m->at("resultSize").get_unsigned();
+    meta.metrics.elapsed_time = utils::parse_duration(m->at("elapsedTime").get_string());
+    meta.metrics.execution_time = utils::parse_duration(m->at("executionTime").get_string());
+    meta.metrics.processed_objects = m->at("processedObjects").get_unsigned();
+    meta.metrics.error_count = m->optional<std::uint64_t>("errorCount").value_or(0);
+    meta.metrics.warning_count = m->optional<std::uint64_t>("warningCount").value_or(0);
+  }
+
+  if (const auto* e = payload.find("errors"); e != nullptr) {
+    for (const auto& err : e->get_array()) {
+      analytics_response::analytics_problem problem;
+      problem.code = err.at("code").get_unsigned();
+      problem.message = err.at("msg").get_string();
+      meta.errors.emplace_back(problem);
+    }
+  }
+
+  if (const auto* w = payload.find("warnings"); w != nullptr) {
+    for (const auto& warn : w->get_array()) {
+      analytics_response::analytics_problem problem;
+      problem.code = warn.at("code").get_unsigned();
+      problem.message = warn.at("msg").get_string();
+      meta.warnings.emplace_back(problem);
+    }
+  }
+
+  return meta;
+}
+
+auto
+map_analytics_error(const analytics_response::analytics_meta_data& meta, std::uint32_t http_status)
+  -> std::error_code
+{
+  if (meta.status == analytics_response::analytics_status::success && http_status != 400) {
+    return {};
+  }
+  const auto unmatched =
+    http_status == 400 ? errc::common::invalid_argument : errc::common::internal_server_failure;
+
+  if (meta.errors.empty()) {
+    /* Reachable from make_response, which calls this for any non-success status even when the
+     * payload carries no "errors" array, and from the streaming-path caller, which has no such
+     * guarantee either. */
+    return unmatched;
+  }
+
+  const auto first_error_code = meta.errors.front().code;
+
+  std::error_code ec{};
+  switch (first_error_code) {
+    case 21002: /* Request timed out and will be cancelled */
+      ec = errc::common::unambiguous_timeout;
+      break;
+    case 24000: /* RFC-58: ParsingFailure */
+      ec = errc::common::parsing_failure;
+      break;
+    case 23000: /* RFC-58: TemporaryFailure */
+    case 23003: /* RFC-58: TemporaryFailure */
+      ec = errc::common::temporary_failure;
+      break;
+    case 23007: /* Job queue is full with [string] jobs */
+      ec = errc::analytics::job_queue_full;
+      break;
+    case 24044: /* Cannot find dataset [string] because there is no dataverse declared, nor an
+                   alias with name [string]! */
+    case 24045: /* Cannot find dataset [string] in dataverse [string] nor an alias with name
+                   [string]! */
+    case 24025: /* Cannot find dataset with name [string] in dataverse [string] */
+      ec = errc::analytics::dataset_not_found;
+      break;
+    case 24034: /* Cannot find dataverse with name [string] */
+      ec = errc::analytics::dataverse_not_found;
+      break;
+    case 24040: /* A dataset with name [string] already exists in dataverse [string] */
+      ec = errc::analytics::dataset_exists;
+      break;
+    case 24039: /* A dataverse with this name [string] already exists. */
+      ec = errc::analytics::dataverse_exists;
+      break;
+    case 24006: /* Link [string] does not exist | Link [string] does not exist */
+      ec = errc::analytics::link_not_found;
+      break;
+    default:
+      // RFC-58 maps these ranges whatever the HTTP status, so a 400 carrying one is not
+      // invalid_argument.
+      if (first_error_code >= 24000 && first_error_code < 25000) {
+        ec = errc::analytics::compilation_failure;
+      } else if (first_error_code >= 20000 && first_error_code < 21000) {
+        ec = errc::common::authentication_failure;
+      } else if (first_error_code >= 25000 && first_error_code < 26000) {
+        ec = errc::common::internal_server_failure;
+      }
+      break;
+  }
+
+  if (!ec) {
+    ec = unmatched;
+  }
+
+  return ec;
+}
+
+} // namespace couchbase::core::operations

data/ext/couchbase/core/operations/analytics_response_parsing.hxx

@@ -0,0 +1,55 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-2021 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 "core/operations/document_analytics.hxx"
+
+#include <couchbase/error_codes.hxx>
+
+#include <tao/json/forward.hpp>
+
+#include <cstdint>
+#include <system_error>
+
+namespace couchbase::core::operations
+{
+
+/**
+ * Parse analytics meta-data fields (status, metrics, warnings, errors, signature, requestID,
+ * clientContextID) from a top-level response payload.
+ *
+ * Pure function — no side effects, no access to request state.
+ */
+auto
+parse_analytics_meta(const tao::json::value& payload) -> analytics_response::analytics_meta_data;
+
+/**
+ * Map analytics meta-data to an error_code.
+ *
+ * Pure classifier — no side effects, no exceptions thrown. Returns an empty error_code when the
+ * analytics query succeeded (meta.status == success and http_status is not 400).
+ *
+ * http_status is the status of the response that carried the metadata, or 0 where there is none.
+ * A failure that matches no specific mapping is invalid_argument for an HTTP 400 (RFC-58) and
+ * internal_server_failure otherwise.
+ */
+[[nodiscard]] auto
+map_analytics_error(const analytics_response::analytics_meta_data& meta,
+                    std::uint32_t http_status = 0) -> std::error_code;
+
+} // namespace couchbase::core::operations