couchbase 3.8.2 → 3.9.0

data/ext/couchbase/core/protostellar/search_converter.hxx

@@ -0,0 +1,244 @@
+/* -*- 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
+
+// Translates the core FTS search request/response to and from couchbase.search.v1. Hits arrive
+// across streamed SearchQueryResponse messages and are buffered into search_response::rows; the
+// terminal message carries the metadata.
+//
+// The couchbase2 SearchQueryRequest models the FTS query as a structured `Query` oneof of 21 types,
+// whereas the core request carries an opaque pre-serialized JSON `query`. This converter translates
+// the trivial forms -- query_string (optionally boosted), match_all and match_none -- and reports
+// every other shape as unmappable so the component surfaces feature_not_available. Structured
+// facets, structured sort specs, vector search, mutation-token consistency, the `raw`
+// passthrough, and score fusion (rrf/rsf) have no couchbase2 home and are likewise gated;
+// `scoring(none())` predates fusion and maps onto the protocol's existing disable_scoring field, so
+// it is not gated. Translating the remaining eighteen query arms is a follow-up; the gate is what
+// keeps an untranslated one from being dropped in silence in the meantime.
+
+#include "core/operations/document_search.hxx"
+#include "core/utils/json.hxx"
+
+#include <couchbase/search/v1/search.pb.h>
+
+// core/utils/json.hxx only forward-declares tao::json::value; this header instantiates one and
+// calls its members, so it needs the full definition.
+#include <tao/json/value.hpp>
+
+#include <chrono>
+#include <cstdint>
+#include <optional>
+#include <string>
+#include <vector>
+
+namespace couchbase::core::protostellar::search
+{
+namespace v1 = ::couchbase::search::v1;
+
+// Coarse, cheap gate for request features with no couchbase2 mapping. Query-shape support is
+// decided in encode() (which must parse the query JSON).
+[[nodiscard]] inline auto
+can_encode(const operations::search_request& request) -> bool
+{
+  return request.raw.empty() && request.facets.empty() && request.sort_specs.empty() &&
+         request.mutation_state.empty() && !request.vector_search.has_value() &&
+         !request.vector_query_combination.has_value() && !request.row_callback.has_value() &&
+         !couchbase::core::is_score_fusion(request.scoring);
+}
+
+// True when request.query does not parse as JSON at all, as opposed to parsing into a shape this
+// converter does not translate. The component maps the two to different errors: a query the caller
+// failed to serialize is their own invalid_argument, not a gap in couchbase2 support.
+[[nodiscard]] inline auto
+query_is_malformed(const operations::search_request& request) -> bool
+{
+  try {
+    static_cast<void>(utils::json::parse(request.query));
+  } catch (...) {
+    return true;
+  }
+  return false;
+}
+
+// Translate the parsed core query JSON into the structured Query oneof, for the trivial forms only.
+// Returns false, leaving proto.query unset, for every shape this converter does not translate.
+[[nodiscard]] inline auto
+apply_query(const tao::json::value& parsed, v1::SearchQueryRequest& proto) -> bool
+{
+  if (!parsed.is_object()) {
+    return false;
+  }
+  // A boost is serialized beside the query key rather than inside it: query_string("foo").boost(2)
+  // encodes as {"query":"foo","boost":2}. Rejecting every two-key object would therefore make an
+  // ordinary boosted query unroutable, so a boost is read as a modifier of the recognized key.
+  // Whether it can actually be carried depends on the arm, and is decided below. Any other sibling
+  // (an analyzer, a field) would be lost in translation, so a wider object is reported as
+  // unmappable and the component surfaces feature_not_available.
+  const auto* boost = parsed.find("boost");
+  if (parsed.get_object().size() > (boost == nullptr ? 1U : 2U)) {
+    return false;
+  }
+  const auto* match_all = parsed.find("match_all");
+  const auto* match_none = parsed.find("match_none");
+  if (match_all != nullptr || match_none != nullptr) {
+    // MatchAllQuery and MatchNoneQuery are empty messages, so a boost on either has nowhere to go.
+    // Refusing the request keeps it from being run at a weight the caller did not ask for.
+    if (boost != nullptr) {
+      return false;
+    }
+    if (match_all != nullptr) {
+      proto.mutable_query()->mutable_match_all_query();
+    } else {
+      proto.mutable_query()->mutable_match_none_query();
+    }
+    return true;
+  }
+  if (const auto* q = parsed.find("query"); q != nullptr && q->is_string()) {
+    auto* query_string = proto.mutable_query()->mutable_query_string_query();
+    query_string->set_query_string(q->get_string());
+    if (boost != nullptr) {
+      if (!boost->is_number()) {
+        return false;
+      }
+      query_string->set_boost(static_cast<float>(boost->as<double>()));
+    }
+    return true;
+  }
+  return false;
+}
+
+// Encode the request; returns nullopt for a gated feature, an untranslated query shape, or a query
+// that is not JSON. The component separates the last case with query_is_malformed().
+[[nodiscard]] inline auto
+encode(const operations::search_request& request) -> std::optional<v1::SearchQueryRequest>
+{
+  if (!can_encode(request)) {
+    return std::nullopt;
+  }
+  v1::SearchQueryRequest proto;
+  proto.set_index_name(request.index_name);
+  if (request.bucket_name.has_value()) {
+    proto.set_bucket_name(*request.bucket_name);
+  }
+  if (request.scope_name.has_value()) {
+    proto.set_scope_name(*request.scope_name);
+  }
+  tao::json::value parsed;
+  try {
+    parsed = utils::json::parse(request.query);
+  } catch (...) {
+    return std::nullopt;
+  }
+  if (!apply_query(parsed, proto)) {
+    return std::nullopt;
+  }
+  if (request.limit.has_value()) {
+    proto.set_limit(*request.limit);
+  }
+  if (request.skip.has_value()) {
+    proto.set_skip(*request.skip);
+  }
+  if (request.explain.value_or(false)) {
+    proto.set_include_explanation(true);
+  }
+  proto.set_disable_scoring(
+    request.disable_scoring ||
+    std::holds_alternative<couchbase::core::search_scoring_none>(request.scoring));
+  proto.set_include_locations(request.include_locations);
+  proto.set_scan_consistency(v1::SearchQueryRequest_ScanConsistency_SCAN_CONSISTENCY_NOT_BOUNDED);
+  if (request.highlight_style.has_value()) {
+    proto.set_highlight_style(*request.highlight_style == search_highlight_style::ansi
+                                ? v1::SearchQueryRequest_HighlightStyle_HIGHLIGHT_STYLE_ANSI
+                                : v1::SearchQueryRequest_HighlightStyle_HIGHLIGHT_STYLE_HTML);
+  }
+  for (const auto& field : request.highlight_fields) {
+    proto.add_highlight_fields(field);
+  }
+  for (const auto& field : request.fields) {
+    proto.add_fields(field);
+  }
+  for (const auto& collection : request.collections) {
+    proto.add_collections(collection);
+  }
+  return proto;
+}
+
+// Append the hits from one streamed message onto the buffered response and, if present, decode the
+// terminal metadata. Structured facets are gated by can_encode(), so a response cannot carry any.
+inline void
+decode(const v1::SearchQueryResponse& message, operations::search_response& response)
+{
+  for (const auto& hit : message.hits()) {
+    operations::search_response::search_row row;
+    row.index = hit.index();
+    row.id = hit.id();
+    row.score = hit.score();
+    row.explanation = hit.explanation();
+    for (const auto& [field, fragment] : hit.fragments()) {
+      row.fragments[field] =
+        std::vector<std::string>{ fragment.content().begin(), fragment.content().end() };
+    }
+    // The proto keys each requested field to its value as raw JSON, whereas the core row carries
+    // the whole set as one JSON object, so the object is reassembled here.
+    if (!hit.fields().empty()) {
+      tao::json::value fields = tao::json::empty_object;
+      for (const auto& [name, value] : hit.fields()) {
+        try {
+          fields[name] = utils::json::parse(value);
+        } catch (...) {
+          // decode() runs on the io_context out of a stream callback, where an escaping exception
+          // would take down the loop. A value that is not JSON is kept verbatim as a string so the
+          // field still reaches the caller.
+          fields[name] = value;
+        }
+      }
+      row.fields = utils::json::generate(fields);
+    }
+    for (const auto& location : hit.locations()) {
+      operations::search_response::search_location out;
+      out.field = location.field();
+      out.term = location.term();
+      out.position = location.position();
+      out.start_offset = location.start();
+      out.end_offset = location.end();
+      if (location.array_positions_size() > 0) {
+        out.array_positions = std::vector<std::uint64_t>{ location.array_positions().begin(),
+                                                          location.array_positions().end() };
+      }
+      row.locations.push_back(std::move(out));
+    }
+    response.rows.push_back(std::move(row));
+  }
+  if (message.has_meta_data()) {
+    const auto& meta = message.meta_data();
+    if (meta.has_metrics()) {
+      const auto& m = meta.metrics();
+      response.meta.metrics.took = std::chrono::seconds{ m.execution_time().seconds() } +
+                                   std::chrono::nanoseconds{ m.execution_time().nanos() };
+      response.meta.metrics.total_rows = m.total_rows();
+      response.meta.metrics.max_score = m.max_score();
+      response.meta.metrics.success_partition_count = m.success_partition_count();
+      response.meta.metrics.error_partition_count = m.error_partition_count();
+    }
+    for (const auto& [location, msg] : meta.errors()) {
+      response.meta.errors.try_emplace(location, msg);
+    }
+  }
+}
+
+} // namespace couchbase::core::protostellar::search

data/ext/couchbase/core/protostellar/search_index_admin_converter.hxx

@@ -0,0 +1,156 @@
+/* -*- 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
+
+// Translates core FTS index settings to and from couchbase.admin.search.v1. The one non-trivial
+// bit: core stores params/plan_params/source_params as single JSON-object strings, while the proto
+// Index uses map<string,bytes> keyed by the object's top-level members (each value a raw-JSON
+// blob). fill_params/params_to_json round-trip between the two representations.
+//
+// Every conversion that can lose a member reports failure instead. A definition that cannot be
+// represented must not be truncated in silence: the caller edits what get_index returned and
+// upserts it back, so a dropped member deletes part of the index definition while the call reports
+// success.
+
+#include "core/management/search_index.hxx"
+#include "core/utils/json.hxx"
+
+#include <tao/json/value.hpp>
+
+#include <couchbase/admin/search/v1/search.pb.h>
+
+#include <google/protobuf/map.h>
+
+#include <optional>
+#include <string>
+
+namespace couchbase::core::protostellar::search_index_admin
+{
+namespace v1 = ::couchbase::admin::search::v1;
+
+// Explode a JSON-object string into the proto map: one entry per top-level member, value = the
+// member's raw JSON. An empty input is the "unset" convention and contributes nothing. Anything
+// that is not a JSON object has no representation in the map and is refused.
+[[nodiscard]] inline auto
+fill_params(const std::string& json, ::google::protobuf::Map<std::string, std::string>* target)
+  -> bool
+{
+  if (json.empty()) {
+    return true;
+  }
+  tao::json::value parsed;
+  try {
+    parsed = utils::json::parse(json);
+  } catch (...) {
+    return false;
+  }
+  if (!parsed.is_object()) {
+    return false;
+  }
+  for (const auto& [key, value] : parsed.get_object()) {
+    (*target)[key] = utils::json::generate(value);
+  }
+  return true;
+}
+
+// Rebuild a JSON-object string from the proto map (inverse of fill_params). Empty map -> empty
+// string so the core struct keeps its "unset" convention. A member whose bytes are not JSON cannot
+// be placed in the object, and dropping it would hand back a definition short of what the server
+// holds, so the whole conversion fails.
+[[nodiscard]] inline auto
+params_to_json(const ::google::protobuf::Map<std::string, std::string>& source)
+  -> std::optional<std::string>
+{
+  if (source.empty()) {
+    return std::string{};
+  }
+  tao::json::value object = tao::json::empty_object;
+  for (const auto& [key, value] : source) {
+    try {
+      object[key] = utils::json::parse(value);
+    } catch (...) {
+      return {};
+    }
+  }
+  return utils::json::generate(object);
+}
+
+// The fields shared by CreateIndexRequest and Index. The two messages carry the same index
+// definition under the same field names, but they are unrelated proto types and neither derives
+// from the other, so the assignments are written once against whichever is passed.
+template<typename Proto>
+[[nodiscard]] auto
+apply_index_fields(const management::search::index& index, Proto& proto) -> bool
+{
+  proto.set_name(index.name);
+  proto.set_type(index.type);
+  if (!index.source_name.empty()) {
+    proto.set_source_name(index.source_name);
+  }
+  if (!index.source_type.empty()) {
+    proto.set_source_type(index.source_type);
+  }
+  if (!index.source_uuid.empty()) {
+    proto.set_source_uuid(index.source_uuid);
+  }
+  return fill_params(index.params_json, proto.mutable_params()) &&
+         fill_params(index.plan_params_json, proto.mutable_plan_params()) &&
+         fill_params(index.source_params_json, proto.mutable_source_params());
+}
+
+// Encode a core index into a CreateIndexRequest. A create carries no uuid: an upsert that supplies
+// one is an update and goes to UpdateIndex instead.
+[[nodiscard]] inline auto
+apply_index(const management::search::index& index, v1::CreateIndexRequest& proto) -> bool
+{
+  return apply_index_fields(index, proto);
+}
+
+// Encode a core index into the Index of an UpdateIndexRequest. The uuid is what makes it an
+// update: the gateway rejects the call without one, and the server matches it against the current
+// definition so a concurrent update is not overwritten.
+[[nodiscard]] inline auto
+apply_index(const management::search::index& index, v1::Index& proto) -> bool
+{
+  proto.set_uuid(index.uuid);
+  return apply_index_fields(index, proto);
+}
+
+[[nodiscard]] inline auto
+decode_index(const v1::Index& proto) -> std::optional<management::search::index>
+{
+  auto params = params_to_json(proto.params());
+  auto plan_params = params_to_json(proto.plan_params());
+  auto source_params = params_to_json(proto.source_params());
+  if (!params.has_value() || !plan_params.has_value() || !source_params.has_value()) {
+    return {};
+  }
+  management::search::index index;
+  index.uuid = proto.uuid();
+  index.name = proto.name();
+  index.type = proto.type();
+  index.source_uuid = proto.source_uuid();
+  index.source_name = proto.source_name();
+  index.source_type = proto.source_type();
+  index.params_json = std::move(*params);
+  index.plan_params_json = std::move(*plan_params);
+  index.source_params_json = std::move(*source_params);
+  return index;
+}
+
+} // namespace couchbase::core::protostellar::search_index_admin

data/ext/couchbase/core/protostellar/view_converter.hxx

@@ -0,0 +1,158 @@
+/* -*- 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
+
+// Views are deprecated in the core API but still routable over couchbase2; suppress the core
+// deprecation attribute for this header. push/pop the macro so an including translation unit that
+// already defined it keeps its state restored, rather than having it clobbered at the bottom.
+#pragma push_macro("COUCHBASE_CXX_CLIENT_IGNORE_CORE_DEPRECATIONS")
+#define COUCHBASE_CXX_CLIENT_IGNORE_CORE_DEPRECATIONS
+
+// Translates the core map/reduce view request/response to and from couchbase.view.v1. Rows arrive
+// across streamed ViewQueryResponse messages and are buffered into document_view_response::rows;
+// the terminal message carries the metadata.
+//
+// The couchbase2 ViewQueryRequest has no home for the core request's `raw`, `query_string`,
+// `full_set`, or streaming `row_callback` fields; can_encode() reports those so the component
+// surfaces feature_not_available rather than silently dropping them. The proto `limit`/`skip` are
+// uint32 while core carries uint64, so can_encode() also rejects values that would truncate.
+// `client_context_id`/`timeout` likewise have no proto field but do not change results, so they are
+// simply not sent.
+
+#include "core/operations/document_view.hxx"
+
+#include <couchbase/view/v1/view.pb.h>
+
+#include <cstdint>
+#include <limits>
+#include <string>
+
+namespace couchbase::core::protostellar::view
+{
+namespace v1 = ::couchbase::view::v1;
+
+[[nodiscard]] inline auto
+can_encode(const operations::document_view_request& request) -> bool
+{
+  constexpr auto u32_max = (std::numeric_limits<std::uint32_t>::max)();
+  return request.raw.empty() && request.query_string.empty() && !request.full_set.value_or(false) &&
+         !request.row_callback.has_value() && request.limit.value_or(0) <= u32_max &&
+         request.skip.value_or(0) <= u32_max;
+}
+
+inline auto
+encode(const operations::document_view_request& request) -> v1::ViewQueryRequest
+{
+  v1::ViewQueryRequest proto;
+  proto.set_bucket_name(request.bucket_name);
+  proto.set_design_document_name(request.document_name);
+  proto.set_view_name(request.view_name);
+  proto.set_namespace_(request.ns == design_document_namespace::development
+                         ? v1::ViewQueryRequest_Namespace_NAMESPACE_DEVELOPMENT
+                         : v1::ViewQueryRequest_Namespace_NAMESPACE_PRODUCTION);
+
+  for (const auto& key : request.keys) {
+    proto.add_keys(key);
+  }
+  if (request.key.has_value()) {
+    proto.set_key(*request.key);
+  }
+  if (request.start_key.has_value()) {
+    proto.set_start_key(*request.start_key);
+  }
+  if (request.end_key.has_value()) {
+    proto.set_end_key(*request.end_key);
+  }
+  if (request.start_key_doc_id.has_value()) {
+    proto.set_start_key_doc_id(*request.start_key_doc_id);
+  }
+  if (request.end_key_doc_id.has_value()) {
+    proto.set_end_key_doc_id(*request.end_key_doc_id);
+  }
+  if (request.limit.has_value()) {
+    proto.set_limit(static_cast<std::uint32_t>(*request.limit));
+  }
+  if (request.skip.has_value()) {
+    proto.set_skip(static_cast<std::uint32_t>(*request.skip));
+  }
+  if (request.reduce.has_value()) {
+    proto.set_reduce(*request.reduce);
+  }
+  if (request.group.has_value()) {
+    proto.set_group(*request.group);
+  }
+  if (request.group_level.has_value()) {
+    proto.set_group_level(*request.group_level);
+  }
+  if (request.inclusive_end.has_value()) {
+    proto.set_inclusive_end(*request.inclusive_end);
+  }
+  proto.set_debug(request.debug);
+  if (request.consistency.has_value()) {
+    switch (*request.consistency) {
+      case view_scan_consistency::not_bounded:
+        proto.set_scan_consistency(
+          v1::ViewQueryRequest_ScanConsistency_SCAN_CONSISTENCY_NOT_BOUNDED);
+        break;
+      case view_scan_consistency::update_after:
+        proto.set_scan_consistency(
+          v1::ViewQueryRequest_ScanConsistency_SCAN_CONSISTENCY_UPDATE_AFTER);
+        break;
+      case view_scan_consistency::request_plus:
+        proto.set_scan_consistency(
+          v1::ViewQueryRequest_ScanConsistency_SCAN_CONSISTENCY_REQUEST_PLUS);
+        break;
+    }
+  }
+  if (request.order.has_value()) {
+    proto.set_order(*request.order == view_sort_order::descending
+                      ? v1::ViewQueryRequest_Order_ORDER_DESCENDING
+                      : v1::ViewQueryRequest_Order_ORDER_ASCENDING);
+  }
+  if (request.on_error.has_value()) {
+    proto.set_on_error(*request.on_error == view_on_error::stop
+                         ? v1::ViewQueryRequest_ErrorMode_ERROR_MODE_STOP
+                         : v1::ViewQueryRequest_ErrorMode_ERROR_MODE_CONTINUE);
+  }
+  return proto;
+}
+
+// Append the rows from one streamed message onto the buffered response.
+inline void
+decode_rows(const v1::ViewQueryResponse& message, operations::document_view_response& response)
+{
+  for (const auto& row : message.rows()) {
+    operations::document_view_response::row out;
+    if (!row.id().empty()) {
+      out.id = row.id();
+    }
+    out.key = row.key();
+    out.value = row.value();
+    response.rows.push_back(std::move(out));
+  }
+  if (message.has_meta_data()) {
+    response.meta.total_rows = message.meta_data().total_rows();
+    if (!message.meta_data().debug().empty()) {
+      response.meta.debug_info = message.meta_data().debug();
+    }
+  }
+}
+
+} // namespace couchbase::core::protostellar::view
+
+#pragma pop_macro("COUCHBASE_CXX_CLIENT_IGNORE_CORE_DEPRECATIONS")