couchbase 3.8.1 → 3.9.0

data/ext/couchbase/core/io/mcbp_buffer_pool.hxx

@@ -0,0 +1,122 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2024. 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 <array>
+#include <cstddef>
+#include <utility>
+#include <vector>
+
+namespace couchbase::core::io
+{
+/**
+ * A tiny free-list of byte buffers used to recycle mcbp response body buffers.
+ *
+ * A KV response's body is allocated when the frame is parsed and freed a moment later when the
+ * decoded response is destroyed. Recycling those buffers keeps their capacity warm, so a subsequent
+ * response of similar size reuses the storage instead of allocating (and, once the value crosses
+ * the allocator's mmap threshold, mmap/munmap-ing) a fresh block every operation.
+ *
+ * NOT thread-safe by design, and it performs no synchronization. It is intended to be used as a
+ * thread-local pool (see tls_response_body_pool()): acquire and release always happen on the
+ * calling thread's own pool, so a buffer acquired on one IO thread but released on another (for
+ * example when a replica response is handed to a command strand running on a different IO thread)
+ * is simply not recycled back to the acquiring thread — which is safe, because each thread only
+ * ever touches its own pool. Recycling is therefore best-effort.
+ *
+ * Two bounds keep memory in check: at most `max_buffers` buffers are retained, and buffers larger
+ * than `max_buffer_bytes` are never pooled (they are freed normally), so a single very large value
+ * cannot pin megabytes per thread.
+ *
+ * The free list is a fixed-size array of (initially empty) buffers, so constructing the pool
+ * allocates nothing. That matters because the pool is a lazily-initialized thread_local (see
+ * tls_response_body_pool()): the first use on a given thread may be a release() from a response
+ * destructor, and that first use triggers the thread_local's construction. Backing the free list
+ * with a std::vector would make that construction allocate (and, on failure, throw) inside the
+ * noexcept destructor path, where a throw calls std::terminate. A fixed array cannot.
+ */
+class mcbp_buffer_pool
+{
+public:
+  using buffer = std::vector<std::byte>;
+
+  static constexpr std::size_t max_buffers = 16;
+  static constexpr std::size_t default_max_buffer_bytes = std::size_t{ 1024 } * 1024;
+
+  explicit mcbp_buffer_pool(std::size_t retained_buffers = max_buffers,
+                            std::size_t max_buffer_bytes = default_max_buffer_bytes)
+    : retained_buffers_{ retained_buffers < max_buffers ? retained_buffers : max_buffers }
+    , max_buffer_bytes_{ max_buffer_bytes }
+  {
+    // No allocation here by design (see the class comment): the free list is a fixed-size array of
+    // empty buffers, so neither this constructor nor the lazy thread_local init it drives can
+    // throw.
+  }
+
+  /**
+   * Hand out a recycled buffer (cleared, capacity retained) or an empty one if the pool is empty.
+   */
+  auto acquire() -> buffer
+  {
+    if (count_ == 0) {
+      return {};
+    }
+    // Move the buffer out, leaving an empty slot (the moved-from vector holds no storage).
+    return std::move(free_[--count_]);
+  }
+
+  /**
+   * Return a buffer for reuse. Empty buffers (nothing to recycle) and buffers above the size cap
+   * are dropped, as is any buffer beyond the retained-count bound.
+   */
+  void release(buffer&& buf) noexcept
+  {
+    if (buf.capacity() == 0 || buf.capacity() > max_buffer_bytes_ || count_ >= retained_buffers_) {
+      return;
+    }
+    buf.clear();
+    // Slots at index >= count_ are always empty, so this move-assignment frees nothing and
+    // allocates nothing; release() therefore never touches the allocator, as its noexcept contract
+    // requires.
+    free_[count_++] = std::move(buf);
+  }
+
+  [[nodiscard]] auto size() const -> std::size_t
+  {
+    return count_;
+  }
+
+private:
+  std::array<buffer, max_buffers> free_{};
+  std::size_t count_{ 0 };
+  std::size_t retained_buffers_;
+  std::size_t max_buffer_bytes_;
+};
+
+/**
+ * The calling thread's response-body buffer pool. Shared by every mcbp connection served on that IO
+ * thread; because it is thread-local, acquire and release are always confined to a single thread
+ * and need no locking (see mcbp_buffer_pool).
+ */
+inline auto
+tls_response_body_pool() -> mcbp_buffer_pool&
+{
+  static thread_local mcbp_buffer_pool pool;
+  return pool;
+}
+} // namespace couchbase::core::io

data/ext/couchbase/core/io/mcbp_command.hxx

@@ -18,11 +18,11 @@
 #pragma once
 
 #include "core/app_telemetry_meter.hxx"
-#include "core/document_id_fmt.hxx"
+#include "core/document_id_redaction.hxx"
 #include "core/error_context/key_value_error_map_info.hxx"
+#include "core/logger/redaction.hxx"
 #include "core/metrics/meter_wrapper.hxx"
 #include "core/operations/operation_traits.hxx"
-#include "core/platform/uuid.h"
 #include "core/protocol/client_request.hxx"
 #include "core/protocol/client_response.hxx"
 #include "core/protocol/cmd_get_collection_id.hxx"
@@ -30,17 +30,23 @@
 #include "core/utils/movable_function.hxx"
 #include "couchbase/metrics/meter.hxx"
 #include "couchbase/tracing/request_tracer.hxx"
+#include "mcbp_command_id.hxx"
 #include "mcbp_session.hxx"
 #include "mcbp_traits.hxx"
 #include "retry_orchestrator.hxx"
 
+#include <couchbase/build_config.hxx>
 #include <couchbase/durability_level.hxx>
 #include <couchbase/error_codes.hxx>
 
+#include <asio/dispatch.hpp>
+#include <asio/io_context.hpp>
 #include <asio/steady_timer.hpp>
+#include <asio/strand.hpp>
 #include <spdlog/fmt/bundled/chrono.h>
 
 #include <functional>
+#include <type_traits>
 #include <utility>
 
 namespace couchbase::core::operations
@@ -51,12 +57,22 @@ using mcbp_command_handler =
 
 template<typename Manager, typename Request>
 struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager, Request>> {
-  static constexpr std::chrono::milliseconds durability_timeout_floor{ 1'500 };
-
   using encoded_request_type = typename Request::encoded_request_type;
   using encoded_response_type = typename Request::encoded_response_type;
   asio::steady_timer deadline;
   asio::steady_timer retry_backoff;
+  // Only cancellable operations (replica fan-out) need a strand: their dispatch
+  // path can run on the caller thread while a sibling's completion cancels them
+  // from an IO thread, so all access to session_/opaque_/handler_ is confined to
+  // it. Non-cancellable operations get an empty placeholder instead, so they pay
+  // neither the strand_impl allocation nor any access on the hot path; the strand
+  // is referenced only inside `if constexpr (is_cancellable_operation_v<...>)`.
+  struct unused_strand {
+  };
+  using command_strand = std::conditional_t<is_cancellable_operation_v<Request>,
+                                            asio::strand<asio::io_context::executor_type>,
+                                            unused_strand>;
+  command_strand strand_;
   Request request;
   encoded_request_type encoded;
   std::optional<std::uint32_t> opaque_{};
@@ -64,9 +80,8 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
   mcbp_command_handler handler_{};
   std::shared_ptr<Manager> manager_{};
   std::chrono::milliseconds timeout_{};
-  std::string id_{ fmt::format("{:02x}/{}",
-                               static_cast<std::uint8_t>(encoded_request_type::body_type::opcode),
-                               uuid::to_string(uuid::random())) };
+  // Built lazily by id(); empty until first requested. See id().
+  mutable std::string id_{};
 #ifdef COUCHBASE_CXX_CLIENT_CREATE_OPERATION_SPAN_IN_CORE
   std::shared_ptr<couchbase::tracing::request_span> span_{ nullptr };
 #endif
@@ -76,29 +91,48 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
   std::chrono::time_point<std::chrono::steady_clock> started_at_{};
   std::vector<std::chrono::microseconds> server_durations_{};
 
+  static auto make_command_strand(asio::io_context& ctx) -> command_strand
+  {
+    if constexpr (is_cancellable_operation_v<Request>) {
+      return command_strand{ ctx.get_executor() };
+    } else {
+      return command_strand{};
+    }
+  }
+
   mcbp_command(asio::io_context& ctx,
                std::shared_ptr<Manager> manager,
                Request req,
                std::chrono::milliseconds default_timeout)
     : deadline(ctx)
     , retry_backoff(ctx)
+    , strand_(make_command_strand(ctx))
     , request(req)
     , manager_(manager)
     , timeout_(request.timeout.value_or(default_timeout))
     , parent_span_(request.parent_span)
   {
-    if constexpr (io::mcbp_traits::supports_durability_v<Request>) {
-      if (request.durability_level != durability_level::none &&
-          timeout_ < durability_timeout_floor) {
-        CB_LOG_DEBUG(
-          R"(Timeout is too low for operation with durability, increasing to sensible value. timeout={}ms, floor={}ms, id="{}")",
-          request.id,
-          timeout_.count(),
-          durability_timeout_floor.count(),
-          id_);
-        timeout_ = durability_timeout_floor;
-      }
+  }
+
+  // The diagnostic identifier ("<opcode>/<uuid>") is used only in log lines,
+  // retry traces, and the returned key_value error context — never on the wire.
+  // Build it lazily on first use and cache it, so it is materialized at most once
+  // per command instead of eagerly in every constructor, and repeated readers -- a
+  // retry log line and then the completion's error context -- share the one cached
+  // value. The completion path builds the error context, so a completed operation
+  // still materializes it once; the laziness only avoids the cost for commands that
+  // never reach a point that needs it. The cache is logically const (it does not
+  // change the command's observable value), hence the mutable member and const
+  // accessor. Access while the command is in flight
+  // is serialized -- non-cancellable operations run on their session's single io
+  // thread, and cancellable (replica) operations confine access to the command
+  // strand (see strand_) -- so the one-time memoizing write needs no synchronization.
+  [[nodiscard]] auto id() const -> const std::string&
+  {
+    if (id_.empty()) {
+      id_ = make_command_id(encoded_request_type::body_type::opcode);
     }
+    return id_;
   }
 
   void start(mcbp_command_handler&& handler)
@@ -133,6 +167,16 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
 
   void cancel(retry_reason reason, bool is_timeout = true)
   {
+    if constexpr (is_cancellable_operation_v<Request>) {
+      // Confine cancellation to the command strand so it cannot race the
+      // dispatch path (map_and_send/send_to/send) of a replica sibling that is
+      // still being set up on another thread.
+      if (!strand_.running_in_this_thread()) {
+        return asio::dispatch(strand_, [self = this->shared_from_this(), reason, is_timeout]() {
+          self->cancel(reason, is_timeout);
+        });
+      }
+    }
     if (opaque_ && session_) {
       if (session_->cancel(opaque_.value(), asio::error::operation_aborted, reason)) {
         handler_ = nullptr;
@@ -149,6 +193,36 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
     }
   }
 
+  // Re-dispatch a session completion handler onto the command strand for
+  // cancellable operations, so the response/timeout path (which mcbp_session
+  // invokes on its own IO thread) cannot run concurrently with a strand-confined
+  // cancel(). A no-op passthrough for non-cancellable operations.
+  template<typename Handler>
+  auto on_strand(Handler&& handler)
+  {
+    if constexpr (is_cancellable_operation_v<Request>) {
+      return [self = this->shared_from_this(), handler = std::forward<Handler>(handler)](
+               std::error_code ec,
+               retry_reason reason,
+               io::mcbp_message&& msg,
+               std::optional<key_value_error_map_info> error_info) mutable {
+        if (self->strand_.running_in_this_thread()) {
+          return handler(ec, reason, std::move(msg), std::move(error_info));
+        }
+        asio::dispatch(self->strand_,
+                       [handler = std::move(handler),
+                        ec,
+                        reason,
+                        msg = std::move(msg),
+                        error_info = std::move(error_info)]() mutable {
+                         handler(ec, reason, std::move(msg), std::move(error_info));
+                       });
+      };
+    } else {
+      return std::forward<Handler>(handler);
+    }
+  }
+
   void invoke_handler(std::error_code ec, std::optional<io::mcbp_message>&& msg = {})
   {
     retry_backoff.cancel();
@@ -162,18 +236,19 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
     }
 #endif
     if (handler) {
-      const auto& node_uuid = session_ ? session_->node_uuid() : "";
       auto telemetry_recorder =
-        manager_->app_telemetry_meter()->value_recorder(node_uuid, manager_->name());
+        session_
+          ? session_->app_telemetry_recorder(*manager_->app_telemetry_meter(), manager_->name())
+          : manager_->app_telemetry_meter()->value_recorder("", manager_->name());
       telemetry_recorder->update_counter(app_telemetry_counter::kv_r_total);
       if (ec == errc::common::unambiguous_timeout || ec == errc::common::ambiguous_timeout) {
         telemetry_recorder->update_counter(app_telemetry_counter::kv_r_timedout);
         auto time_left = deadline.expiry() - std::chrono::steady_clock::now();
         CB_LOG_TRACE(R"([{}] timeout operation id="{}", {}, key="{}", partition={}, time_left={})",
                      session_ ? session_->log_prefix() : manager_->log_prefix(),
-                     id_,
+                     id(),
                      encoded_request_type::body_type::opcode,
-                     request.id,
+                     logger::document(request.id),
                      request.partition,
                      time_left);
       } else if (ec == errc::common::request_canceled) {
@@ -185,6 +260,15 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
 
   void request_collection_id()
   {
+    if constexpr (is_cancellable_operation_v<Request>) {
+      // Reached from the unknown-collection retry timer on an arbitrary IO
+      // thread; hop onto the strand before touching session_/opaque_.
+      if (!strand_.running_in_this_thread()) {
+        return asio::dispatch(strand_, [self = this->shared_from_this()]() {
+          self->request_collection_id();
+        });
+      }
+    }
     if (session_->is_stopped()) {
       return manager_->map_and_send(this->shared_from_this());
     }
@@ -194,11 +278,11 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
     session_->write_and_subscribe(
       req.opaque(),
       req.data(session_->supports_feature(protocol::hello_feature::snappy)),
-      [self = this->shared_from_this()](
-        std::error_code ec,
-        retry_reason /* reason */,
-        io::mcbp_message&& msg,
-        std::optional<key_value_error_map_info> /* error_info */) mutable {
+      on_strand([self = this->shared_from_this()](
+                  std::error_code ec,
+                  retry_reason /* reason */,
+                  io::mcbp_message&& msg,
+                  std::optional<key_value_error_map_info> /* error_info */) mutable {
         if (ec == asio::error::operation_aborted) {
           return self->invoke_handler(errc::common::ambiguous_timeout);
         }
@@ -216,7 +300,7 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
                                               resp.body().collection_uid());
         self->request.id.collection_uid(resp.body().collection_uid());
         return self->send();
-      });
+      }));
   }
 
   void handle_unknown_collection()
@@ -225,9 +309,9 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
     auto time_left = deadline.expiry() - std::chrono::steady_clock::now();
     CB_LOG_DEBUG(R"({} unknown collection response for "{}", time_left={}ms, id="{}")",
                  session_->log_prefix(),
-                 request.id,
+                 logger::document(request.id),
                  std::chrono::duration_cast<std::chrono::milliseconds>(time_left).count(),
-                 id_);
+                 id());
     request.retries.add_reason(retry_reason::key_value_collection_outdated);
     if (time_left < backoff) {
       return invoke_handler(make_error_code(request.retries.idempotent()
@@ -256,9 +340,9 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
           CB_LOG_DEBUG(
             R"({} no cache entry for collection, resolve collection id for "{}", timeout={}ms, id="{}")",
             session_->log_prefix(),
-            request.id,
+            logger::document(request.id),
             timeout_.count(),
-            id_);
+            id());
           return request_collection_id();
         }
       } else {
@@ -283,13 +367,13 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
     session_->write_and_subscribe(
       request.opaque,
       encoded.data(session_->supports_feature(protocol::hello_feature::snappy)),
-      [self = this->shared_from_this(),
-       start = std::chrono::steady_clock::now(),
-       dispatch_span = std::move(dispatch_span)](
-        std::error_code ec,
-        retry_reason reason,
-        io::mcbp_message&& msg,
-        std::optional<key_value_error_map_info> /* error_info */) mutable {
+      on_strand([self = this->shared_from_this(),
+                 start = std::chrono::steady_clock::now(),
+                 dispatch_span = std::move(dispatch_span)](
+                  std::error_code ec,
+                  retry_reason reason,
+                  io::mcbp_message&& msg,
+                  std::optional<key_value_error_map_info> /* error_info */) mutable {
         {
           const auto server_duration_us =
             static_cast<std::uint64_t>(protocol::parse_server_duration_us(msg));
@@ -320,17 +404,17 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
               break;
           }
 
-          auto telemetry_recorder = self->manager_->app_telemetry_meter()->value_recorder(
-            self->session_->node_uuid(), self->manager_->name());
+          auto telemetry_recorder = self->session_->app_telemetry_recorder(
+            *self->manager_->app_telemetry_meter(), self->manager_->name());
           telemetry_recorder->record_latency(category, latency);
         }
 
 #ifdef COUCHBASE_CXX_CLIENT_CREATE_OPERATION_SPAN_IN_CORE
         {
           metrics::metric_attributes attrs{
-            service_type::key_value,
+            tracing::service::key_value,
             self->request.observability_identifier,
-            ec,
+            metrics::standardized_error_type(ec),
             self->request.id.bucket(),
             self->request.id.scope(),
             self->request.id.collection(),
@@ -411,7 +495,7 @@ struct mcbp_command : public std::enable_shared_from_this<mcbp_command<Manager,
         } else {
           io::retry_orchestrator::maybe_retry(self->manager_, self, reason, ec);
         }
-      });
+      }));
   }
 
   void send_to(io::mcbp_session session)
@@ -464,9 +548,17 @@ private:
 #endif
     if (dispatch_span->uses_tags()) {
       dispatch_span->add_tag(tracing::attributes::dispatch::network_transport, "tcp");
-      dispatch_span->add_tag(tracing::attributes::dispatch::operation_id,
-                             fmt::format("0x{:x}", request.opaque));
-      dispatch_span->add_tag(tracing::attributes::dispatch::local_id, session_->id());
+      // Prefer the typed capability so the opaque is not formatted to a string on the hot path;
+      // spans that do not support it (external tracers) fall back to the string tag.
+      if (!dispatch_span->try_set_dispatch_operation_id(request.opaque)) {
+        dispatch_span->add_tag(tracing::attributes::dispatch::operation_id,
+                               fmt::format("0x{:x}", request.opaque));
+      }
+      // Prefer the typed capability so the local id is not string-tagged on the hot path; external
+      // tracers fall back to the string tag.
+      if (!dispatch_span->try_set_dispatch_local_id(session_->id())) {
+        dispatch_span->add_tag(tracing::attributes::dispatch::local_id, session_->id());
+      }
     }
     return dispatch_span;
   }
@@ -475,14 +567,21 @@ private:
                            const std::uint64_t server_duration_us) const
   {
     if (dispatch_span->uses_tags()) {
-      dispatch_span->add_tag(tracing::attributes::dispatch::server_duration, server_duration_us);
+      // Prefer the typed capability so the server duration and peer socket are not string-tagged on
+      // the hot path; external tracers fall back to the string tags.
+      if (!dispatch_span->try_set_dispatch_result(
+            server_duration_us, session_->remote_hostname(), session_->remote_port())) {
+        dispatch_span->add_tag(tracing::attributes::dispatch::server_duration, server_duration_us);
+        dispatch_span->add_tag(tracing::attributes::dispatch::peer_address,
+                               session_->remote_hostname());
+        dispatch_span->add_tag(tracing::attributes::dispatch::peer_port, session_->remote_port());
+      }
+      // The built-in span does not keep the server (canonical) address; only external tracers
+      // consume these, and their SSO-sized tag names do not allocate.
       dispatch_span->add_tag(tracing::attributes::dispatch::server_address,
                              session_->canonical_hostname());
       dispatch_span->add_tag(tracing::attributes::dispatch::server_port,
                              session_->canonical_port_number());
-      dispatch_span->add_tag(tracing::attributes::dispatch::peer_address,
-                             session_->remote_hostname());
-      dispatch_span->add_tag(tracing::attributes::dispatch::peer_port, session_->remote_port());
     }
     dispatch_span->end();
   }

data/ext/couchbase/core/io/mcbp_command_id.hxx

@@ -0,0 +1,45 @@
+/* -*- 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/platform/uuid.h"
+#include "core/protocol/client_opcode.hxx"
+
+#include <spdlog/fmt/bundled/core.h>
+
+#include <cstdint>
+#include <string>
+
+namespace couchbase::core::operations
+{
+/**
+ * Build the diagnostic identifier for an mcbp command: the opcode rendered as
+ * two lowercase hex digits, a slash, and a random v4 UUID
+ * (e.g. "01/3f2a1c9e-...-...", 39 chars).
+ *
+ * This identifier never travels on the wire; it appears only in log lines,
+ * retry traces, and the returned key_value error context. mcbp_command
+ * therefore builds it lazily on first use rather than for every operation.
+ */
+inline auto
+make_command_id(protocol::client_opcode opcode) -> std::string
+{
+  return fmt::format(
+    "{:02x}/{}", static_cast<std::uint8_t>(opcode), uuid::to_string(uuid::random()));
+}
+} // namespace couchbase::core::operations

data/ext/couchbase/core/io/mcbp_message.cxx

@@ -26,7 +26,15 @@ namespace couchbase::core::io
 auto
 binary_header::status() const -> std::uint16_t
 {
-  return utils::byte_swap(specific);
+  return utils::network_to_host(specific);
+}
+
+auto
+binary_header::alt_sizes() const -> binary_header::alt_frame_sizes
+{
+  std::array<std::byte, sizeof(keylen)> bytes{};
+  std::memcpy(bytes.data(), &keylen, sizeof(keylen));
+  return { std::to_integer<std::uint8_t>(bytes[0]), std::to_integer<std::uint8_t>(bytes[1]) };
 }
 
 auto

data/ext/couchbase/core/io/mcbp_message.hxx

@@ -18,6 +18,7 @@
 #pragma once
 
 #include <array>
+#include <cstddef>
 #include <cstdint>
 #include <vector>
 
@@ -42,12 +43,30 @@ struct binary_header {
   std::uint32_t opaque;
   std::uint64_t cas;
 
+  /**
+   * Sizes of the framing extras and key regions of a flexible-framing ("alt") frame.
+   *
+   * Bytes 2 and 3 of an alt frame header are two independent 1-byte fields, not one 16-bit
+   * value. Reinterpreting `keylen` as an integer and shifting the two halves apart puts each
+   * byte into the wrong variable on one host order or the other, so read them out as bytes.
+   */
+  struct alt_frame_sizes {
+    std::uint8_t framing_extras;
+    std::uint8_t key;
+  };
+
   [[nodiscard]] auto status() const -> std::uint16_t;
+  [[nodiscard]] auto alt_sizes() const -> alt_frame_sizes;
 };
 
 struct mcbp_message {
   binary_header header{};
   std::vector<std::byte> body{};
+  // Set on every frame read from the socket, so the buffer that ends up holding `body` can be
+  // recycled to the reading thread's pool when the decoded response is destroyed. False only for a
+  // message that never passed through the read loop (e.g. a default-constructed one), whose `body`
+  // is freed normally.
+  bool recycle_body{ false };
 
   mcbp_message() = default;
   mcbp_message(const mcbp_message& other) = delete;