couchbase 3.8.2 → 3.9.0

data/ext/couchbase/core/impl/observe_poll.cxx

@@ -169,20 +169,21 @@ private:
 
 class observe_context;
 void
-observe_poll(const cluster& core, std::shared_ptr<observe_context> ctx);
+observe_poll(const std::shared_ptr<observe_context>& ctx);
 
 class observe_context : public std::enable_shared_from_this<observe_context>
 {
 public:
-  observe_context(asio::io_context& io,
+  observe_context(cluster core,
                   document_id id,
                   mutation_token token,
                   std::optional<std::chrono::milliseconds> timeout,
                   couchbase::persist_to persist_to,
                   couchbase::replicate_to replicate_to,
                   observe_handler&& handler)
-    : poll_deadline_{ io }
-    , poll_backoff_{ io }
+    : poll_deadline_{ core.io_context() }
+    , poll_backoff_{ core.io_context() }
+    , core_{ std::move(core) }
     , id_{ std::move(id) }
     , status_{ std::move(token) }
     , timeout_{ timeout }
@@ -192,6 +193,38 @@ public:
   {
   }
 
+  observe_context(const observe_context&) = delete;
+  observe_context(observe_context&&) = delete;
+  auto operator=(const observe_context&) -> observe_context& = delete;
+  auto operator=(observe_context&&) -> observe_context& = delete;
+
+  ~observe_context()
+  {
+    // Fail closed. The context is anchored on the io_context by poll_deadline_ for the whole
+    // operation, while the config wait captures a weak_ptr and the seqno requests are cancellable
+    // core operations. If the io_context is torn down mid-poll, every continuation is dropped and
+    // the context is destroyed here with handler_ still set. Deliver an error so a std::future
+    // caller never observes broken_promise and a callback caller never hangs -- this is the
+    // backstop for every legacy-durability mutation (persist_to / replicate_to), which routes its
+    // handler through the observe poll.
+    observe_handler handler{};
+    {
+      const std::scoped_lock lock(handler_mutex_);
+      std::swap(handler_, handler);
+    }
+    if (handler) {
+      try {
+        handler(errc::network::cluster_closed);
+      } catch (...) { // NOLINT(bugprone-empty-catch)
+      }
+    }
+  }
+
+  [[nodiscard]] auto core() const -> const cluster&
+  {
+    return core_;
+  }
+
   void start()
   {
     poll_deadline_.expires_after(poll_deadline_interval_);
@@ -294,27 +327,30 @@ public:
     on_last_response_ = std::move(handler);
   }
 
-  void execute(const cluster& core)
+  void execute()
   {
     auto requests = std::move(requests_);
     status_.reset();
-    on_last_response(requests.size(), [core, ctx = shared_from_this()](std::error_code ec) mutable {
+    on_last_response(requests.size(), [weak = weak_from_this()](std::error_code ec) mutable {
       if (ec == asio::error::operation_aborted) {
         return;
       }
-      observe_poll(core, std::move(ctx));
+      if (auto ctx = weak.lock()) {
+        observe_poll(ctx);
+      }
     });
     for (auto&& request : requests) {
-      core.execute(std::move(request),
-                   [ctx = shared_from_this()](observe_seqno_response&& response) {
-                     ctx->handle_response(std::move(response));
-                   });
+      core_.execute(std::move(request),
+                    [ctx = shared_from_this()](observe_seqno_response&& response) {
+                      ctx->handle_response(std::move(response));
+                    });
     }
   }
 
 private:
   asio::steady_timer poll_deadline_;
   asio::steady_timer poll_backoff_;
+  cluster core_;
   const document_id id_;
   observe_status status_;
   std::optional<std::chrono::milliseconds> timeout_;
@@ -330,13 +366,22 @@ private:
 };
 
 void
-observe_poll(const cluster& core, std::shared_ptr<observe_context> ctx)
+observe_poll(const std::shared_ptr<observe_context>& ctx)
 {
   const std::string bucket_name = ctx->bucket_name();
-  core.with_bucket_configuration(
+  // Capture a weak_ptr, not the context or a core copy: with_bucket_configuration parks this
+  // callback in the core (in the bucket-bootstrap window it is not drained on close). The context
+  // is kept alive meanwhile by poll_deadline_ on the io_context, and it owns the core through its
+  // core_ member -- capturing either strongly here would form a cycle that survives cluster close
+  // and strand the handler.
+  ctx->core().with_bucket_configuration(
     bucket_name,
-    [core, ctx = std::move(ctx)](
+    [weak = std::weak_ptr<observe_context>(ctx)](
       std::error_code ec, const std::shared_ptr<core::topology::configuration>& config) mutable {
+      auto ctx = weak.lock();
+      if (!ctx) {
+        return;
+      }
       if (ec) {
         return ctx->finish(ec);
       }
@@ -360,7 +405,7 @@ observe_poll(const cluster& core, std::shared_ptr<observe_context> ctx)
             observe_seqno_request{ replica_id, false, ctx->partition_uuid(), ctx->timeout() });
         }
       }
-      ctx->execute(core);
+      ctx->execute();
     });
 }
 } // namespace
@@ -374,14 +419,9 @@ initiate_observe_poll(const cluster& core,
                       couchbase::replicate_to replicate_to,
                       observe_handler&& handler)
 {
-  auto ctx = std::make_shared<observe_context>(core.io_context(),
-                                               std::move(id),
-                                               std::move(token),
-                                               timeout,
-                                               persist_to,
-                                               replicate_to,
-                                               std::move(handler));
+  auto ctx = std::make_shared<observe_context>(
+    core, std::move(id), std::move(token), timeout, persist_to, replicate_to, std::move(handler));
   ctx->start();
-  return observe_poll(core, std::move(ctx));
+  return observe_poll(ctx);
 }
 } // namespace couchbase::core::impl

data/ext/couchbase/core/impl/public_analytics_stream_result.cxx

@@ -0,0 +1,372 @@
+/* -*- 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.
+ */
+
+#include <couchbase/analytics_meta_data.hxx>
+#include <couchbase/analytics_metrics.hxx>
+#include <couchbase/analytics_status.hxx>
+#include <couchbase/analytics_stream_result.hxx>
+#include <couchbase/analytics_warning.hxx>
+#include <couchbase/error_codes.hxx>
+
+#include "core/operations/document_analytics.hxx"
+#include "core/utils/binary.hxx"
+
+#include "analytics.hxx"
+#include "error.hxx"
+#include "internal_analytics_stream_result.hxx"
+#include "observability_recorder.hxx"
+
+#include <future>
+#include <memory>
+#include <mutex>
+#include <optional>
+#include <string>
+#include <system_error>
+#include <utility>
+#include <vector>
+
+namespace couchbase
+{
+namespace
+{
+auto
+to_binary(const std::string& s) -> codec::binary
+{
+  return core::utils::to_binary(s);
+}
+
+auto
+build_analytics_meta_data(core::operations::analytics_response::analytics_meta_data meta)
+  -> analytics_meta_data
+{
+  std::vector<analytics_warning> warnings;
+  warnings.reserve(meta.warnings.size());
+  for (auto& w : meta.warnings) {
+    warnings.emplace_back(w.code, std::move(w.message));
+  }
+
+  const analytics_metrics metrics{
+    meta.metrics.elapsed_time,  meta.metrics.execution_time,    meta.metrics.result_count,
+    meta.metrics.result_size,   meta.metrics.processed_objects, meta.metrics.error_count,
+    meta.metrics.warning_count,
+  };
+
+  std::optional<codec::binary> signature;
+  if (meta.signature) {
+    signature = to_binary(*meta.signature);
+  }
+
+  return analytics_meta_data{
+    std::move(meta.request_id),
+    std::move(meta.client_context_id),
+    core::impl::map_analytics_status(meta.status),
+    std::move(warnings),
+    metrics,
+    std::move(signature),
+  };
+}
+} // namespace
+
+// ---------------------------------------------------------------------------
+// internal_analytics_stream_result implementation
+// ---------------------------------------------------------------------------
+
+internal_analytics_stream_result::internal_analytics_stream_result(
+  core::analytics_stream stream,
+  std::unique_ptr<core::impl::observability_recorder> obs_rec,
+  core::error_context::analytics ctx)
+  : stream_{ std::move(stream) }
+  , ctx_{ std::move(ctx) }
+  , obs_rec_{ std::move(obs_rec) }
+{
+}
+
+internal_analytics_stream_result::~internal_analytics_stream_result()
+{
+  cancel();
+}
+
+void
+internal_analytics_stream_result::cancel()
+{
+  // Resolve any parked meta_data() futures with a cancellation error so they don't throw
+  // broken_promise when the stream is torn down before reaching a natural terminal. Idempotent
+  // via terminal_reached_, so a real terminal that already ran is preserved.
+  resolve_meta_data(errc::common::request_canceled);
+  stream_.cancel();
+}
+
+auto
+internal_analytics_stream_result::signature() const -> std::optional<codec::binary>
+{
+  auto raw = stream_.signature();
+  if (!raw) {
+    return {};
+  }
+  return to_binary(*raw);
+}
+
+void
+internal_analytics_stream_result::resolve_meta_data(std::error_code ec)
+{
+  std::pair<error, analytics_meta_data> value;
+  if (ec) {
+    // Report the terminal against the request's context with whatever the response said stamped on,
+    // so a mid-stream failure carries the same detail (statement, service error, endpoint) as one
+    // that never started. A cancellation leaves the service error code and message unset, because
+    // the service never reported one, but the envelope parsed so far is still reported as the body:
+    // it names the request id the service logs are keyed by, and the buffered path likewise reports
+    // whatever body it received.
+    auto ctx = ctx_;
+    ctx.ec = ec;
+    core::apply_error_details(ctx, stream_.error_details());
+    value.first = core::impl::make_error(ctx);
+  }
+  auto core_meta = stream_.meta_data();
+  if (core_meta) {
+    value.second = build_analytics_meta_data(std::move(*core_meta));
+  }
+
+  std::vector<std::promise<std::pair<error, analytics_meta_data>>> to_satisfy;
+  {
+    const std::scoped_lock lk{ meta_mutex_ };
+    if (terminal_reached_) {
+      return;
+    }
+    terminal_reached_ = true;
+    terminal_value_ = value;
+    to_satisfy = std::move(pending_meta_promises_);
+    pending_meta_promises_.clear();
+  }
+  for (auto& promise : to_satisfy) {
+    promise.set_value(value);
+  }
+  // Reached exactly once (the terminal_reached_ guard above returns on every later call), so the
+  // operation is finished here: record the latency metric and end the operation span. ec is the
+  // terminal error (falsy on a clean drain, request_canceled on teardown before a natural end).
+  if (obs_rec_) {
+    obs_rec_->finish(ec);
+  }
+}
+
+auto
+internal_analytics_stream_result::meta_data() -> std::future<std::pair<error, analytics_meta_data>>
+{
+  const std::scoped_lock lk{ meta_mutex_ };
+  std::promise<std::pair<error, analytics_meta_data>> promise;
+  auto future = promise.get_future();
+  if (terminal_reached_) {
+    promise.set_value(terminal_value_);
+  } else {
+    pending_meta_promises_.push_back(std::move(promise));
+  }
+  return future;
+}
+
+void
+internal_analytics_stream_result::next(analytics_row_handler&& handler)
+{
+  {
+    // Idempotent terminal: once the stream has ended, re-deliver the terminal (clean end or the
+    // terminal error) instead of issuing a pull that would block forever on the drained channel.
+    const std::scoped_lock lk{ meta_mutex_ };
+    if (terminal_reached_) {
+      return handler(terminal_value_.first, std::nullopt);
+    }
+  }
+  bool expected = false;
+  if (!pull_in_flight_.compare_exchange_strong(expected, true)) {
+    // Enforce the single-outstanding-next() contract instead of racing the single-consumer channel.
+    return handler(
+      error{ errc::common::invalid_argument, "a previous next() call is still in flight" },
+      std::nullopt);
+  }
+  // Capture a strong self so the object outlives an in-flight pull; dropping the public handle
+  // mid-pull would otherwise destroy this object before the channel completion runs (use-after-
+  // free). The stream is always owned via shared_ptr (make_shared in dispatch_analytics_stream).
+  stream_.next_row([handler = std::move(handler), self = shared_from_this()](
+                     std::optional<std::string> row, std::error_code ec) mutable {
+    if (row.has_value()) {
+      // Real row (ec is falsy). Release the pull gate before invoking the handler so it may
+      // immediately issue the next pull.
+      self->pull_in_flight_.store(false);
+      return handler({}, analytics_row{ to_binary(*row) });
+    }
+    // Terminal (nullopt row): publish the terminal state and intentionally leave pull_in_flight_
+    // set. Every later next() is served by the terminal_reached_ guard (idempotent re-delivery) and
+    // must never issue another pull onto the drained channel, so the gate is never reopened — this
+    // also backstops a caller that violates the single-outstanding-next() contract from a racing
+    // thread before terminal_reached_ becomes visible.
+    self->resolve_meta_data(ec);
+    if (ec) {
+      // Deliver the contextual error resolve_meta_data() has just published rather than building a
+      // bare one here. This is the first and usually only observation of a mid-stream terminal, so
+      // it has to carry the same diagnostics as every later next() (served by the terminal_reached_
+      // guard above) and as meta_data(); constructing a fresh error here would report the one case
+      // this class exists to describe with an empty context.
+      error terminal_error;
+      {
+        const std::scoped_lock lk{ self->meta_mutex_ };
+        terminal_error = self->terminal_value_.first;
+      }
+      return handler(std::move(terminal_error), {});
+    }
+    return handler({}, {});
+  });
+}
+
+// ---------------------------------------------------------------------------
+// analytics_stream_result public implementation
+// ---------------------------------------------------------------------------
+
+analytics_stream_result::analytics_stream_result(
+  std::shared_ptr<internal_analytics_stream_result> internal)
+  : internal_{ std::move(internal) }
+{
+}
+
+void
+analytics_stream_result::next(analytics_row_handler&& handler) const
+{
+  if (!internal_) {
+    // Empty handle behaves as an immediately-exhausted stream.
+    handler(error{}, std::nullopt);
+    return;
+  }
+  return internal_->next(std::move(handler));
+}
+
+auto
+analytics_stream_result::next() const -> std::future<std::pair<error, std::optional<analytics_row>>>
+{
+  auto barrier = std::make_shared<std::promise<std::pair<error, std::optional<analytics_row>>>>();
+  if (!internal_) {
+    // Empty handle behaves as an immediately-exhausted stream.
+    barrier->set_value({ error{}, std::nullopt });
+    return barrier->get_future();
+  }
+  internal_->next([barrier](const auto& err, const auto& row) mutable {
+    barrier->set_value({ err, row });
+  });
+  return barrier->get_future();
+}
+
+auto
+analytics_stream_result::signature() const -> std::optional<codec::binary>
+{
+  if (!internal_) {
+    return {};
+  }
+  return internal_->signature();
+}
+
+auto
+analytics_stream_result::meta_data() const -> std::future<std::pair<error, analytics_meta_data>>
+{
+  if (!internal_) {
+    // Empty handle resolves immediately with empty metadata.
+    std::promise<std::pair<error, analytics_meta_data>> p;
+    p.set_value({ error{}, analytics_meta_data{} });
+    return p.get_future();
+  }
+  return internal_->meta_data();
+}
+
+void
+analytics_stream_result::cancel() const
+{
+  if (internal_) {
+    return internal_->cancel();
+  }
+}
+
+// ---------------------------------------------------------------------------
+// iterator implementation
+// ---------------------------------------------------------------------------
+
+analytics_stream_result::iterator::iterator(
+  std::shared_ptr<internal_analytics_stream_result> internal)
+  : internal_{ std::move(internal) }
+{
+  if (internal_) {
+    fetch_item();
+  } else {
+    // An empty result handle has no rows: the iterator starts already at end.
+    terminal_ = true;
+  }
+}
+
+void
+analytics_stream_result::iterator::fetch_item()
+{
+  auto barrier = std::make_shared<std::promise<std::pair<error, std::optional<analytics_row>>>>();
+  internal_->next([barrier](const error& err, std::optional<analytics_row> row) mutable {
+    barrier->set_value({ err, std::move(row) });
+  });
+  auto result = barrier->get_future().get();
+  if (result.first) {
+    // Terminal error: deliver it as one visible element (still != end()) so a range-for loop can
+    // observe it; the next increment then advances to true end.
+    item_ = { result.first, {} };
+    terminal_ = false;
+    error_pending_ = true;
+  } else if (!result.second.has_value()) {
+    // Clean end-of-stream.
+    item_ = {};
+    terminal_ = true;
+    error_pending_ = false;
+  } else {
+    item_ = { {}, *result.second };
+    terminal_ = false;
+    error_pending_ = false;
+  }
+}
+
+auto
+analytics_stream_result::iterator::operator*() const -> std::pair<error, analytics_row>
+{
+  return item_;
+}
+
+auto
+analytics_stream_result::iterator::operator++() -> analytics_stream_result::iterator&
+{
+  if (error_pending_) {
+    // The terminal error element has been consumed; advance to end().
+    error_pending_ = false;
+    item_ = {};
+    terminal_ = true;
+    return *this;
+  }
+  fetch_item();
+  return *this;
+}
+
+auto
+analytics_stream_result::begin() const -> analytics_stream_result::iterator
+{
+  // The iterator constructor treats a null internal handle as an already-drained stream, so an
+  // empty result handle yields begin() == end().
+  return analytics_stream_result::iterator{ internal_ };
+}
+
+auto
+analytics_stream_result::end() const -> analytics_stream_result::end_sentinel
+{
+  return {};
+}
+} // namespace couchbase

data/ext/couchbase/core/impl/public_bucket.cxx

@@ -15,21 +15,24 @@
  *   limitations under the License.
  */
 
-#include <couchbase/bucket.hxx>
-
 #include "core/cluster.hxx"
 #include "core/tracing/constants.hxx"
 #include "core/tracing/tracer_wrapper.hxx"
 #include "diagnostics.hxx"
 #include "observability_recorder.hxx"
+#include "wait_until_ready.hxx"
+#include <couchbase/bucket.hxx>
+#include <couchbase/build_config.hxx>
 
 #include <couchbase/collection.hxx>
 #include <couchbase/collection_manager.hxx>
 #include <couchbase/error.hxx>
+#include <couchbase/error_codes.hxx>
 #include <couchbase/ping_options.hxx>
 #include <couchbase/ping_result.hxx>
 #include <couchbase/scope.hxx>
 
+#include <chrono>
 #include <future>
 #include <memory>
 #include <string_view>
@@ -68,6 +71,15 @@ public:
   {
     auto obs_rec = create_observability_recorder(
       core::tracing::operation::ping, std::nullopt, options.parent_span);
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+    if (core_.is_protostellar()) {
+      // couchbase2 has no per-bucket sessions to probe; mirror cluster::ping and the other SDKs.
+      obs_rec->finish(errc::common::feature_not_available);
+      return handler(error{ errc::common::feature_not_available,
+                            "ping is not supported over the couchbase2 protocol" },
+                     {});
+    }
+#endif
     return core_.ping(
       options.report_id,
       name_,
@@ -79,6 +91,20 @@ public:
       });
   }
 
+  void wait_until_ready(std::chrono::milliseconds timeout,
+                        const wait_until_ready_options::built& options,
+                        wait_until_ready_handler&& handler) const
+  {
+    return core::impl::wait_until_ready(core_,
+                                        name_,
+                                        timeout,
+                                        options.desired_state,
+                                        core::impl::to_core_service_types(options.service_types),
+                                        [handler = std::move(handler)](std::error_code ec) mutable {
+                                          return handler(couchbase::error{ ec });
+                                        });
+  }
+
 private:
   [[nodiscard]] auto create_observability_recorder(
     const std::string& operation_name,
@@ -148,6 +174,26 @@ bucket::ping(const couchbase::ping_options& options) const
   return barrier->get_future();
 }
 
+void
+bucket::wait_until_ready(std::chrono::milliseconds timeout,
+                         const couchbase::wait_until_ready_options& options,
+                         couchbase::wait_until_ready_handler&& handler) const
+{
+  return impl_->wait_until_ready(timeout, options.build(), std::move(handler));
+}
+
+auto
+bucket::wait_until_ready(std::chrono::milliseconds timeout,
+                         const couchbase::wait_until_ready_options& options) const
+  -> std::future<error>
+{
+  auto barrier = std::make_shared<std::promise<error>>();
+  wait_until_ready(timeout, options, [barrier](auto err) mutable {
+    barrier->set_value(std::move(err));
+  });
+  return barrier->get_future();
+}
+
 auto
 bucket::collections() const -> collection_manager
 {