couchbase 3.8.1 → 3.9.0

data/ext/couchbase/core/protocol/cmd_mutate_in.cxx

@@ -44,12 +44,12 @@ mutate_in_response_body::parse(key_value_status_code status,
     if (extras_size == 16) {
       std::uint64_t partition_uuid{};
       memcpy(&partition_uuid, body.data() + offset, sizeof(partition_uuid));
-      partition_uuid = utils::byte_swap(partition_uuid);
+      partition_uuid = utils::network_to_host(partition_uuid);
       offset += 8;
 
       std::uint64_t sequence_number{};
       memcpy(&sequence_number, body.data() + offset, sizeof(sequence_number));
-      sequence_number = utils::byte_swap(sequence_number);
+      sequence_number = utils::network_to_host(sequence_number);
 
       token_ = couchbase::utils::build_mutation_token(partition_uuid, sequence_number);
       offset += 8;
@@ -66,7 +66,7 @@ mutate_in_response_body::parse(key_value_status_code status,
 
       std::uint16_t entry_status = 0;
       memcpy(&entry_status, body.data() + offset, sizeof(entry_status));
-      entry_status = utils::byte_swap(entry_status);
+      entry_status = utils::network_to_host(entry_status);
       Expects(is_valid_status(entry_status));
       field.status = static_cast<key_value_status_code>(entry_status);
       offset += static_cast<offset_type>(sizeof(entry_status));
@@ -74,7 +74,7 @@ mutate_in_response_body::parse(key_value_status_code status,
       if (field.status == key_value_status_code::success) {
         std::uint32_t entry_size = 0;
         memcpy(&entry_size, body.data() + offset, sizeof(entry_size));
-        entry_size = utils::byte_swap(entry_size);
+        entry_size = utils::network_to_host(entry_size);
         Expects(entry_size < 20 * 1024 * 1024);
         offset += static_cast<offset_type>(sizeof(entry_size));
 
@@ -117,16 +117,16 @@ mutate_in_request_body::fill_extras()
 {
   if (expiry_ != 0 || user_flags_) {
     extras_.resize(sizeof(expiry_));
-    std::uint32_t field = utils::byte_swap(expiry_);
+    std::uint32_t field = utils::host_to_network(expiry_);
     memcpy(extras_.data(), &field, sizeof(field));
   }
   if (user_flags_) {
     const std::size_t offset = extras_.size();
     extras_.resize(offset + sizeof(std::uint32_t));
-    std::uint32_t field = utils::byte_swap(user_flags_.value());
+    std::uint32_t field = utils::host_to_network(user_flags_.value());
     memcpy(extras_.data() + offset, &field, sizeof(field));
   }
-  if (flags_ != std::byte{ 0U }) {
+  if (flags_ != std::uint8_t{ 0U }) {
     const std::size_t offset = extras_.size();
     extras_.resize(offset + sizeof(flags_));
     extras_[offset] = std::byte{ flags_ };
@@ -150,12 +150,13 @@ mutate_in_request_body::fill_value()
     value_[offset] = spec.flags_;
     ++offset;
 
-    std::uint16_t path_size = utils::byte_swap(gsl::narrow_cast<std::uint16_t>(spec.path_.size()));
+    std::uint16_t path_size =
+      utils::host_to_network(gsl::narrow_cast<std::uint16_t>(spec.path_.size()));
     std::memcpy(value_.data() + offset, &path_size, sizeof(path_size));
     offset += sizeof(path_size);
 
     std::uint32_t param_size =
-      utils::byte_swap(gsl::narrow_cast<std::uint32_t>(spec.value_.size()));
+      utils::host_to_network(gsl::narrow_cast<std::uint32_t>(spec.value_.size()));
     std::memcpy(value_.data() + offset, &param_size, sizeof(param_size));
     offset += sizeof(param_size);
 

data/ext/couchbase/core/protocol/cmd_mutate_in.hxx

@@ -81,33 +81,33 @@ public:
    * `path_flag_create_parents`. and `upsert` mutation semantics. Not valid with
    * `insert`.
    */
-  static constexpr std::byte doc_flag_mkdoc{ 0b0000'0001U };
+  static constexpr std::uint8_t doc_flag_mkdoc{ 0b0000'0001U };
 
   /**
    * Add the document only if it does not exist. Implies
    * `path_flag_create_parents`. Not valid with `doc_flag_mkdoc`.
    */
-  static constexpr std::byte doc_flag_add{ 0b0000'0010U };
+  static constexpr std::uint8_t doc_flag_add{ 0b0000'0010U };
 
   /**
    * Allow access to XATTRs for deleted documents (instead of returning
    * KEY_ENOENT).
    */
-  static constexpr std::byte doc_flag_access_deleted{ 0b0000'0100U };
+  static constexpr std::uint8_t doc_flag_access_deleted{ 0b0000'0100U };
 
   /**
    * Used with `doc_flag_mkdoc` / `doc_flag_add`; if the document does not exist
    * then create it in the "Deleted" state, instead of the normal "Alive" state.
    * Not valid unless `doc_flag_mkdoc` or `doc_flag_add` specified.
    */
-  static constexpr std::byte doc_flag_create_as_deleted{ 0b0000'1000U };
+  static constexpr std::uint8_t doc_flag_create_as_deleted{ 0b0000'1000U };
 
   /**
    * If the document exists and isn't deleted the operation will fail with .
    * If the input document _is_ deleted the result of the operation will store
    * the document as a "live" document instead of a deleted document.
    */
-  static constexpr std::byte doc_flag_revive_document{ 0b0001'0000U };
+  static constexpr std::uint8_t doc_flag_revive_document{ 0b0001'0000U };
 
 private:
   std::vector<std::byte> key_;
@@ -116,7 +116,7 @@ private:
 
   std::optional<std::uint32_t> user_flags_{};
   std::uint32_t expiry_{ 0 };
-  std::byte flags_{ 0 };
+  std::uint8_t flags_{ 0 };
   std::vector<couchbase::core::impl::subdoc::command> specs_;
   std::vector<std::byte> framing_extras_{};
 
@@ -138,7 +138,7 @@ public:
     if (value) {
       flags_ |= doc_flag_access_deleted;
     } else {
-      flags_ &= ~doc_flag_access_deleted;
+      flags_ &= static_cast<std::uint8_t>(~doc_flag_access_deleted);
     }
   }
 
@@ -147,7 +147,7 @@ public:
     if (value) {
       flags_ |= doc_flag_create_as_deleted;
     } else {
-      flags_ &= ~doc_flag_create_as_deleted;
+      flags_ &= static_cast<std::uint8_t>(~doc_flag_create_as_deleted);
     }
   }
 
@@ -156,13 +156,13 @@ public:
     if (value) {
       flags_ |= doc_flag_revive_document;
     } else {
-      flags_ &= ~doc_flag_revive_document;
+      flags_ &= static_cast<std::uint8_t>(~doc_flag_revive_document);
     }
   }
 
   void store_semantics(couchbase::store_semantics semantics)
   {
-    flags_ &= std::byte{ 0b1111'1100U }; /* reset first two bits */
+    flags_ &= static_cast<std::uint8_t>(0b1111'1100U); /* reset first two bits */
     switch (semantics) {
       case couchbase::store_semantics::replace:
         /* leave bits as zeros */

data/ext/couchbase/core/protocol/cmd_observe_seqno.cxx

@@ -45,32 +45,32 @@ observe_seqno_response_body::parse(key_value_status_code status,
     ++offset;
 
     memcpy(&partition_id_, body.data() + offset, sizeof(partition_id_));
-    partition_id_ = utils::byte_swap(partition_id_);
+    partition_id_ = utils::network_to_host(partition_id_);
     offset += static_cast<offset_type>(sizeof(partition_id_));
 
     memcpy(&partition_uuid_, body.data() + offset, sizeof(partition_uuid_));
-    partition_uuid_ = utils::byte_swap(partition_uuid_);
+    partition_uuid_ = utils::network_to_host(partition_uuid_);
     offset += static_cast<offset_type>(sizeof(partition_uuid_));
 
     memcpy(&last_persisted_sequence_number_,
            body.data() + offset,
            sizeof(last_persisted_sequence_number_));
-    last_persisted_sequence_number_ = utils::byte_swap(last_persisted_sequence_number_);
+    last_persisted_sequence_number_ = utils::network_to_host(last_persisted_sequence_number_);
     offset += static_cast<offset_type>(sizeof(last_persisted_sequence_number_));
 
     memcpy(&current_sequence_number_, body.data() + offset, sizeof(current_sequence_number_));
-    current_sequence_number_ = utils::byte_swap(current_sequence_number_);
+    current_sequence_number_ = utils::network_to_host(current_sequence_number_);
     offset += static_cast<offset_type>(sizeof(current_sequence_number_));
 
     if (failover) {
       std::uint64_t field{};
 
       memcpy(&field, body.data() + offset, sizeof(field));
-      old_partition_uuid_.emplace(utils::byte_swap(field));
+      old_partition_uuid_.emplace(utils::network_to_host(field));
       offset += static_cast<offset_type>(sizeof(field));
 
       memcpy(&field, body.data() + offset, sizeof(field));
-      last_received_sequence_number_.emplace(utils::byte_swap(field));
+      last_received_sequence_number_.emplace(utils::network_to_host(field));
     }
   }
   return false;
@@ -89,7 +89,7 @@ observe_seqno_request_body::fill_body()
 
   value_.resize(sizeof(std::uint64_t));
 
-  std::uint64_t field = utils::byte_swap(partition_uuid_);
+  std::uint64_t field = utils::host_to_network(partition_uuid_);
   memcpy(value_.data() + offset, &field, sizeof(field));
 }
 } // namespace couchbase::core::protocol

data/ext/couchbase/core/protocol/cmd_prepend.cxx

@@ -41,12 +41,12 @@ prepend_response_body::parse(key_value_status_code status,
     if (extras_size == 16) {
       std::uint64_t partition_uuid{};
       memcpy(&partition_uuid, body.data() + offset, sizeof(partition_uuid));
-      partition_uuid = utils::byte_swap(partition_uuid);
+      partition_uuid = utils::network_to_host(partition_uuid);
       offset += 8;
 
       std::uint64_t sequence_number{};
       memcpy(&sequence_number, body.data() + offset, sizeof(sequence_number));
-      sequence_number = utils::byte_swap(sequence_number);
+      sequence_number = utils::network_to_host(sequence_number);
 
       token_ = couchbase::utils::build_mutation_token(partition_uuid, sequence_number);
       return true;

data/ext/couchbase/core/protocol/cmd_remove.cxx

@@ -42,12 +42,12 @@ remove_response_body::parse(key_value_status_code status,
     if (extras_size == 16) {
       std::uint64_t partition_uuid{};
       memcpy(&partition_uuid, body.data() + offset, sizeof(partition_uuid));
-      partition_uuid = utils::byte_swap(partition_uuid);
+      partition_uuid = utils::network_to_host(partition_uuid);
       offset += 8;
 
       std::uint64_t sequence_number{};
       memcpy(&sequence_number, body.data() + offset, sizeof(sequence_number));
-      sequence_number = utils::byte_swap(sequence_number);
+      sequence_number = utils::network_to_host(sequence_number);
 
       token_ = couchbase::utils::build_mutation_token(partition_uuid, sequence_number);
       return true;

data/ext/couchbase/core/protocol/cmd_replace.cxx

@@ -42,12 +42,12 @@ replace_response_body::parse(key_value_status_code status,
     if (extras_size == 16) {
       std::uint64_t partition_uuid{};
       memcpy(&partition_uuid, body.data() + offset, sizeof(partition_uuid));
-      partition_uuid = utils::byte_swap(partition_uuid);
+      partition_uuid = utils::network_to_host(partition_uuid);
       offset += 8;
 
       std::uint64_t sequence_number{};
       memcpy(&sequence_number, body.data() + offset, sizeof(sequence_number));
-      sequence_number = utils::byte_swap(sequence_number);
+      sequence_number = utils::network_to_host(sequence_number);
 
       token_ = couchbase::utils::build_mutation_token(partition_uuid, sequence_number);
       return true;
@@ -83,10 +83,10 @@ replace_request_body::fill_extras()
 {
   extras_.resize(sizeof(flags_) + sizeof(expiry_));
 
-  std::uint32_t field = utils::byte_swap(flags_);
+  std::uint32_t field = utils::host_to_network(flags_);
   memcpy(extras_.data(), &field, sizeof(field));
 
-  field = utils::byte_swap(expiry_);
+  field = utils::host_to_network(expiry_);
   memcpy(extras_.data() + sizeof(flags_), &field, sizeof(field));
 }
 } // namespace couchbase::core::protocol

data/ext/couchbase/core/protocol/cmd_touch.cxx

@@ -47,7 +47,7 @@ void
 touch_request_body::expiry(std::uint32_t seconds)
 {
   extras_.resize(sizeof(seconds));
-  seconds = utils::byte_swap(seconds);
+  seconds = utils::host_to_network(seconds);
   memcpy(extras_.data(), &seconds, sizeof(seconds));
 }
 } // namespace couchbase::core::protocol

data/ext/couchbase/core/protocol/cmd_upsert.cxx

@@ -43,12 +43,12 @@ upsert_response_body::parse(key_value_status_code status,
     if (extras_size == 16) {
       std::uint64_t partition_uuid{};
       memcpy(&partition_uuid, body.data() + offset, sizeof(partition_uuid));
-      partition_uuid = utils::byte_swap(partition_uuid);
+      partition_uuid = utils::network_to_host(partition_uuid);
       offset += 8;
 
       std::uint64_t sequence_number{};
       memcpy(&sequence_number, body.data() + offset, sizeof(sequence_number));
-      sequence_number = utils::byte_swap(sequence_number);
+      sequence_number = utils::network_to_host(sequence_number);
 
       token_ = couchbase::utils::build_mutation_token(partition_uuid, sequence_number);
       return true;
@@ -83,10 +83,10 @@ upsert_request_body::fill_extras()
 {
   extras_.resize(sizeof(flags_) + sizeof(expiry_));
 
-  std::uint32_t field = utils::byte_swap(flags_);
+  std::uint32_t field = utils::host_to_network(flags_);
   memcpy(extras_.data(), &field, sizeof(field));
 
-  field = utils::byte_swap(expiry_);
+  field = utils::host_to_network(expiry_);
   memcpy(extras_.data() + sizeof(flags_), &field, sizeof(field));
 }
 } // namespace couchbase::core::protocol

data/ext/couchbase/core/protocol/datatype.hxx

@@ -17,6 +17,7 @@
 
 #pragma once
 
+#include <cstddef>
 #include <cstdint>
 
 namespace couchbase::core::protocol
@@ -28,6 +29,122 @@ enum class datatype : std::uint8_t {
   xattr = 0x04,
 };
 
+/*
+ * Free-standing bitwise operators for the datatype flag set.
+ *
+ * Combining two datatypes stays inside the enum domain and yields a datatype.
+ * Combining a datatype with a raw protocol byte yields std::byte (in either
+ * operand order), because the result may carry bits outside the named values
+ * and therefore should not pretend to be a well-formed datatype.
+ */
+
+constexpr auto
+operator|(datatype lhs, datatype rhs) noexcept -> datatype
+{
+  return static_cast<datatype>(static_cast<std::uint8_t>(lhs) | static_cast<std::uint8_t>(rhs));
+}
+
+constexpr auto
+operator&(datatype lhs, datatype rhs) noexcept -> datatype
+{
+  return static_cast<datatype>(static_cast<std::uint8_t>(lhs) & static_cast<std::uint8_t>(rhs));
+}
+
+constexpr auto
+operator^(datatype lhs, datatype rhs) noexcept -> datatype
+{
+  return static_cast<datatype>(static_cast<std::uint8_t>(lhs) ^ static_cast<std::uint8_t>(rhs));
+}
+
+constexpr auto
+operator|(datatype lhs, std::byte rhs) noexcept -> std::byte
+{
+  return static_cast<std::byte>(lhs) | rhs;
+}
+
+constexpr auto
+operator|(std::byte lhs, datatype rhs) noexcept -> std::byte
+{
+  return lhs | static_cast<std::byte>(rhs);
+}
+
+constexpr auto
+operator&(datatype lhs, std::byte rhs) noexcept -> std::byte
+{
+  return static_cast<std::byte>(lhs) & rhs;
+}
+
+constexpr auto
+operator&(std::byte lhs, datatype rhs) noexcept -> std::byte
+{
+  return lhs & static_cast<std::byte>(rhs);
+}
+
+constexpr auto
+operator^(datatype lhs, std::byte rhs) noexcept -> std::byte
+{
+  return static_cast<std::byte>(lhs) ^ rhs;
+}
+
+constexpr auto
+operator^(std::byte lhs, datatype rhs) noexcept -> std::byte
+{
+  return lhs ^ static_cast<std::byte>(rhs);
+}
+
+/*
+ * Type-safe flag presence test. Returns true when every bit of flag is set in
+ * value; using the composite flag itself as the right-hand side keeps the check
+ * correct even when flag carries more than one bit.
+ */
+
+constexpr auto
+has_flag(datatype value, datatype flag) noexcept -> bool
+{
+  const auto masked = value & flag;
+  return masked == flag;
+}
+
+constexpr auto
+has_flag(std::byte value, datatype flag) noexcept -> bool
+{
+  const auto masked = value & flag;
+  return masked == static_cast<std::byte>(flag);
+}
+
+/*
+ * In-place mutators that set or clear flag bits. The flag is always a named
+ * datatype, while the value being modified may live in the typed enum domain or
+ * as a raw protocol byte.
+ */
+
+constexpr void
+set_flag(datatype& value, datatype flag) noexcept
+{
+  value = value | flag;
+}
+
+constexpr void
+set_flag(std::byte& value, datatype flag) noexcept
+{
+  value = value | flag;
+}
+
+constexpr void
+clear_flag(datatype& value, datatype flag) noexcept
+{
+  // Complement the flag in the integer domain: the bitwise negation of a single
+  // flag is not itself a valid datatype, so it must never be cast back to the enum.
+  value =
+    static_cast<datatype>(static_cast<std::uint8_t>(value) & ~static_cast<std::uint8_t>(flag));
+}
+
+constexpr void
+clear_flag(std::byte& value, datatype flag) noexcept
+{
+  value &= ~static_cast<std::byte>(flag);
+}
+
 constexpr auto
 is_valid_datatype(std::uint8_t code) -> bool
 {
@@ -44,6 +161,6 @@ is_valid_datatype(std::uint8_t code) -> bool
 constexpr auto
 has_json_datatype(std::uint8_t code) -> bool
 {
-  return (code & static_cast<std::uint8_t>(datatype::json)) != 0;
+  return has_flag(static_cast<std::byte>(code), datatype::json);
 }
 } // namespace couchbase::core::protocol

data/ext/couchbase/core/protocol/frame_info_utils.cxx

@@ -39,7 +39,7 @@ add_durability_frame_info(std::vector<std::byte>& framing_extras,
     framing_extras.resize(extras_old_size + 1 + static_cast<std::size_t>(frame_size));
     framing_extras[extras_old_size + 0] = (frame_id << 4U) | frame_size;
     framing_extras[extras_old_size + 1] = static_cast<std::byte>(level);
-    std::uint16_t val = utils::byte_swap(*timeout);
+    std::uint16_t val = utils::host_to_network(*timeout);
     memcpy(framing_extras.data() + extras_old_size + 2, &val, sizeof(val));
   } else {
     const std::byte frame_size{ 1 /* 1 for level */ };

data/ext/couchbase/core/protocol/magic.hxx

@@ -22,6 +22,8 @@
 namespace couchbase::core::protocol
 {
 enum class magic : std::uint8_t {
+  /// Sentinel value for default-constructed/invalid packets (not a real wire value)
+  invalid = 0x00,
   /// Request packet from client to server
   client_request = 0x80,
   /// The alternative request packet containing frame extras
@@ -47,6 +49,8 @@ is_valid_magic(std::uint8_t code) -> bool
     case magic::server_request:
     case magic::server_response:
       return true;
+    case magic::invalid:
+      break;
   }
   return false;
 }

data/ext/couchbase/core/protocol/magic_fmt.hxx

@@ -52,6 +52,9 @@ struct fmt::formatter<couchbase::core::protocol::magic> {
       case couchbase::core::protocol::magic::server_response:
         name = "server_response (0x83)";
         break;
+      case couchbase::core::protocol::magic::invalid:
+        name = "invalid (0x00)";
+        break;
     }
     return format_to(ctx.out(), "{}", name);
   }

data/ext/couchbase/core/protocol/server_request.hxx

@@ -104,12 +104,14 @@ public:
 
     std::uint32_t field = 0;
     memcpy(&field, header_.data() + 8, sizeof(field));
-    body_size_ = utils::byte_swap(field);
+    body_size_ = utils::network_to_host(field);
     data_.resize(body_size_);
 
     memcpy(&opaque_, header_.data() + 12, sizeof(opaque_));
+    opaque_ = utils::network_to_host(opaque_);
 
     memcpy(&cas_, header_.data() + 16, sizeof(cas_));
+    cas_ = utils::network_to_host(cas_);
   }
 
   void parse_body()

data/ext/couchbase/core/protocol/status.cxx

@@ -65,6 +65,7 @@ map_status_code(protocol::client_opcode opcode, std::uint16_t status) -> std::er
     case key_value_status_code::invalid:
     case key_value_status_code::xattr_invalid:
     case key_value_status_code::subdoc_invalid_combo:
+    case key_value_status_code::subdoc_invalid_xattr_order:
     case key_value_status_code::subdoc_deleted_document_cannot_have_value:
       return errc::common::invalid_argument;
 
@@ -181,7 +182,6 @@ map_status_code(protocol::client_opcode opcode, std::uint16_t status) -> std::er
     case key_value_status_code::scope_size_limit_exceeded:
       return errc::common::quota_limited;
 
-    case key_value_status_code::subdoc_invalid_xattr_order:
     case key_value_status_code::not_my_vbucket:
     case key_value_status_code::auth_continue:
     case key_value_status_code::range_error:

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

@@ -0,0 +1,171 @@
+/* -*- 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 analytics request/response to and from the couchbase.analytics.v1 protobuf
+// messages, mirroring query_converter. Rows arrive across streamed AnalyticsQueryResponse messages
+// and are buffered into analytics_response::rows when no callback is provided, or delivered
+// incrementally to row_callback when present; the terminal message carries the metadata.
+//
+// Features with no couchbase2 equivalent are reported by can_encode() so the component can surface
+// feature_not_available rather than silently dropping them: the `raw` passthrough map and scoped
+// analytics.
+//
+// Scoped analytics is refused because the schema cannot express it, not merely because it is
+// unimplemented. AnalyticsQueryRequest at the pinned protostellar revision retired the field the
+// older schema used for this: field 8 is `reserved // bucket_name`, and field 9 was renamed from
+// `scope_name` to `analytics_scope_name` -- one analytics-scope identifier rather than the
+// bucket/scope pair the core request carries in bucket_name/scope_name/scope_qualifier. Collapsing
+// a two-part qualification into that single name would be a guess about which the gateway means, so
+// the request is refused instead. (Vendored copies in couchbase-jvm-clients and
+// couchbase-net-client still carry the older bucket_name=8/scope_name=9 shape, so a mapping cribbed
+// from them would target a schema this client does not speak.)
+
+#include "core/operations/document_analytics.hxx"
+#include "core/protostellar/json_payload.hxx"
+
+#include <couchbase/analytics_scan_consistency.hxx>
+
+#include <couchbase/analytics/v1/analytics.pb.h>
+
+#include <chrono>
+#include <cstddef>
+#include <string>
+#include <utility>
+#include <vector>
+
+namespace couchbase::core::protostellar::analytics
+{
+namespace v1 = ::couchbase::analytics::v1;
+
+[[nodiscard]] inline auto
+can_encode(const operations::analytics_request& request) -> bool
+{
+  return request.raw.empty() && !request.bucket_name.has_value() &&
+         !request.scope_name.has_value() && !request.scope_qualifier.has_value();
+}
+
+inline auto
+encode(const operations::analytics_request& request) -> v1::AnalyticsQueryRequest
+{
+  v1::AnalyticsQueryRequest proto;
+  proto.set_statement(request.statement);
+  proto.set_read_only(request.readonly);
+  proto.set_priority(request.priority);
+  if (request.client_context_id.has_value()) {
+    proto.set_client_context_id(*request.client_context_id);
+  }
+  if (request.scan_consistency.has_value()) {
+    switch (*request.scan_consistency) {
+      case analytics_scan_consistency::not_bounded:
+        proto.set_scan_consistency(
+          v1::AnalyticsQueryRequest_ScanConsistency_SCAN_CONSISTENCY_NOT_BOUNDED);
+        break;
+      case analytics_scan_consistency::request_plus:
+        proto.set_scan_consistency(
+          v1::AnalyticsQueryRequest_ScanConsistency_SCAN_CONSISTENCY_REQUEST_PLUS);
+        break;
+    }
+  }
+  for (const auto& parameter : request.positional_parameters) {
+    proto.add_positional_parameters(json_payload(parameter));
+  }
+  for (const auto& [name, value] : request.named_parameters) {
+    (*proto.mutable_named_parameters())[name] = json_payload(value);
+  }
+  return proto;
+}
+
+[[nodiscard]] inline auto
+to_nanoseconds(const google::protobuf::Duration& duration) -> std::chrono::nanoseconds
+{
+  return std::chrono::seconds{ duration.seconds() } + std::chrono::nanoseconds{ duration.nanos() };
+}
+
+// The gateway reports status as a lowercase string; map it onto the core enum.
+[[nodiscard]] inline auto
+status_from_string(const std::string& status) -> operations::analytics_response::analytics_status
+{
+  using s = operations::analytics_response::analytics_status;
+  if (status == "running") {
+    return s::running;
+  }
+  if (status == "success") {
+    return s::success;
+  }
+  if (status == "errors") {
+    return s::errors;
+  }
+  if (status == "completed") {
+    return s::completed;
+  }
+  if (status == "stopped") {
+    return s::stopped;
+  }
+  if (status == "timeout" || status == "timedout") {
+    return s::timedout;
+  }
+  if (status == "closed") {
+    return s::closed;
+  }
+  if (status == "fatal") {
+    return s::fatal;
+  }
+  if (status == "aborted") {
+    return s::aborted;
+  }
+  return s::unknown;
+}
+
+inline void
+decode_meta_data(const v1::AnalyticsQueryResponse_MetaData& proto,
+                 operations::analytics_response::analytics_meta_data& meta)
+{
+  meta.request_id = proto.request_id();
+  meta.client_context_id = proto.client_context_id();
+  meta.status = status_from_string(proto.status());
+  if (!proto.signature().empty()) {
+    meta.signature = proto.signature();
+  }
+  if (proto.has_metrics()) {
+    const auto& m = proto.metrics();
+    meta.metrics.elapsed_time = to_nanoseconds(m.elapsed_time());
+    meta.metrics.execution_time = to_nanoseconds(m.execution_time());
+    meta.metrics.result_count = m.result_count();
+    meta.metrics.result_size = m.result_size();
+    meta.metrics.error_count = m.error_count();
+    meta.metrics.processed_objects = m.processed_objects();
+    meta.metrics.warning_count = m.warning_count();
+  }
+  // Replaced rather than appended, matching query_converter: decode_meta_data runs once per
+  // MetaData message, and appending would accumulate duplicates without bound if a gateway ever
+  // sent more than one.
+  if (proto.warnings_size() > 0) {
+    std::vector<operations::analytics_response::analytics_problem> warnings;
+    warnings.reserve(static_cast<std::size_t>(proto.warnings_size()));
+    for (const auto& w : proto.warnings()) {
+      operations::analytics_response::analytics_problem problem;
+      problem.code = w.code();
+      problem.message = w.message();
+      warnings.push_back(std::move(problem));
+    }
+    meta.warnings = std::move(warnings);
+  }
+}
+
+} // namespace couchbase::core::protostellar::analytics