couchbase 3.8.2 → 3.9.0

data/ext/couchbase/core/operations/management/scope_drop.cxx

@@ -45,7 +45,11 @@ scope_drop_request::make_response(error_context::http&& ctx,
   if (!response.ctx.ec) {
     switch (const auto& body = encoded.body.data(); encoded.status_code) {
       case 400:
-        response.ctx.ec = errc::common::unsupported_operation;
+        if (body.find("Not allowed on this version of cluster") != std::string_view::npos) {
+          response.ctx.ec = errc::common::unsupported_operation;
+        } else {
+          response.ctx.ec = errc::common::invalid_argument;
+        }
         break;
       case 404: {
         const auto prefix_pos = body.find("Scope with name ");

data/ext/couchbase/core/operations/management/scope_get_all.cxx

@@ -46,7 +46,12 @@ scope_get_all_request::make_response(error_context::http&& ctx,
   if (!response.ctx.ec) {
     switch (encoded.status_code) {
       case 400:
-        response.ctx.ec = errc::common::unsupported_operation;
+        if (encoded.body.data().find("Not allowed on this version of cluster") !=
+            std::string::npos) {
+          response.ctx.ec = errc::common::unsupported_operation;
+        } else {
+          response.ctx.ec = errc::common::invalid_argument;
+        }
         break;
       case 404:
         response.ctx.ec = errc::common::bucket_not_found;

data/ext/couchbase/core/operations/management/search_get_stats.cxx

@@ -16,6 +16,7 @@
  */
 
 #include "search_get_stats.hxx"
+#include "error_utils.hxx"
 
 #include <couchbase/error_codes.hxx>
 
@@ -37,6 +38,15 @@ search_get_stats_request::make_response(error_context::http&& ctx,
 {
   search_get_stats_response response{ std::move(ctx) };
   if (!response.ctx.ec) {
+    if (encoded.status_code == 401 || encoded.status_code == 403) {
+      // RFC-58: Search reports a 401 or 403 as an authentication failure.
+      response.ctx.ec = errc::common::authentication_failure;
+      return response;
+    }
+    if (encoded.status_code != 200) {
+      response.ctx.ec = extract_common_error_code(encoded.status_code, encoded.body.data());
+      return response;
+    }
     response.stats = encoded.body.data();
   }
   return response;

data/ext/couchbase/core/operations/management/search_index_analyze_document.cxx

@@ -41,9 +41,10 @@ search_index_analyze_document_request::encode_to(encoded_request_type& encoded,
     encoded.path = fmt::format("/api/bucket/{}/scope/{}/index/{}/analyzeDoc",
                                utils::string_codec::v2::path_escape(bucket_name.value()),
                                utils::string_codec::v2::path_escape(scope_name.value()),
-                               index_name);
+                               utils::string_codec::v2::path_escape(index_name));
   } else {
-    encoded.path = fmt::format("/api/index/{}/analyzeDoc", index_name);
+    encoded.path =
+      fmt::format("/api/index/{}/analyzeDoc", utils::string_codec::v2::path_escape(index_name));
   }
   encoded.body = encoded_document;
   return {};

data/ext/couchbase/core/operations/management/search_index_control_ingest.cxx

@@ -38,11 +38,12 @@ search_index_control_ingest_request::encode_to(encoded_request_type& encoded,
     encoded.path = fmt::format("/api/bucket/{}/scope/{}/index/{}/ingestControl/{}",
                                utils::string_codec::v2::path_escape(bucket_name.value()),
                                utils::string_codec::v2::path_escape(scope_name.value()),
-                               index_name,
+                               utils::string_codec::v2::path_escape(index_name),
                                pause ? "pause" : "resume");
   } else {
-    encoded.path =
-      fmt::format("/api/index/{}/ingestControl/{}", index_name, pause ? "pause" : "resume");
+    encoded.path = fmt::format("/api/index/{}/ingestControl/{}",
+                               utils::string_codec::v2::path_escape(index_name),
+                               pause ? "pause" : "resume");
   }
   return {};
 }

data/ext/couchbase/core/operations/management/search_index_control_plan_freeze.cxx

@@ -39,11 +39,12 @@ search_index_control_plan_freeze_request::encode_to(encoded_request_type& encode
     encoded.path = fmt::format("/api/bucket/{}/scope/{}/index/{}/planFreezeControl/{}",
                                utils::string_codec::v2::path_escape(bucket_name.value()),
                                utils::string_codec::v2::path_escape(scope_name.value()),
-                               index_name,
+                               utils::string_codec::v2::path_escape(index_name),
                                freeze ? "freeze" : "unfreeze");
   } else {
-    encoded.path =
-      fmt::format("/api/index/{}/planFreezeControl/{}", index_name, freeze ? "freeze" : "unfreeze");
+    encoded.path = fmt::format("/api/index/{}/planFreezeControl/{}",
+                               utils::string_codec::v2::path_escape(index_name),
+                               freeze ? "freeze" : "unfreeze");
   }
   return {};
 }

data/ext/couchbase/core/operations/management/search_index_control_query.cxx

@@ -38,11 +38,12 @@ search_index_control_query_request::encode_to(encoded_request_type& encoded,
     encoded.path = fmt::format("/api/bucket/{}/scope/{}/index/{}/queryControl/{}",
                                utils::string_codec::v2::path_escape(bucket_name.value()),
                                utils::string_codec::v2::path_escape(scope_name.value()),
-                               index_name,
+                               utils::string_codec::v2::path_escape(index_name),
                                allow ? "allow" : "disallow");
   } else {
-    encoded.path =
-      fmt::format("/api/index/{}/queryControl/{}", index_name, allow ? "allow" : "disallow");
+    encoded.path = fmt::format("/api/index/{}/queryControl/{}",
+                               utils::string_codec::v2::path_escape(index_name),
+                               allow ? "allow" : "disallow");
   }
   return {};
 }

data/ext/couchbase/core/operations/management/search_index_drop.cxx

@@ -38,9 +38,9 @@ search_index_drop_request::encode_to(encoded_request_type& encoded,
     encoded.path = fmt::format("/api/bucket/{}/scope/{}/index/{}",
                                utils::string_codec::v2::path_escape(bucket_name.value()),
                                utils::string_codec::v2::path_escape(scope_name.value()),
-                               index_name);
+                               utils::string_codec::v2::path_escape(index_name));
   } else {
-    encoded.path = fmt::format("/api/index/{}", index_name);
+    encoded.path = fmt::format("/api/index/{}", utils::string_codec::v2::path_escape(index_name));
   }
   return {};
 }

data/ext/couchbase/core/operations/management/search_index_get.cxx

@@ -39,9 +39,9 @@ search_index_get_request::encode_to(encoded_request_type& encoded,
     encoded.path = fmt::format("/api/bucket/{}/scope/{}/index/{}",
                                utils::string_codec::v2::path_escape(bucket_name.value()),
                                utils::string_codec::v2::path_escape(scope_name.value()),
-                               index_name);
+                               utils::string_codec::v2::path_escape(index_name));
   } else {
-    encoded.path = fmt::format("/api/index/{}", index_name);
+    encoded.path = fmt::format("/api/index/{}", utils::string_codec::v2::path_escape(index_name));
   }
   return {};
 }

data/ext/couchbase/core/operations/management/search_index_get_documents_count.cxx

@@ -36,9 +36,10 @@ search_index_get_documents_count_request::encode_to(encoded_request_type& encode
     encoded.path = fmt::format("/api/bucket/{}/scope/{}/index/{}/count",
                                utils::string_codec::v2::path_escape(bucket_name.value()),
                                utils::string_codec::v2::path_escape(scope_name.value()),
-                               index_name);
+                               utils::string_codec::v2::path_escape(index_name));
   } else {
-    encoded.path = fmt::format("/api/index/{}/count", index_name);
+    encoded.path =
+      fmt::format("/api/index/{}/count", utils::string_codec::v2::path_escape(index_name));
   }
   return {};
 }

data/ext/couchbase/core/operations/management/search_index_get_stats.cxx

@@ -18,6 +18,7 @@
 #include "search_index_get_stats.hxx"
 
 #include "core/utils/json.hxx"
+#include "core/utils/url_codec.hxx"
 #include "error_utils.hxx"
 
 #include <spdlog/fmt/bundled/core.h>
@@ -33,7 +34,8 @@ search_index_get_stats_request::encode_to(encoded_request_type& encoded,
     return errc::common::invalid_argument;
   }
   encoded.method = "GET";
-  encoded.path = fmt::format("/api/stats/index/{}", index_name);
+  encoded.path =
+    fmt::format("/api/stats/index/{}", utils::string_codec::v2::path_escape(index_name));
   return {};
 }
 

data/ext/couchbase/core/operations/management/search_index_upsert.cxx

@@ -41,9 +41,9 @@ search_index_upsert_request::encode_to(encoded_request_type& encoded,
     encoded.path = fmt::format("/api/bucket/{}/scope/{}/index/{}",
                                utils::string_codec::v2::path_escape(bucket_name.value()),
                                utils::string_codec::v2::path_escape(scope_name.value()),
-                               index.name);
+                               utils::string_codec::v2::path_escape(index.name));
   } else {
-    encoded.path = fmt::format("/api/index/{}", index.name);
+    encoded.path = fmt::format("/api/index/{}", utils::string_codec::v2::path_escape(index.name));
   }
   tao::json::value body{
     { "name", index.name },

data/ext/couchbase/core/operations/management/user_drop.cxx

@@ -18,6 +18,7 @@
 #include "user_drop.hxx"
 
 #include "core/management/rbac_fmt.hxx"
+#include "core/utils/url_codec.hxx"
 #include "error_utils.hxx"
 
 namespace couchbase::core::operations::management
@@ -27,7 +28,8 @@ user_drop_request::encode_to(encoded_request_type& encoded,
                              http_context& /* context */) const -> std::error_code
 {
   encoded.method = "DELETE";
-  encoded.path = fmt::format("/settings/rbac/users/{}/{}", domain, username);
+  encoded.path = fmt::format(
+    "/settings/rbac/users/{}/{}", domain, utils::string_codec::v2::path_escape(username));
   return {};
 }
 

data/ext/couchbase/core/operations/management/user_get.cxx

@@ -20,6 +20,7 @@
 #include "core/management/rbac_fmt.hxx"
 #include "core/management/rbac_json.hxx"
 #include "core/utils/json.hxx"
+#include "core/utils/url_codec.hxx"
 #include "error_utils.hxx"
 
 #include <tao/json/value.hpp>
@@ -31,7 +32,8 @@ user_get_request::encode_to(encoded_request_type& encoded,
                             http_context& /* context */) const -> std::error_code
 {
   encoded.method = "GET";
-  encoded.path = fmt::format("/settings/rbac/users/{}/{}", domain, username);
+  encoded.path = fmt::format(
+    "/settings/rbac/users/{}/{}", domain, utils::string_codec::v2::path_escape(username));
   encoded.headers["content-type"] = "application/x-www-form-urlencoded";
   return {};
 }

data/ext/couchbase/core/operations/management/user_upsert.cxx

@@ -32,39 +32,42 @@ user_upsert_request::encode_to(encoded_request_type& encoded,
                                http_context& /* context */) const -> std::error_code
 {
   encoded.method = "PUT";
-  encoded.path = fmt::format("/settings/rbac/users/{}/{}", domain, user.username);
+  encoded.path = fmt::format(
+    "/settings/rbac/users/{}/{}", domain, utils::string_codec::v2::path_escape(user.username));
   std::vector<std::string> params{};
   if (user.display_name) {
     params.push_back(
-      fmt::format("name={}", utils::string_codec::url_encode(user.display_name.value())));
+      fmt::format("name={}", utils::string_codec::form_encode(user.display_name.value())));
   }
   if (user.password) {
     params.push_back(
-      fmt::format("password={}", utils::string_codec::url_encode(user.password.value())));
+      fmt::format("password={}", utils::string_codec::form_encode(user.password.value())));
   }
   if (!user.groups.empty()) {
     const std::string encoded_groups = utils::join_strings(user.groups, ",");
-    params.push_back(fmt::format("groups={}", utils::string_codec::url_encode(encoded_groups)));
+    params.push_back(fmt::format("groups={}", utils::string_codec::form_encode(encoded_groups)));
   }
+  // Names go into the spec unescaped: the server does not percent-decode role parameters after
+  // form-decoding the body, so the spec is form-encoded exactly once, as a whole.
   std::vector<std::string> encoded_roles{};
   encoded_roles.reserve(user.roles.size());
   for (const auto& role : user.roles) {
     std::string spec = role.name;
     if (role.bucket) {
-      spec += fmt::format("[{}", utils::string_codec::v2::path_escape(role.bucket.value()));
+      spec += fmt::format("[{}", role.bucket.value());
       if (role.scope) {
-        spec += fmt::format(":{}", utils::string_codec::v2::path_escape(role.scope.value()));
+        spec += fmt::format(":{}", role.scope.value());
         if (role.collection) {
-          spec += fmt::format(":{}", utils::string_codec::v2::path_escape(role.collection.value()));
+          spec += fmt::format(":{}", role.collection.value());
         }
       }
-      spec += "]";
+      spec += ']';
     }
     encoded_roles.push_back(spec);
   }
   if (!encoded_roles.empty()) {
     const std::string concatenated = utils::join_strings(encoded_roles, ",");
-    params.push_back(fmt::format("roles={}", utils::string_codec::url_encode(concatenated)));
+    params.push_back(fmt::format("roles={}", utils::string_codec::form_encode(concatenated)));
   }
   encoded.body = utils::join_strings(params, "&");
   encoded.headers["content-type"] = "application/x-www-form-urlencoded";

data/ext/couchbase/core/operations/management/view_index_drop.cxx

@@ -33,7 +33,7 @@ view_index_drop_request::encode_to(encoded_request_type& encoded,
   encoded.path = fmt::format("/{}/_design/{}{}",
                              utils::string_codec::v2::path_escape(bucket_name),
                              ns == design_document_namespace::development ? "dev_" : "",
-                             document_name);
+                             utils::string_codec::v2::path_escape(document_name));
   return {};
 }
 

data/ext/couchbase/core/operations/management/view_index_get.cxx

@@ -34,7 +34,7 @@ view_index_get_request::encode_to(encoded_request_type& encoded,
   encoded.path = fmt::format("/{}/_design/{}{}",
                              utils::string_codec::v2::path_escape(bucket_name),
                              ns == design_document_namespace::development ? "dev_" : "",
-                             document_name);
+                             utils::string_codec::v2::path_escape(document_name));
   return {};
 }
 

data/ext/couchbase/core/operations/management/view_index_upsert.cxx

@@ -48,7 +48,7 @@ view_index_upsert_request::encode_to(encoded_request_type& encoded,
   encoded.path = fmt::format("/{}/_design/{}{}",
                              utils::string_codec::v2::path_escape(bucket_name),
                              document.ns == design_document_namespace::development ? "dev_" : "",
-                             document.name);
+                             utils::string_codec::v2::path_escape(document.name));
   encoded.body = utils::json::generate(body);
   return {};
 }

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

@@ -34,4 +34,22 @@ struct is_cancellable_operation : public std::false_type {
 
 template<typename T>
 inline constexpr bool is_cancellable_operation_v = is_cancellable_operation<T>::value;
+
+/**
+ * Operations that pick the node to dispatch to themselves, instead of being
+ * routed by the vbucket map alone.
+ *
+ * Specialize this only for a request that provides
+ * @c resolve_route(const topology::configuration&) returning an
+ * @c std::optional<impl::replica_route_decision>, and a writable @c partition
+ * member: that is the whole interface @c bucket::map_and_send() calls through
+ * this trait. An empty optional declines self-routing for that request, and the
+ * vbucket-map path routes it instead.
+ */
+template<typename T>
+struct resolves_own_route : public std::false_type {
+};
+
+template<typename T>
+inline constexpr bool resolves_own_route_v = resolves_own_route<T>::value;
 } // namespace couchbase::core::operations

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

@@ -0,0 +1,211 @@
+/* -*- 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 "query_response_parsing.hxx"
+
+#include "core/operations/management/error_utils.hxx"
+#include "core/utils/contains_string.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_query_meta(const tao::json::value& payload) -> query_response::query_meta_data
+{
+  query_response::query_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) {
+    meta.status = s->get_string();
+  }
+  if (const auto* s = payload.find("signature"); s != nullptr) {
+    meta.signature = couchbase::core::utils::json::generate(*s);
+  }
+  if (const auto* p = payload.find("profile"); p != nullptr) {
+    meta.profile = couchbase::core::utils::json::generate(*p);
+  }
+
+  if (const auto* m = payload.find("metrics"); m != nullptr) {
+    query_response::query_metrics metrics{};
+    metrics.result_count = m->at("resultCount").get_unsigned();
+    metrics.result_size = m->at("resultSize").get_unsigned();
+    metrics.elapsed_time = utils::parse_duration(m->at("elapsedTime").get_string());
+    metrics.execution_time = utils::parse_duration(m->at("executionTime").get_string());
+    metrics.sort_count = m->template optional<std::uint64_t>("sortCount").value_or(0);
+    metrics.mutation_count = m->template optional<std::uint64_t>("mutationCount").value_or(0);
+    metrics.error_count = m->template optional<std::uint64_t>("errorCount").value_or(0);
+    metrics.warning_count = m->template optional<std::uint64_t>("warningCount").value_or(0);
+    meta.metrics.emplace(metrics);
+  }
+
+  if (const auto* e = payload.find("errors"); e != nullptr) {
+    std::vector<query_response::query_problem> problems{};
+    for (const auto& err : e->get_array()) {
+      query_response::query_problem problem;
+      problem.code = err.at("code").get_unsigned();
+      problem.message = err.at("msg").get_string();
+      if (const auto* reason = err.find("reason"); reason != nullptr && reason->is_object()) {
+        problem.reason = reason->optional<std::uint64_t>("code");
+        problem.retry = reason->optional<bool>("retry");
+      }
+      problems.emplace_back(problem);
+    }
+    meta.errors.emplace(problems);
+  }
+
+  if (const auto* w = payload.find("warnings"); w != nullptr) {
+    std::vector<query_response::query_problem> problems{};
+    for (const auto& warn : w->get_array()) {
+      query_response::query_problem problem;
+      problem.code = warn.at("code").get_unsigned();
+      problem.message = warn.at("msg").get_string();
+      problems.emplace_back(problem);
+    }
+    meta.warnings.emplace(problems);
+  }
+
+  return meta;
+}
+
+auto
+map_query_error(const query_response::query_meta_data& meta, std::uint32_t http_status)
+  -> std::error_code
+{
+  const auto unmatched =
+    http_status == 400 ? errc::common::invalid_argument : errc::common::internal_server_failure;
+
+  if (meta.status == "success" && http_status != 400) {
+    return {};
+  }
+
+  if (!meta.errors || meta.errors->empty()) {
+    /* Unreachable from make_response, which only calls map_query_error after confirming
+     * errors is non-empty; present for the streaming-path caller, which has no such guard. */
+    return unmatched;
+  }
+
+  const auto& first = meta.errors->front();
+  const auto first_code = first.code;
+  const auto& first_message = first.message;
+
+  std::error_code ec{};
+
+  switch (first_code) {
+    case 1065: /* IKey: "service.io.request.unrecognized_parameter" */
+      if ((first_message.find("Unrecognized parameter in request") != std::string::npos) &&
+          (first_message.find("preserve_expiry") != std::string::npos)) {
+        ec = errc::common::feature_not_available;
+      } else {
+        ec = errc::common::invalid_argument;
+      }
+      break;
+    case 1080: /* IKey: "timeout" */
+      ec = errc::common::unambiguous_timeout;
+      break;
+    case 3000: /* IKey: "parse.syntax_error" */
+      ec = errc::common::parsing_failure;
+      break;
+    case 4040: /* IKey: "plan.build_prepared.no_such_name" */
+    case 4050: /* IKey: "plan.build_prepared.unrecognized_prepared" */
+    case 4060: /* IKey: "plan.build_prepared.no_such_name" */
+    case 4070: /* IKey: "plan.build_prepared.decoding" */
+    case 4080: /* IKey: "plan.build_prepared.name_encoded_plan_mismatch" */
+    case 4090: /* IKey: "plan.build_prepared.name_not_in_encoded_plan" */
+      /* NOTE: make_response also does cache.erase + throw retry_http_request for codes
+       * 4040/4050/4070. That stateful logic stays in make_response. This pure classifier
+       * returns prepared_statement_failure so callers (e.g. streaming path) get a
+       * non-empty error_code. */
+      ec = errc::query::prepared_statement_failure;
+      break;
+    case 4300: /* IKey: "plan.new_index_already_exists" */
+      ec = errc::common::index_exists;
+      break;
+    case 5000: /* IKey: "Internal Error" */
+      if (utils::contains_string(first_message, "index", true) &&
+          utils::contains_string(first_message, "already exist", true)) {
+        ec = errc::common::index_exists;
+      } else if (utils::contains_string(first_message, "Index does not exist") ||
+                 (utils::contains_string(first_message, "index", true) &&
+                  utils::contains_string(first_message, "not found", true))) {
+        ec = errc::common::index_not_found;
+      } else if (first_message.find("Bucket Not Found") != std::string::npos) {
+        ec = errc::common::bucket_not_found;
+      }
+      break;
+    case 12009: /* IKey: "datastore.couchbase.DML_error" */
+      if (first_message.find("CAS mismatch") != std::string::npos) {
+        ec = errc::common::cas_mismatch;
+      } else {
+        switch (first.reason.value_or(0)) {
+          case 12033:
+            ec = errc::common::cas_mismatch;
+            break;
+          case 17014:
+            ec = errc::key_value::document_not_found;
+            break;
+          case 17012:
+            ec = errc::key_value::document_exists;
+            break;
+          default:
+            ec = errc::query::dml_failure;
+            break;
+        }
+      }
+      break;
+    case 12004: /* IKey: "datastore.couchbase.primary_idx_not_found" */
+    case 12016: /* IKey: "datastore.couchbase.index_not_found" */
+      ec = errc::common::index_not_found;
+      break;
+    case 13014: /* IKey: "datastore.couchbase.insufficient_credentials" */
+      ec = errc::common::authentication_failure;
+      break;
+    default:
+      if ((first_code >= 12000 && first_code < 13000) ||
+          (first_code >= 14000 && first_code < 15000)) {
+        ec = errc::query::index_failure;
+      } else if (first_code >= 4000 && first_code < 5000) {
+        ec = errc::query::planning_failure;
+      }
+      break;
+  }
+
+  if (!ec) {
+    auto common_ec = management::extract_common_query_error_code(first_code, first_message);
+    if (common_ec) {
+      ec = common_ec.value();
+    }
+  }
+
+  if (!ec) {
+    ec = unmatched;
+  }
+
+  return ec;
+}
+
+} // namespace couchbase::core::operations

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

@@ -0,0 +1,60 @@
+/* -*- 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_query.hxx"
+
+#include <couchbase/error_codes.hxx>
+
+#include <tao/json/forward.hpp>
+
+#include <cstdint>
+#include <system_error>
+
+namespace couchbase::core::operations
+{
+
+/**
+ * Parse query meta-data fields (status, metrics, warnings, errors, signature, profile,
+ * requestID, clientContextID) from a top-level response payload.
+ *
+ * Pure function — no side effects, no access to request state.
+ */
+auto
+parse_query_meta(const tao::json::value& payload) -> query_response::query_meta_data;
+
+/**
+ * Map query meta-data to an error_code.
+ *
+ * Pure classifier — no side effects, no cache mutations, no exceptions thrown.
+ * All prepared-statement codes (4040/4050/4060/4070/4080/4090) are classified as
+ * prepared_statement_failure here; the cache-erase + retry_http_request throw remains in
+ * make_response and applies only to the 4040/4050/4070 subset.
+ *
+ * Returns an empty error_code when the query succeeded (meta.status == "success", http_status is
+ * not 400, and no prepared-statement retry needed).
+ *
+ * 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_query_error(const query_response::query_meta_data& meta, std::uint32_t http_status = 0)
+  -> std::error_code;
+
+} // namespace couchbase::core::operations

data/ext/couchbase/core/operations_fwd.hxx

@@ -28,8 +28,6 @@ struct s3_external_link;
 
 namespace impl
 {
-struct get_replica_request;
-struct get_replica_response;
 struct lookup_in_replica_request;
 struct lookup_in_replica_response;
 struct observe_seqno_request;
@@ -51,6 +49,8 @@ struct decrement_response;
 struct exists_request;
 struct exists_response;
 struct get_request;
+struct get_replica_request;
+struct get_replica_response;
 struct get_response;
 struct get_all_replicas_request;
 struct get_all_replicas_response;
@@ -106,7 +106,7 @@ using replace_request_with_legacy_durability = impl::with_legacy_durability<repl
 using upsert_request_with_legacy_durability = impl::with_legacy_durability<upsert_request>;
 
 using get_request_with_cancellation = impl::with_cancellation<get_request>;
-using get_replica_request_with_cancellation = impl::with_cancellation<impl::get_replica_request>;
+using get_replica_request_with_cancellation = impl::with_cancellation<get_replica_request>;
 using lookup_in_request_with_cancellation = impl::with_cancellation<lookup_in_request>;
 using lookup_in_replica_request_with_cancellation =
   impl::with_cancellation<impl::lookup_in_replica_request>;