couchbase 3.8.1 → 3.9.0

data/ext/couchbase/core/row_streamer.cxx

@@ -26,9 +26,14 @@
 #include "utils/json_streaming_lexer.hxx"
 #include "utils/movable_function.hxx"
 
+#include <asio/error.hpp>
 #include <asio/experimental/channel_error.hpp>
 #include <asio/experimental/concurrent_channel.hpp>
 #include <asio/io_context.hpp>
+#include <asio/post.hpp>
+
+#include <asio/steady_timer.hpp>
+#include <chrono>
 
 #include <atomic>
 #include <memory>
@@ -48,50 +53,75 @@ struct row_stream_end_signal {
 class row_streamer_impl : public std::enable_shared_from_this<row_streamer_impl>
 {
 public:
-  static constexpr std::size_t ROW_BUFFER_SIZE{ 100 };
-  static constexpr std::size_t ROW_BUFFER_FEED_THRESHOLD{ ROW_BUFFER_SIZE * 3 / 4 };
-  static constexpr std::uint32_t LEXER_DEPTH{ 4 };
-
   row_streamer_impl(asio::io_context& io,
                     http_response_body body,
-                    const std::string& pointer_expression)
+                    const std::string& pointer_expression,
+                    row_streamer_options options)
     : io_{ io }
     , body_{ std::move(body) }
-    , rows_{ io_, ROW_BUFFER_SIZE }
-    , lexer_{ pointer_expression, LEXER_DEPTH }
+    // rows_ initializes before options_, so read the capacity from the ctor parameter.
+    , rows_{ io_, options.row_buffer_size }
+    , options_{ options }
+    , idle_timer_{ io_ }
+    , lexer_{ pointer_expression, options_.lexer_depth, options_.max_row_bytes }
   {
   }
 
   void start(utils::movable_function<void(std::string, std::error_code)>&& handler)
   {
+    metadata_header_handler_ = std::move(handler);
     lexer_.on_metadata_header_complete(
-      [handler = std::move(handler)](auto ec, auto meta_header) mutable {
+      [weak = weak_from_this()](auto ec, auto meta_header) mutable {
+        auto self = weak.lock();
+        if (!self) {
+          return;
+        }
         // Trim any whitespace from the end
-        meta_header.erase(meta_header.find_last_not_of(" \t\f\v\n\r") + 1);
+        auto last_non_ws = meta_header.find_last_not_of(" \t\f\v\n\r");
+        if (last_non_ws != std::string::npos) {
+          meta_header.erase(last_non_ws + 1);
+        }
 
         // The metadata header can end with an open `[` (opening bracket for pointer expression
         // array). If that's the case, close the array and the response object
-        if (meta_header[meta_header.length() - 1] == '[') {
+        if (!meta_header.empty() && meta_header[meta_header.length() - 1] == '[') {
           meta_header.append("]}");
         }
-        handler(meta_header, ec);
+        self->deliver_metadata_header(ec, std::move(meta_header));
       });
-    lexer_.on_row([self = shared_from_this()](std::string&& row) -> utils::json::stream_control {
-      self->rows_.async_send({}, std::move(row), [self](auto ec) {
-        self->buffered_row_count_++;
+    lexer_.on_row([weak = weak_from_this()](std::string&& row) -> utils::json::stream_control {
+      auto self = weak.lock();
+      if (!self) {
+        return utils::json::stream_control::stop;
+      }
+      auto row_len = row.size();
+      // Account the row against the back-pressure budget *synchronously*, as it is handed to the
+      // channel. A concurrent_channel completes async_send immediately while it has spare capacity
+      // and otherwise queues the send until a receiver drains a slot; if we only counted bytes in
+      // the completion handler, a full channel would leave buffered_bytes_ pinned low and let
+      // maybe_feed_lexer() keep pulling from the socket, piling up unbounded pending sends (each
+      // owning a row). Counting here makes the high-water mark observe the true backlog.
+      self->buffered_bytes_.fetch_add(row_len, std::memory_order_relaxed);
+      self->rows_.async_send({}, std::move(row), [self, row_len](auto ec) {
         if (ec) {
           if (ec != asio::experimental::error::channel_closed &&
               ec != asio::experimental::error::channel_cancelled) {
             CB_LOG_WARNING(
               "unexpected error while sending to row channel: {} ({})", ec.value(), ec.message());
           }
-          return;
+          // The send never reached a receiver (channel closed/cancelled), so release its budget.
+          self->release_buffered_bytes(row_len);
         }
       });
       return utils::json::stream_control::next_row;
     });
-    lexer_.on_complete([self = shared_from_this()](
+    lexer_.on_complete([weak = weak_from_this()](
                          std::error_code ec, std::size_t /*number_of_rows*/, std::string&& meta) {
+      auto self = weak.lock();
+      if (!self) {
+        return;
+      }
+      self->lexer_completed_ = true;
       row_stream_end_signal signal{ ec, std::move(meta) };
       self->rows_.async_send({}, std::move(signal), [self](auto ec) {
         if (ec) {
@@ -115,7 +145,6 @@ public:
     }
     rows_.async_receive(
       [self = shared_from_this(), handler = std::move(handler)](auto ec, auto row) mutable {
-        self->buffered_row_count_--;
         if (ec) {
           if (ec == asio::experimental::error::channel_closed ||
               ec == asio::experimental::error::channel_cancelled) {
@@ -124,66 +153,288 @@ public:
           return handler({}, ec);
         }
         if (std::holds_alternative<row_stream_end_signal>(row)) {
-          auto signal = std::get<row_stream_end_signal>(row);
+          auto& signal = std::get<row_stream_end_signal>(row);
           if (!signal.metadata.empty()) {
-            std::lock_guard<std::mutex> const lock{ self->metadata_mutex_ };
+            const std::scoped_lock<std::mutex> lock{ self->metadata_mutex_ };
             self->metadata_ = std::move(signal.metadata);
           }
           return handler({}, signal.ec);
         }
-        auto row_content = std::get<std::string>(row);
+        auto row_content = std::move(std::get<std::string>(row));
+        const auto row_bytes = row_content.size();
         handler(std::move(row_content), {});
 
-        // After receiving a row check if more data needs to be fed into the lexer
-        self->maybe_feed_lexer();
+        // Release the row's budget and resume feeding at or below the low-water mark.
+        self->release_buffered_bytes(row_bytes);
+        if (self->should_resume()) {
+          self->maybe_feed_lexer();
+        }
         return;
       });
   }
 
+  auto set_deadline(std::chrono::time_point<std::chrono::steady_clock> deadline_tp)
+    -> io::deadline_state
+  {
+    // Held across the check and the arm. Testing the flag and then arming as two steps leaves a
+    // window in which cancel() can run to completion in between, so this thread would install a
+    // deadline on a stream already cancelled and an expiry could report a timeout after it.
+    // cancel() takes the same lock around its own state change and its cancel_deadline(), so the
+    // two orderings are the only ones: arm-then-cancel, which the cancel supersedes, or
+    // cancel-then-arm, which this refuses.
+    const std::scoped_lock<std::mutex> lock{ cancel_mutex_ };
+    if (cancelled_) {
+      return io::deadline_state::body_already_ended;
+    }
+    // Arms on the calling thread: the body serialises arming, cancelling and the terminal
+    // transition under one lock and supersedes an expiry already queued. Not posted, which would
+    // leave the previous deadline installed until the post ran.
+    const auto on_expiry =
+      options_.is_read_only ? io::deadline_terminal::unambiguous : io::deadline_terminal::ambiguous;
+    return body_.set_deadline(deadline_tp, on_expiry);
+  }
+
   void cancel()
   {
-    body_.cancel();
+    {
+      // The state change and the supersession are one step, against set_deadline() holding the
+      // same lock across its check and its arm. Recorded on this thread rather than in the posted
+      // teardown: the flag refuses later arms, and cancel_deadline() supersedes one already armed,
+      // which would otherwise stay live until the post ran and could take the body's terminal --
+      // reporting a timeout for a stream the caller had already cancelled.
+      const std::scoped_lock<std::mutex> lock{ cancel_mutex_ };
+      cancelled_ = true;
+      body_.cancel_deadline();
+    }
+    // An explicit cancel must win over a racing inter-read idle timer, so it is disarmed here
+    // rather than in the posted teardown: a timer completion running before that post would set
+    // timed_out_ and the read abort would be reported as a timeout. The completion holds this lock
+    // across its generation test and its store, so it either sees the bump and returns, or its
+    // store precedes the clear. idle_disarmed_ refuses a timer armed by a read completing before
+    // the teardown.
+    {
+      const std::scoped_lock<std::mutex> lock{ idle_timer_mutex_ };
+      idle_disarmed_ = true;
+      idle_timer_.cancel();
+      idle_generation_.fetch_add(1, std::memory_order_relaxed);
+      timed_out_ = false;
+    }
+    // Tear the body down from the io_context rather than the caller's thread, which may never run
+    // it. The channel is thread-safe, so cancel/close it synchronously to unblock a waiting
+    // consumer immediately. No post once the read-ahead has ended: the body is closed or drained,
+    // and its cancel() does nothing. After cluster close the io_context runs out of work and
+    // stops. A post queued then never runs, and its capture holds this streamer and the body until
+    // the io_context is destroyed.
+    if (!received_all_data_) {
+      asio::post(io_, [self = shared_from_this()]() {
+        self->body_.cancel();
+      });
+    }
     rows_.cancel();
     rows_.close();
   }
 
   auto metadata() -> std::optional<std::string>
   {
-    std::lock_guard<std::mutex> const lock{ metadata_mutex_ };
+    const std::scoped_lock<std::mutex> lock{ metadata_mutex_ };
     return metadata_;
   }
 
+  [[nodiscard]] auto buffered_bytes() const -> std::size_t
+  {
+    return buffered_bytes_.load(std::memory_order_relaxed);
+  }
+
 private:
+  // Resolve start()'s preamble handler exactly once. The lexer delivers it on a well-formed
+  // response (rows-array open or clean root pop); the terminal paths in maybe_feed_lexer call this
+  // with an error so a response that never produces a metadata header (empty body, or a valid but
+  // non-object JSON root) still resolves the handler instead of hanging the caller forever.
+  void deliver_metadata_header(std::error_code ec, std::string&& meta_header)
+  {
+    if (metadata_header_delivered_.exchange(true)) {
+      return;
+    }
+    // Move the handler out before invoking so it is destroyed right after. The handler owns a
+    // strong reference to the owning query/analytics stream (which in turn owns this row_streamer),
+    // so keeping it in a member past delivery would form a reference cycle and leak the whole
+    // stream.
+    auto handler = std::move(metadata_header_handler_);
+    if (handler) {
+      handler(std::move(meta_header), ec);
+    }
+  }
+
+  // At or below the mark, not strictly below it: buffered_bytes_ is unsigned, so a strict
+  // comparison against a zero low-water mark can never hold and the consumer would never ask the
+  // producer to resume. Reading would stop for good at the first pause. An empty buffer resumes
+  // reading whatever the mark is set to.
+  [[nodiscard]] auto should_resume() const -> bool
+  {
+    return buffered_bytes_.load(std::memory_order_relaxed) <= options_.low_water_bytes;
+  }
+
+  // Release a row's byte budget, clamping at zero. Uses an atomic compare-exchange loop so the
+  // subtract is a single read-modify-write: even if the io_context is driven by more than one
+  // thread, a concurrent update to buffered_bytes_ cannot be lost (as it could with a separate
+  // load + store).
+  //
+  // Sequentially consistent, as is the gating load in maybe_feed_lexer(). The handshake needs
+  // visibility from consumer to producer, the opposite direction from the channel handoff, which
+  // therefore supplies nothing here. A consumer that drains below the low-water mark and then
+  // loses the feeding_ compare-exchange leaves the resume to the producer's gate; a gate reading a
+  // pre-drain value declines it too, and the stream stalls with no read outstanding and the
+  // consumer parked in next_row. Relaxed on both ends leaves that store-buffering shape open, and
+  // release/acquire does not forbid it either. Only a total order covering all four accesses --
+  // these two and the feeding_ gate's -- rules the stall out.
+  void release_buffered_bytes(std::size_t n)
+  {
+    auto current = buffered_bytes_.load(std::memory_order_relaxed);
+    while (!buffered_bytes_.compare_exchange_weak(current,
+                                                  current >= n ? current - n : 0,
+                                                  std::memory_order_seq_cst,
+                                                  std::memory_order_relaxed)) {
+    }
+  }
+
+  // Arm the inter-read idle timer, if configured. It is armed only while a socket read is in
+  // flight (see maybe_feed_lexer) so a legitimately slow consumer — which produces no socket
+  // traffic — is never timed out; a fire means the server stalled mid-body.
+  void arm_idle_timer()
+  {
+    if (options_.idle_timeout.count() <= 0) {
+      return;
+    }
+    const std::scoped_lock<std::mutex> lock{ idle_timer_mutex_ };
+    if (idle_disarmed_) {
+      return;
+    }
+    const auto generation = idle_generation_.fetch_add(1, std::memory_order_relaxed) + 1;
+    idle_timer_.expires_after(options_.idle_timeout);
+    idle_timer_.async_wait([weak = weak_from_this(), generation](std::error_code ec) {
+      if (ec == asio::error::operation_aborted) {
+        return;
+      }
+      auto self = weak.lock();
+      if (!self) {
+        return;
+      }
+      // Ignore a completion from a timer that has already been superseded: when a read completes it
+      // cancels and bumps the generation, but a timer that fired at almost the same instant may
+      // already be queued. Acting on such a stale fire would abort the healthy next read and
+      // misreport it as a timeout.
+      {
+        // Under the lock cancel_idle_timer() bumps the generation in: on another thread, cancel()
+        // could otherwise bump and clear timed_out_ between this test and the store, and the
+        // cancelled read would be reported as a timeout.
+        const std::scoped_lock<std::mutex> lock{ self->idle_timer_mutex_ };
+        if (self->idle_generation_.load(std::memory_order_relaxed) != generation) {
+          return;
+        }
+        // Server stalled while a read was in flight: abort it; the read completion delivers the
+        // terminal with a timeout error (steered by timed_out_).
+        self->timed_out_ = true;
+      }
+      self->body_.cancel();
+    });
+  }
+
+  // Cancels the idle timer and supersedes its generation, so a completion already queued is
+  // ignored.
+  void cancel_idle_timer()
+  {
+    const std::scoped_lock<std::mutex> lock{ idle_timer_mutex_ };
+    idle_timer_.cancel();
+    idle_generation_.fetch_add(1, std::memory_order_relaxed);
+  }
+
   void maybe_feed_lexer()
   {
-    if (feeding_ || received_all_data_ || buffered_row_count_ > ROW_BUFFER_FEED_THRESHOLD) {
+    // Sequentially consistent, as is the releasing read-modify-write in release_buffered_bytes().
+    // A consumer that has drained below the low-water mark and lost the gate below leaves the
+    // resume to this load, which has to observe its release.
+    if (received_all_data_ ||
+        buffered_bytes_.load(std::memory_order_seq_cst) > options_.high_water_bytes) {
       return;
     }
 
-    feeding_ = true;
+    // Atomically claim the feeding gate. With a multi-threaded io_context two resume paths (a
+    // next_row completion draining a slot and the feed chain re-entering) can reach here at once;
+    // only one may hold an outstanding body_.next().
+    bool expected = false;
+    if (!feeding_.compare_exchange_strong(expected, true)) {
+      return;
+    }
+    arm_idle_timer();
 
-    body_.next([self = shared_from_this()](const auto& data, auto ec) mutable {
+    body_.next([self = shared_from_this()](const auto& data, bool has_more, auto ec) mutable {
+      // A read completed (or was aborted); the idle timer only guards an in-flight read. Cancel it
+      // and bump the generation so a timer that fired at the same instant is treated as stale.
+      self->cancel_idle_timer();
       if (ec) {
         self->received_all_data_ = true;
-        auto signal = row_stream_end_signal{ ec };
-        return self->rows_.async_send({}, std::move(signal), [self](auto ec) {
-          if (!ec || ec == asio::experimental::error::channel_cancelled ||
-              ec == asio::experimental::error::channel_closed) {
-            return;
-          }
-          CB_LOG_WARNING("unexpected error while sending row stream end signal: {} ({})",
-                         ec.value(),
-                         ec.message());
-        });
-      }
-      if (data.empty()) {
-        self->received_all_data_ = true;
+        // If the idle timer aborted the read, report a timeout rather than the raw cancel error.
+        // Classify it the way the buffered path (http_command) does: a read-only request is
+        // idempotent, so its timeout is unambiguous (definitely not applied); a mutating request
+        // must be ambiguous, because a retry layer that reads unambiguous would consider it safe to
+        // replay and could double-apply the mutation.
+        auto terminal_ec = ec;
+        if (self->timed_out_) {
+          terminal_ec = self->options_.is_read_only
+                          ? std::error_code{ errc::common::unambiguous_timeout }
+                          : std::error_code{ errc::common::ambiguous_timeout };
+        }
+        // A read error before any metadata header (e.g. the connection is reset right after the
+        // response headers) must still resolve start()'s handler rather than hang the caller.
+        self->deliver_metadata_header(terminal_ec, {});
+        // Only enqueue a terminal if the lexer has not already delivered one: on a keep-alive
+        // socket a read can error after the JSON document already completed, which would otherwise
+        // enqueue a second, never-consumed terminal.
+        if (!self->lexer_completed_) {
+          auto signal = row_stream_end_signal{ terminal_ec };
+          return self->rows_.async_send({}, std::move(signal), [self](auto ec) {
+            if (!ec || ec == asio::experimental::error::channel_cancelled ||
+                ec == asio::experimental::error::channel_closed) {
+              return;
+            }
+            CB_LOG_WARNING("unexpected error while sending row stream end signal: {} ({})",
+                           ec.value(),
+                           ec.message());
+          });
+        }
         return;
       }
-      {
-        const std::lock_guard<std::mutex> lock{ self->data_feed_mutex_ };
+      if (!data.empty()) {
+        // The chunk may be empty even mid-stream (a socket read consumed entirely by HTTP chunk
+        // framing); only feed the lexer when there are actual body bytes. End-of-stream is keyed
+        // off has_more, never off emptiness, so a framing-only read never looks like completion.
+        const std::scoped_lock<std::mutex> lock{ self->data_feed_mutex_ };
         self->lexer_.feed(data);
       }
+      if (!has_more) {
+        // Transport reached the end of the body. For a well-formed response the lexer's
+        // on_complete already delivered the terminal row_stream_end_signal; if the body ended
+        // before the JSON document completed (truncated/malformed response), no terminal would
+        // otherwise reach the consumer and it would block forever — surface a parsing failure.
+        self->received_all_data_ = true;
+        if (!self->lexer_completed_) {
+          // The body ended without the lexer completing the document: a truncated/malformed
+          // response, an empty body, or a valid-JSON-but-not-an-object root that the lexer rejects
+          // without ever emitting a metadata header. Resolve start()'s handler and enqueue a
+          // terminal so a consumer parked in start() or next_row() is not stuck forever.
+          self->deliver_metadata_header(errc::common::parsing_failure, {});
+          auto signal = row_stream_end_signal{ errc::common::parsing_failure };
+          self->rows_.async_send({}, std::move(signal), [self](auto ec) {
+            if (ec && ec != asio::experimental::error::channel_cancelled &&
+                ec != asio::experimental::error::channel_closed) {
+              CB_LOG_WARNING("unexpected error while sending row stream end signal: {} ({})",
+                             ec.value(),
+                             ec.message());
+            }
+          });
+        }
+        return;
+      }
 
       self->feeding_ = false;
 
@@ -196,10 +447,31 @@ private:
   asio::experimental::concurrent_channel<void(std::error_code,
                                               std::variant<std::string, row_stream_end_signal>)>
     rows_;
-  std::atomic_size_t buffered_row_count_{ 0 };
+  row_streamer_options options_;
+  asio::steady_timer idle_timer_;
+  // Armed from the read path and cancelled from the read completion and from cancel() on its
+  // caller's thread, which differ once more than one thread runs the io_context or cancel() is
+  // called off it. Also held across the timer completion's generation test and its timed_out_
+  // store.
+  std::mutex idle_timer_mutex_{};
+  // Set by cancel(); guarded by idle_timer_mutex_.
+  bool idle_disarmed_{ false };
+  std::atomic_size_t buffered_bytes_{ 0 };
   std::atomic_bool received_all_data_{ false };
   std::atomic_bool feeding_{ false };
-  std::optional<std::string> metadata_header_;
+  std::atomic_bool lexer_completed_{ false };
+  std::atomic_bool timed_out_{ false };
+  // Guards the pair below against set_deadline(): the check and the arm, and the state change and
+  // the supersession, each have to be one step or an arm can land on a cancelled stream.
+  std::mutex cancel_mutex_{};
+  bool cancelled_{ false };
+  // Guards the one-shot delivery of the preamble handler (see deliver_metadata_header): the stream
+  // must resolve start()'s handler on every terminal, even when the lexer never fires its metadata
+  // callback (empty body, or a valid-JSON-but-not-an-object root).
+  std::atomic_bool metadata_header_delivered_{ false };
+  utils::movable_function<void(std::string, std::error_code)> metadata_header_handler_{};
+  // Bumped on every arm/cancel of the idle timer so a superseded timer completion is ignored.
+  std::atomic_uint64_t idle_generation_{ 0 };
   std::optional<std::string> metadata_;
   utils::json::streaming_lexer lexer_;
   std::mutex data_feed_mutex_{};
@@ -208,8 +480,9 @@ private:
 
 row_streamer::row_streamer(asio::io_context& io,
                            couchbase::core::http_response_body body,
-                           const std::string& pointer_expression)
-  : impl_{ std::make_shared<row_streamer_impl>(io, std::move(body), pointer_expression) }
+                           const std::string& pointer_expression,
+                           row_streamer_options options)
+  : impl_{ std::make_shared<row_streamer_impl>(io, std::move(body), pointer_expression, options) }
 {
 }
 
@@ -225,6 +498,13 @@ row_streamer::next_row(utils::movable_function<void(std::string, std::error_code
   impl_->next_row(std::move(handler));
 }
 
+auto
+row_streamer::set_deadline(std::chrono::time_point<std::chrono::steady_clock> deadline_tp)
+  -> io::deadline_state
+{
+  return impl_->set_deadline(deadline_tp);
+}
+
 void
 row_streamer::cancel()
 {
@@ -236,4 +516,10 @@ row_streamer::metadata() -> std::optional<std::string>
 {
   return impl_->metadata();
 }
+
+auto
+row_streamer::buffered_bytes() const -> std::size_t
+{
+  return impl_->buffered_bytes();
+}
 } // namespace couchbase::core

data/ext/couchbase/core/row_streamer.hxx

@@ -17,8 +17,11 @@
 
 #pragma once
 
+#include "core/io/stream_deadline.hxx"
+#include "row_streamer_options.hxx"
 #include "utils/movable_function.hxx"
 
+#include <chrono>
 #include <memory>
 #include <optional>
 #include <string>
@@ -39,7 +42,8 @@ class row_streamer
 public:
   row_streamer(asio::io_context& io,
                http_response_body body,
-               const std::string& pointer_expression);
+               const std::string& pointer_expression,
+               row_streamer_options options = {});
 
   /**
    *  Starts the row stream and returns all the metadata preceding the first row. This typically
@@ -52,6 +56,26 @@ public:
    */
   void next_row(utils::movable_function<void(std::string, std::error_code)>&& handler);
 
+  /**
+   * Closes the HTTP body at `deadline_tp`, whether or not a row is being pulled, releasing the
+   * connection where one is still held. A response received in full holds none: once its bytes
+   * have also been parsed the call arms nothing and reports body_already_ended, and while bytes
+   * remain unparsed it ends the body, dropping those and reporting the timeout. Rows already
+   * parsed stay consumable either way. The inter-read idle timer is armed only while a socket
+   * read is in flight, and a consumer stopped above the high-water mark has none.
+   *
+   * The terminal reaches the consumer through a pull. A pull outstanding at expiry completes
+   * with the timeout. A read that completes the response is the exception: the whole response
+   * arrived, so those bytes are delivered as a clean end. Otherwise the next pull reports the
+   * terminal, after any rows already buffered.
+   *
+   * Optional. The terminal is unambiguous_timeout for a read-only request, ambiguous_timeout
+   * otherwise. Re-arming before expiry replaces the deadline. Once the stream has ended a
+   * further call arms nothing and reports body_already_ended. Callable from any thread.
+   */
+  [[nodiscard]] auto set_deadline(std::chrono::time_point<std::chrono::steady_clock> deadline_tp)
+    -> io::deadline_state;
+
   /**
    * Cancels the row stream & closes the HTTP connection
    */
@@ -62,6 +86,12 @@ public:
    */
   auto metadata() -> std::optional<std::string>;
 
+  /**
+   * Number of row bytes currently buffered (delivered to the channel but not yet consumed).
+   * Exposed for back-pressure observability in tests and diagnostics.
+   */
+  [[nodiscard]] auto buffered_bytes() const -> std::size_t;
+
 private:
   std::shared_ptr<row_streamer_impl> impl_;
 };

data/ext/couchbase/core/row_streamer_options.hxx

@@ -0,0 +1,55 @@
+/* -*- 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
+
+#include <chrono>
+#include <cstddef>
+#include <cstdint>
+
+namespace couchbase::core
+{
+/**
+ * Tuning knobs for the streaming row engine (row_streamer). These are internal to core — there is
+ * no public API to set them yet; sensible static defaults apply unless a core caller (e.g. via
+ * cluster_options::streaming) overrides them.
+ */
+struct row_streamer_options {
+  // JSONPointer nesting depth the lexer descends before treating a value as a row.
+  std::uint32_t lexer_depth{ 4 };
+  // Buffered row bytes above which socket reads pause, and at or below which they resume
+  // (hysteresis). A zero low-water mark is honoured: reading resumes once the buffer is empty.
+  std::size_t high_water_bytes{ std::size_t{ 2 } * 1024 * 1024 };
+  std::size_t low_water_bytes{ std::size_t{ 512 } * 1024 };
+  // Hard ceiling on a single row (or the trailing metadata) before a synthetic error is raised.
+  std::size_t max_row_bytes{ std::size_t{ 64 } * 1024 * 1024 };
+  // Capacity of the row hand-off channel, in rows. A secondary bound; the byte watermarks above
+  // are the primary back-pressure limit.
+  std::size_t row_buffer_size{ 100 };
+  // Maximum time to wait for the server between socket reads while a read is in flight (an idle
+  // timer armed only while pulling, so a legitimately slow consumer is never timed out). Zero
+  // disables the timer.
+  std::chrono::milliseconds idle_timeout{ 0 };
+  // Whether the request being streamed is read-only (idempotent). Mirrors the buffered path's
+  // http_command branch. It classifies both timeout terminals, the inter-read idle timeout and
+  // the whole-stream deadline: unambiguous_timeout for a read-only request (definitely not
+  // applied, safe to retry) and ambiguous_timeout otherwise (a mutating query such as
+  // UPDATE ... RETURNING may have partially executed, so a retry layer must not treat it as safe
+  // to replay).
+  bool is_read_only{ false };
+};
+} // namespace couchbase::core

data/ext/couchbase/core/sasl/client.h

@@ -22,7 +22,10 @@
 
 #include <functional>
 #include <memory>
+#include <string>
+#include <string_view>
 #include <utility>
+#include <vector>
 
 namespace couchbase::core::sasl
 {