couchbase 3.8.1 → 3.9.0

data/ext/couchbase/core/cluster.cxx

@@ -17,6 +17,16 @@
 
 #include <couchbase/build_config.hxx>
 
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+#include "core/protostellar/component.hxx"
+#include "core/protostellar/credentials.hxx"
+#include "core/protostellar/error_utils.hxx"
+
+#include <couchbase/retry_strategy.hxx>
+
+#include <asio/steady_timer.hpp>
+#endif
+
 #define COUCHBASE_CXX_CLIENT_IGNORE_CORE_DEPRECATIONS
 #include "cluster.hxx"
 
@@ -24,23 +34,25 @@
 #undef COUCHBASE_CXX_CLIENT_IGNORE_CORE_DEPRECATIONS
 
 #include "bucket.hxx"
+#include "capella.hxx"
 #include "capella_ca.hxx"
+#include "cluster_label_listener.hxx"
+#include "core/analytics_stream_component.hxx"
 #include "core/app_telemetry_meter.hxx"
 #include "core/app_telemetry_reporter.hxx"
+#include "core/core_sdk_shim.hxx"
 #include "core/diagnostics.hxx"
 #include "core/error.hxx"
-#include "core/impl/get_replica.hxx"
+#include "core/http_component.hxx"
 #include "core/impl/lookup_in_replica.hxx"
 #include "core/impl/observe_seqno.hxx"
 #include "core/io/http_command.hxx"
 #include "core/io/http_message.hxx"
 #include "core/io/http_session_manager.hxx"
 #include "core/io/mcbp_session.hxx"
-#ifdef COUCHBASE_CXX_CLIENT_COLUMNAR
-#include "core/io/config_tracker.hxx"
-#endif
-#include "cluster_label_listener.hxx"
+#include "core/io/mcbp_traits.hxx"
 #include "core/logger/logger.hxx"
+#include "core/logger/redaction.hxx"
 #include "core/management/analytics_link_azure_blob_external.hxx"
 #include "core/management/analytics_link_couchbase_remote.hxx"
 #include "core/management/analytics_link_s3_external.hxx"
@@ -59,6 +71,7 @@
 #include "core/operations/document_get_and_touch.hxx"
 #include "core/operations/document_get_any_replica.hxx"
 #include "core/operations/document_get_projected.hxx"
+#include "core/operations/document_get_replica.hxx"
 #include "core/operations/document_increment.hxx"
 #include "core/operations/document_insert.hxx"
 #include "core/operations/document_lookup_in.hxx"
@@ -149,13 +162,14 @@
 #include "core/orphan_reporter.hxx"
 #include "core/platform/uuid.h"
 #include "core/protocol/hello_feature.hxx"
+#include "core/query_stream_component.hxx"
 #include "core/service_type.hxx"
 #include "core/tls_verify_mode.hxx"
 #include "core/topology/capabilities.hxx"
 #include "core/tracing/noop_tracer.hxx"
 #include "core/tracing/threshold_logging_tracer.hxx"
 #include "core/tracing/tracer_wrapper.hxx"
-#include "core/utils/join_strings.hxx"
+#include "core/utils/deadline.hxx"
 #include "core/utils/movable_function.hxx"
 #include "crud_component.hxx"
 #include "dispatcher.hxx"
@@ -174,9 +188,11 @@
 #include <asio/post.hpp>
 #include <asio/ssl/verify_mode.hpp>
 
+#include <algorithm>
 #include <atomic>
 #include <chrono>
 #include <cstring>
+#include <list>
 #include <map>
 #include <memory>
 #include <mutex>
@@ -202,6 +218,32 @@ class ping_collector_impl
   std::mutex mutex_{};
 
 public:
+  /**
+   * Counted like a reporter, so the ping cannot complete while pings are still being dispatched.
+   * This prevents erroneously returning early when the in-flight pings momentarily drop to 0.
+   */
+  class dispatch_scope
+  {
+  public:
+    explicit dispatch_scope(std::shared_ptr<ping_collector_impl> collector)
+      : collector_{ std::move(collector) }
+    {
+    }
+
+    dispatch_scope(const dispatch_scope&) = delete;
+    dispatch_scope(dispatch_scope&&) = delete;
+    auto operator=(const dispatch_scope&) -> dispatch_scope& = delete;
+    auto operator=(dispatch_scope&&) -> dispatch_scope& = delete;
+
+    ~dispatch_scope()
+    {
+      collector_->release();
+    }
+
+  private:
+    std::shared_ptr<ping_collector_impl> collector_;
+  };
+
   ping_collector_impl(std::string report_id,
                       utils::movable_function<void(diag::ping_result)>&& handler)
     : res_{ std::move(report_id), meta::sdk_id() }
@@ -226,11 +268,11 @@ public:
 
   void report(diag::endpoint_ping_info&& info) override
   {
-    const std::scoped_lock lock(mutex_);
-    res_.services[info.type].emplace_back(std::move(info));
-    if (--expected_ == 0) {
-      invoke_handler();
+    {
+      const std::scoped_lock lock(mutex_);
+      res_.services[info.type].emplace_back(std::move(info));
     }
+    release();
   }
 
   auto build_reporter() -> std::shared_ptr<diag::ping_reporter> override
@@ -239,17 +281,115 @@ public:
     return shared_from_this();
   }
 
+  [[nodiscard]] auto begin_dispatch() -> std::shared_ptr<dispatch_scope>
+  {
+    ++expected_;
+    return std::make_shared<dispatch_scope>(shared_from_this());
+  }
+
+private:
+  void release()
+  {
+    if (--expected_ == 0) {
+      invoke_handler();
+    }
+  }
+
   void invoke_handler()
   {
-    if (handler_ != nullptr) {
-      handler_(std::move(res_));
+    utils::movable_function<void(diag::ping_result)> handler{};
+    diag::ping_result res{};
+    {
+      const std::scoped_lock lock(mutex_);
+      if (handler_ == nullptr) {
+        return;
+      }
+      handler = std::move(handler_);
       handler_ = nullptr;
+      res = std::move(res_);
     }
+    handler(std::move(res));
   }
 };
 
 namespace
 {
+// A wait with an optional deadline, held by cluster_impl::defer_until_open() or
+// cluster_impl::wait_until(). complete() runs on the IO thread; the destructor runs `resume` on
+// whichever thread drops the last reference.
+struct deferred_request {
+  utils::movable_function<void(std::error_code)> resume{};
+  std::unique_ptr<asio::steady_timer> deadline{};
+  std::atomic_bool completed{ false };
+  // Where the entry sits in cluster_impl::deferred_until_open_, while it is there. Guarded by
+  // deferred_until_open_mutex_.
+  std::optional<std::list<std::shared_ptr<deferred_request>>::iterator> queued{};
+
+  void complete(std::error_code ec)
+  {
+    if (completed.exchange(true)) {
+      return;
+    }
+    if (deadline) {
+      // An armed timer keeps the entry and the io_context's work alive until it expires.
+      deadline->cancel();
+      // The deadline can pass while the IO thread is busy, before the timer callback runs. A
+      // request resumed after it would be dispatched with remaining_until()'s floor.
+      if (!ec && deadline->expiry() <= std::chrono::steady_clock::now()) {
+        ec = errc::common::unambiguous_timeout;
+      }
+    }
+    auto handler = std::move(resume);
+    handler(ec);
+  }
+
+  // complete() for a thread other than the IO thread: the timer is not touched, and is left to
+  // expire or to be destroyed with its io_context.
+  void complete_off_io_thread(std::error_code ec)
+  {
+    if (completed.exchange(true)) {
+      return;
+    }
+    auto handler = std::move(resume);
+    if (handler) {
+      handler(ec);
+    }
+  }
+
+  deferred_request() = default;
+  deferred_request(const deferred_request&) = delete;
+  deferred_request(deferred_request&&) = delete;
+  auto operator=(const deferred_request&) -> deferred_request& = delete;
+  auto operator=(deferred_request&&) -> deferred_request& = delete;
+
+  // A stopped io_context drops the timer wait and any completion posted to it. The last reference
+  // then goes here, and the request completes with cluster_closed rather than never. The timer is
+  // not touched: its io_context may be shutting down.
+  ~deferred_request()
+  {
+    try {
+      complete_off_io_thread(errc::network::cluster_closed);
+    } catch (...) { // NOLINT(bugprone-empty-catch)
+    }
+  }
+};
+
+using utils::remaining_until;
+
+// A durable mutation gets at least this long, counted from when it is issued.
+constexpr std::chrono::milliseconds durability_timeout_floor{ 1'500 };
+
+// Whether T has a client_context_id member: a request that can carry one, or a context that reports
+// it.
+template<typename T, typename = void>
+struct has_client_context_id : std::false_type {
+};
+
+template<typename T>
+struct has_client_context_id<T, std::void_t<decltype(std::declval<T&>().client_context_id)>>
+  : std::true_type {
+};
+
 template<typename Request>
 auto
 is_feature_supported(const Request& /* request */,
@@ -270,6 +410,10 @@ is_feature_supported(const operations::search_request& request,
   if (request.vector_search && !capabilities.supports_vector_search()) {
     return false;
   }
+  // "none" is not behind the score fusion capability
+  if (is_score_fusion(request.scoring) && !capabilities.supports_score_fusion()) {
+    return false;
+  }
 
   return true;
 }
@@ -279,6 +423,7 @@ is_feature_supported(const operations::analytics_request& /*request*/,
                      const configuration_capabilities& capabilities,
                      const cluster_options& options) -> bool
 {
+  // cppcheck-suppress knownConditionTrueFalse
   if (operations::analytics_request::allow_enterprise_analytics) {
     return true;
   }
@@ -292,27 +437,75 @@ is_feature_supported(const operations::management::search_index_upsert_request&
 {
   return !request.index.is_vector_index() || capabilities.supports_vector_search();
 }
+
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+// Extract the error_code from a response's error context. KV responses carry a
+// key_value_error_context (ec() accessor); the query/analytics/search/view/management responses
+// carry a plain error_context::* struct with an `ec` field.
+inline auto
+protostellar_response_ec(const key_value_error_context& ctx) -> std::error_code
+{
+  return ctx.ec();
+}
+template<typename Context>
+inline auto
+protostellar_response_ec(const Context& ctx) -> std::error_code
+{
+  return ctx.ec;
+}
+
+// The cluster's configured timeouts, in the form the component and the retry loop both read them
+// from. Assigned per field rather than brace-initialised positionally: every member has the same
+// type, so a mis-ordering is not a compile error, and an omitted one silently takes the struct's
+// own default instead of the value the caller configured.
+inline auto
+make_component_timeouts(const cluster_options& options) -> protostellar::component_timeouts
+{
+  protostellar::component_timeouts timeouts{};
+  timeouts.key_value = options.key_value_timeout;
+  timeouts.key_value_durable = options.key_value_durable_timeout;
+  timeouts.query = options.query_timeout;
+  timeouts.analytics = options.analytics_timeout;
+  timeouts.search = options.search_timeout;
+  timeouts.view = options.view_timeout;
+  timeouts.management = options.management_timeout;
+  return timeouts;
+}
+#endif
 } // namespace
 
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+// Whether the couchbase2 component can carry this request, answered by asking whether it has an
+// execute() overload for it.
+//
+// The alternative -- a hand-maintained list of request types -- has to agree with the overload set
+// and nothing checks that it does. A type in the list with no overload fails to compile, so that
+// half is safe; an overload with no entry in the list is silently unreachable, and that is how
+// query_index_build_deferred_request came to be wired to a gateway RPC that no caller could
+// reach. Detecting the overload makes the list *be* the overload set.
+template<typename Request, typename = void>
+struct component_routes : std::false_type {
+};
+
+template<typename Request>
+struct component_routes<
+  Request,
+  std::void_t<decltype(std::declval<protostellar::component&>().execute(
+    std::declval<Request>(),
+    std::declval<utils::movable_function<void(typename Request::response_type)>>()))>>
+  : std::true_type {
+};
+#endif
+
 class cluster_impl : public std::enable_shared_from_this<cluster_impl>
 {
 public:
-#ifdef COUCHBASE_CXX_CLIENT_COLUMNAR
-  explicit cluster_impl(asio::io_context& ctx)
-    : ctx_(ctx)
-    , work_(asio::make_work_guard(ctx_))
-    , session_manager_(std::make_shared<io::http_session_manager>(id_, ctx_, tls_, origin_))
-    , retry_backoff_(ctx_)
-  {
-  }
-#else
   explicit cluster_impl(asio::io_context& ctx)
     : ctx_(ctx)
     , work_(asio::make_work_guard(ctx_))
     , session_manager_(std::make_shared<io::http_session_manager>(id_, ctx_, tls_, origin_))
   {
   }
-#endif
 
   auto io_context() -> asio::io_context&
   {
@@ -334,7 +527,21 @@ public:
       tls_options |= asio::ssl::context::no_tlsv1_2; // published: 2008, still in use
     }
     ctx->set_options(tls_options);
-    switch (origin_.options().tls_verify) {
+    const auto requested_verify = origin_.options().tls_verify;
+    const auto effective_verify = effective_tls_verify_mode(requested_verify, has_capella_host);
+    if (requested_verify == tls_verify_mode::none && effective_verify == tls_verify_mode::peer) {
+      CB_LOG_WARNING(
+        "[{}]: TLS certificate verification cannot be disabled when connecting to Couchbase "
+        "Capella; enforcing peer verification (ignoring tls_verify=none).",
+        id_);
+    } else if (effective_verify == tls_verify_mode::none) {
+      CB_LOG_WARNING(
+        "[{}]: TLS certificate verification is DISABLED (tls_verify=none). The server's "
+        "identity will NOT be checked and the connection is vulnerable to interception. This "
+        "is insecure and must not be used in production.",
+        id_);
+    }
+    switch (effective_verify) {
       case tls_verify_mode::none:
         ctx->set_verify_mode(asio::ssl::verify_none);
         break;
@@ -465,27 +672,58 @@ public:
       return handler(errc::common::invalid_argument);
     }
 
-    origin_ = std::move(origin);
+    {
+      const std::scoped_lock lock(origin_mutex_);
+      origin_ = std::move(origin);
+    }
+    apply_log_redaction();
     CB_LOG_DEBUG(R"(open cluster, id: "{}", core version: "{}", connection string: {}, {})",
                  id_,
                  couchbase::core::meta::sdk_semver(),
-                 origin_.connection_string(),
-                 origin_.to_json());
+                 logger::user_data(origin_.connection_string()),
+                 logger::user_data(origin_.to_json()));
+    // The scheme is recognised in every build; only the ability to serve it is conditional. The
+    // parser stays identical either way, so no API or ABI depends on the build mode -- a build
+    // without couchbase2 support answers with a named error instead of attempting an MCBP handshake
+    // against the gateway's gRPC port, which surfaced as an unrelated bootstrap timeout.
+    if (origin_.uses_protostellar()) {
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+      return open_protostellar(std::move(handler));
+#else
+      CB_LOG_ERROR(
+        R"([{}]: cannot open "{}": this build has no couchbase2 support )"
+        "(COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2 is off), so the couchbase2:// scheme cannot be "
+        "served.",
+        id_,
+        logger::user_data(origin_.connection_string()));
+      stopped_ = true;
+      work_.reset();
+      return handler(errc::common::feature_not_available);
+#endif
+    }
+    {
+      const std::scoped_lock lock(deferred_until_open_mutex_);
+      opening_ = true;
+    }
     setup_observability();
     if (origin_.options().enable_dns_srv) {
-      std::string hostname;
-      std::string port;
-      std::tie(hostname, port) = origin_.next_address();
+      auto [hostname, port] = origin_.next_address();
       dns_srv_tracker_ = std::make_shared<impl::dns_srv_tracker>(
         ctx_, hostname, origin_.options().dns_config, origin_.options().enable_tls);
+      {
+        // close() completes the open itself rather than waiting out the lookup.
+        const std::scoped_lock lock(dns_srv_open_handler_mutex_);
+        dns_srv_open_handler_ = std::move(handler);
+      }
       return asio::post(asio::bind_executor(
-        ctx_,
-        [self = shared_from_this(),
-         hostname = std::move(hostname),
-         handler = std::move(handler)]() mutable {
+        ctx_, [self = shared_from_this(), hostname = std::move(hostname)]() mutable {
           return self->dns_srv_tracker_->get_srv_nodes(
-            [self, hostname = std::move(hostname), handler = std::move(handler)](
-              origin::node_list nodes, std::error_code ec) mutable {
+            [self, hostname = std::move(hostname)](origin::node_list nodes,
+                                                   std::error_code ec) mutable {
+              auto handler = self->take_dns_srv_open_handler();
+              if (!handler) {
+                return;
+              }
               if (ec) {
 #ifdef __clang_analyzer__
                 // TODO(CXXCBC-549): clang-tidy-19 reports potential memory leak here
@@ -496,11 +734,13 @@ public:
                 });
               }
               if (!nodes.empty()) {
+                const std::scoped_lock lock(self->origin_mutex_);
                 self->origin_.set_nodes(std::move(nodes));
                 CB_LOG_INFO(
                   "replace list of bootstrap nodes with addresses from DNS SRV of \"{}\": [{}]",
-                  hostname,
-                  utils::join_strings(self->origin_.get_nodes(), ", "));
+                  logger::system_data(hostname),
+                  logger::system_data_list(self->origin_.get_node_addresses(),
+                                           logger::list_entries::quoted));
               }
               return self->do_open(std::move(handler));
             });
@@ -509,40 +749,63 @@ public:
     do_open(std::move(handler));
   }
 
-#ifdef COUCHBASE_CXX_CLIENT_COLUMNAR
-  void open_in_background(couchbase::core::origin origin,
-                          utils::movable_function<void(std::error_code)>&& handler)
+  // Runs `resume` once: with the error that `start` reports through the completion it is given, or
+  // with unambiguous_timeout when `deadline` passes first. A success reported after `deadline` is a
+  // timeout too. `resume` runs on the IO thread while the cluster is open. After close() the IO
+  // thread may never run again, so a stopped cluster completes at once with cluster_closed, and a
+  // wait that reports after close() runs `resume` on the thread that reports.
+  template<typename Start>
+  void wait_until(std::chrono::steady_clock::time_point deadline,
+                  utils::movable_function<void(std::error_code)>&& resume,
+                  Start&& start)
   {
     if (stopped_) {
-      return handler(errc::network::cluster_closed);
-    }
-    if (background_open_started_) {
-      CB_LOG_DEBUG("Background open already started for cluster, id: \"{}\"", id_);
-      return handler({});
-    }
-    if (origin.get_nodes().empty()) {
-      stopped_ = true;
-      work_.reset();
-      return handler(errc::common::invalid_argument);
+      return resume(errc::network::cluster_closed);
     }
+    auto entry = std::make_shared<deferred_request>();
+    entry->resume = std::move(resume);
+    entry->deadline = std::make_unique<asio::steady_timer>(ctx_, deadline);
+    entry->deadline->async_wait([entry](std::error_code ec) {
+      if (ec != asio::error::operation_aborted) {
+        entry->complete(errc::common::unambiguous_timeout);
+      }
+    });
+    // Held weakly: `start` may keep this completion after the wait ends, as a bucket's queue of
+    // configuration waiters does. The pending timer keeps the entry alive until it completes.
+    std::forward<Start>(start)(
+      [self = shared_from_this(),
+       weak_entry = std::weak_ptr<deferred_request>(entry)](std::error_code ec) {
+        auto entry = weak_entry.lock();
+        if (!entry) {
+          return;
+        }
+        if (self->ctx_.get_executor().running_in_this_thread()) {
+          return entry->complete(ec);
+        }
+        // A wait that started just before close() can report after the IO thread has stopped, and
+        // a stopped io_context keeps what is posted to it without running it.
+        if (self->stopped_) {
+          entry->complete_off_io_thread(ec);
+          // The armed timer would keep the io_context busy until the deadline; dropped if it
+          // stopped.
+          return asio::post(self->ctx_, [entry] {
+            entry->deadline->cancel();
+          });
+        }
+        asio::post(self->ctx_, [entry, ec] {
+          entry->complete(ec);
+        });
+      });
+  }
 
-    origin_ = std::move(origin);
-    CB_LOG_DEBUG(R"(open cluster in background, id: "{}", core version: "{}", {})",
-                 id_,
-                 couchbase::core::meta::sdk_semver(),
-                 origin_.to_json());
-    setup_observability();
-    session_manager_->set_dispatch_timeout(origin_.options().dispatch_timeout);
-    // at this point we will infinitely try to connect
-    if (origin_.options().enable_dns_srv) {
-      do_background_dns_srv_open();
-    } else {
-      do_background_open();
-    }
-    background_open_started_ = true;
-    return handler({});
+  void open_bucket_until(const std::string& bucket_name,
+                         std::chrono::steady_clock::time_point deadline,
+                         utils::movable_function<void(std::error_code)>&& handler)
+  {
+    wait_until(deadline, std::move(handler), [&](auto&& done) {
+      open_bucket(bucket_name, std::forward<decltype(done)>(done));
+    });
   }
-#endif
 
   void open_bucket(const std::string& bucket_name,
                    utils::movable_function<void(std::error_code)>&& handler)
@@ -550,6 +813,19 @@ public:
     if (stopped_) {
       return handler(errc::network::cluster_closed);
     }
+    if (is_protostellar()) {
+      // couchbase2 has no bucket bootstrap. Opening one would dial the gateway over MCBP, which it
+      // does not serve, and fail with unambiguous_timeout only at bootstrap_timeout.
+      return handler(errc::common::feature_not_available);
+    }
+    if (defer_until_open([&] {
+          return [self = shared_from_this(), bucket_name, handler = std::move(handler)](
+                   std::error_code /* no deadline */) mutable {
+            self->open_bucket(bucket_name, std::move(handler));
+          };
+        })) {
+      return;
+    }
     std::shared_ptr<bucket> b{};
     {
       const std::scoped_lock lock(buckets_mutex_);
@@ -623,6 +899,8 @@ public:
 
   auto update_credentials(const cluster_credentials& auth) -> core::error
   {
+    // origin_mutex_ as well: while open() bootstraps, the IO thread writes origin_.
+    const std::scoped_lock lock(update_credentials_mutex_, origin_mutex_);
     if (stopped_) {
       return { errc::network::cluster_closed, {} };
     }
@@ -645,8 +923,7 @@ public:
     });
 
     if (auth.requires_tls()) {
-      // Recreate and atomically swap the TLS context, existing sessions should continue to use the
-      // old one.
+      // Recreate and atomically swap the TLS context. KV sessions keep the one they connected with.
       const auto new_ctx = std::make_shared<asio::ssl::context>(asio::ssl::context::tls_client);
       auto ec = configure_tls_context(new_ctx);
       if (ec) {
@@ -655,6 +932,11 @@ public:
         return { ec, {} };
       }
       tls_.set_ctx(new_ctx);
+      // A pooled HTTP connection presents the certificate it was opened with. A password or JWT is
+      // sent with each request.
+      if (auth.uses_certificate()) {
+        session_manager_->retire_sessions();
+      }
     }
 
     if (auth.uses_jwt()) {
@@ -665,14 +947,6 @@ public:
     return {};
   }
 
-  auto origin() const -> std::pair<std::error_code, couchbase::core::origin>
-  {
-    if (stopped_) {
-      return { errc::network::cluster_closed, {} };
-    }
-    return { {}, origin_ };
-  }
-
   template<class Request,
            class Handler,
            typename std::enable_if_t<
@@ -685,7 +959,65 @@ public:
       return handler(request.make_response(
         make_key_value_error_context(errc::network::cluster_closed, request.id), response_type{}));
     }
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+    if (auto component = protostellar_component(); component) {
+      if constexpr (protostellar::component_supports_v<Request>) {
+        execute_protostellar(std::move(request), std::forward<Handler>(handler));
+        return;
+      } else {
+        return handler(request.make_response(
+          make_key_value_error_context(errc::common::feature_not_available, request.id),
+          response_type{}));
+      }
+    }
+#endif
+    auto timeout = request.timeout.value_or(default_timeout_for(service_type::key_value));
+    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. key="{}", timeout={}ms, floor={}ms)",
+          logger::document(request.id),
+          timeout.count(),
+          durability_timeout_floor.count());
+        timeout = durability_timeout_floor;
+      }
+    }
+    execute_until(std::move(request),
+                  std::chrono::steady_clock::now() + timeout,
+                  std::forward<Handler>(handler));
+  }
+
+  // A key-value request's timeout counts from when it was issued: waiting for the bootstrap or for
+  // the bucket to open spends it, and the command gets only what is left. Past `deadline` the
+  // request gets unambiguous_timeout and is not dispatched.
+  template<class Request, class Handler>
+  void execute_until(Request request,
+                     std::chrono::steady_clock::time_point deadline,
+                     Handler&& handler)
+  {
+    using response_type = typename Request::encoded_response_type;
+    if (stopped_) {
+      return handler(request.make_response(
+        make_key_value_error_context(errc::network::cluster_closed, request.id), response_type{}));
+    }
+    auto resume = [&] {
+      return [self = shared_from_this(),
+              deadline,
+              request = std::move(request),
+              handler = std::forward<Handler>(handler)](std::error_code ec) mutable {
+        if (ec) {
+          return handler(
+            request.make_response(make_key_value_error_context(ec, request.id), response_type{}));
+        }
+        self->execute_until(std::move(request), deadline, std::move(handler));
+      };
+    };
+    if (defer_until_open(resume, deadline)) {
+      return;
+    }
     if (auto bucket = find_bucket_by_name(request.id.bucket()); bucket != nullptr) {
+      request.timeout = remaining_until(deadline);
       return bucket->execute(std::move(request), std::forward<Handler>(handler));
     }
     if (request.id.bucket().empty()) {
@@ -693,16 +1025,7 @@ public:
         make_key_value_error_context(errc::common::bucket_not_found, request.id), response_type{}));
     }
     auto bucket_name = request.id.bucket();
-    return open_bucket(bucket_name,
-                       [self = shared_from_this(),
-                        request = std::move(request),
-                        handler = std::forward<Handler>(handler)](std::error_code ec) mutable {
-                         if (ec) {
-                           return handler(request.make_response(
-                             make_key_value_error_context(ec, request.id), response_type{}));
-                         }
-                         return self->execute(std::move(request), std::forward<Handler>(handler));
-                       });
+    open_bucket_until(bucket_name, deadline, resume());
   }
 
   template<class Request,
@@ -716,6 +1039,50 @@ public:
     if (stopped_) {
       return handler(request.make_response({ errc::network::cluster_closed }, response_type{}));
     }
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+    if (auto component = protostellar_component(); component) {
+      if constexpr (component_routes<Request>::value) {
+        // Query/analytics/search/view/management requests carry no retry_context on the request, so
+        // execute_protostellar_http supplies the retry state and re-dispatches a retryable
+        // (service_not_available) response under the same overall-deadline bound as the KV path.
+        execute_protostellar_http(std::move(request), std::forward<Handler>(handler));
+        return;
+      } else {
+        // Remaining management ops over couchbase2 are not wired yet. Reject cleanly rather than
+        // falling through to the MCBP session manager, which is never bootstrapped on this path.
+        return handler(
+          request.make_response({ errc::common::feature_not_available }, response_type{}));
+      }
+    }
+#endif
+    // The request's timeout counts from now, not from the end of the bootstrap.
+    if (const auto deadline = std::chrono::steady_clock::now() +
+                              request.timeout.value_or(default_timeout_for(request.type));
+        defer_until_open(
+          [&] {
+            return [self = shared_from_this(),
+                    deadline,
+                    request = std::move(request),
+                    handler = std::forward<Handler>(handler)](std::error_code ec) mutable {
+              if (ec) {
+                auto response = request.make_response({ ec }, response_type{});
+                if constexpr (has_client_context_id<Request>::value &&
+                              has_client_context_id<decltype(response.ctx)>::value) {
+                  // The caller's id, or a generated one, as a dispatched request carries.
+                  response.ctx.client_context_id = request.client_context_id.has_value()
+                                                     ? *request.client_context_id
+                                                     : uuid::to_string(uuid::random());
+                }
+                return handler(std::move(response));
+              }
+              request.timeout = remaining_until(deadline);
+              self->execute(std::move(request), std::move(handler));
+            };
+          },
+          deadline)) {
+      return;
+    }
+    // cppcheck-suppress knownConditionTrueFalse
     if (!is_feature_supported(
           request, session_manager_->configuration_capabilities(), origin_.options())) {
       return handler(
@@ -737,32 +1104,59 @@ public:
                                             bucket_capability cap,
                                             Handler&& handler)
   {
+    // There is no bucket capability to read over couchbase2, and no MCBP connection to read it
+    // over: open_bucket() below would bootstrap a session against a port the gateway does not
+    // serve, so a request that only wants a capability checked would fail on the check rather
+    // than on what it asked for. The gateway still validates the capability the request depends
+    // on -- history retention needs a magma bucket wherever the request arrives from -- so
+    // routing straight through refuses the same requests, one hop later and in the server's own
+    // words.
+    if (is_protostellar()) {
+      return execute(std::move(request), std::forward<Handler>(handler));
+    }
+    // The waits for the bootstrap and for the bucket's configuration spend the request's timeout;
+    // the request gets what is left. The timed hold comes first: open_bucket() would hold the
+    // request without a deadline, and it would stay queued after timing out.
+    const auto deadline = std::chrono::steady_clock::now() +
+                          request.timeout.value_or(default_timeout_for(request.type));
+    if (defer_until_open(
+          [&] {
+            return [self = shared_from_this(),
+                    deadline,
+                    cap,
+                    request = std::move(request),
+                    handler = std::forward<Handler>(handler)](std::error_code ec) mutable {
+              if (ec) {
+                return handler(request.make_response({ ec }, {}));
+              }
+              request.timeout = remaining_until(deadline);
+              self->execute_with_bucket_capability_check(
+                std::move(request), cap, std::move(handler));
+            };
+          },
+          deadline)) {
+      return;
+    }
     auto bucket_name = request.bucket_name;
-    return open_bucket(
+    return with_bucket_configuration(
       bucket_name,
+      deadline,
       [self = shared_from_this(),
-       bucket_name,
+       deadline,
        cap,
        request = std::move(request),
-       handler = std::forward<Handler>(handler)](std::error_code ec) mutable {
+       handler = std::forward<Handler>(handler)](
+        std::error_code ec, const std::shared_ptr<topology::configuration>& config) mutable {
         if (ec) {
           handler(request.make_response({ ec }, {}));
           return;
         }
-        return self->with_bucket_configuration(
-          bucket_name,
-          [self, cap, request = std::move(request), handler = std::forward<Handler>(handler)](
-            std::error_code ec, const std::shared_ptr<topology::configuration>& config) mutable {
-            if (ec) {
-              handler(request.make_response({ ec }, {}));
-              return;
-            }
-            if (!config->capabilities.has_bucket_capability(cap)) {
-              handler(request.make_response({ errc::common::feature_not_available }, {}));
-              return;
-            }
-            return self->execute(std::move(request), std::forward<Handler>(handler));
-          });
+        if (!config->capabilities.has_bucket_capability(cap)) {
+          handler(request.make_response({ errc::common::feature_not_available }, {}));
+          return;
+        }
+        request.timeout = remaining_until(deadline);
+        return self->execute(std::move(request), std::forward<Handler>(handler));
       });
   }
 
@@ -805,8 +1199,413 @@ public:
     }
   }
 
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+  // couchbase2:// open path: the gateway does the routing, so there is no MCBP config bootstrap.
+  // Build a single gRPC channel + KV component to the first endpoint and report success.
+  void open_protostellar(utils::movable_function<void(std::error_code)>&& handler)
+  {
+    // next_address() dereferences the node iterator; a couchbase2:// string that parsed with no
+    // bootstrap node would make it UB, so fail cleanly instead.
+    if (origin_.get_nodes().empty()) {
+      return handler(errc::common::invalid_argument);
+    }
+    auto [hostname, port] = origin_.next_address();
+    auto endpoint = hostname + ":" + port;
+    // Several nodes reach here from an origin assembled programmatically (set_nodes(), or the
+    // hostname/port constructors), and from a connection string naming more than one host:
+    // parse_connection_string() records that as an error on the connection_string, but no caller
+    // reads that field, so the origin is built with every host regardless. Kept as a log rather
+    // than a rejection: one endpoint is as good as another here, and since the node list is
+    // shuffled unless preserve_bootstrap_nodes_order is set, the message is what says which one
+    // this process picked.
+    if (origin_.get_nodes().size() > 1) {
+      CB_LOG_INFO("[{}]: couchbase2 uses a single gateway endpoint (\"{}\"); the remaining {} "
+                  "node(s) on this origin are ignored (the gateway fronts the cluster).",
+                  id_,
+                  logger::system_data(endpoint),
+                  origin_.get_nodes().size() - 1);
+    }
+
+    // Apply the same Capella safety clamp as the MCBP path (configure_tls_options): force peer
+    // verification against the managed service even if tls_verify=none was requested, and surface
+    // the same warnings. Without this the couchbase2 path would silently allow MITM on Capella.
+    auto options = origin_.options();
+    const auto requested_verify = options.tls_verify;
+    options.tls_verify = effective_tls_verify_mode(requested_verify, is_capella_host(hostname));
+    if (requested_verify == tls_verify_mode::none && options.tls_verify == tls_verify_mode::peer) {
+      CB_LOG_WARNING(R"([{}]: tls_verify=none was requested but "{}" is a Capella endpoint; )"
+                     "enforcing peer verification.",
+                     id_,
+                     logger::system_data(hostname));
+    }
+    // The "verification is disabled" warning is not repeated here: make_channel_credentials() is
+    // the one point every couchbase2 channel passes through and warns there, so it also covers
+    // callers that build a component directly. Only the Capella clamp is specific to this path.
+
+    // Build the channel before starting observability. The two sibling failure paths in open()
+    // (an origin with no nodes) latch stopped_ and release the work guard while nothing has been
+    // started yet; doing the same after setup_observability() would leave its tracer, meter and
+    // reporters running with close() short-circuiting on stopped_ and never stopping them.
+    std::shared_ptr<grpc::Channel> channel;
+    try {
+      channel = protostellar::make_channel(endpoint, options, origin_.credentials());
+    } catch (const std::exception& e) {
+      CB_LOG_ERROR(R"([{}]: failed to establish couchbase2 channel: {})", id_, e.what());
+      stopped_ = true;
+      work_.reset();
+      return handler(errc::common::invalid_argument);
+    }
+    setup_observability();
+    {
+      // Written under the lock for symmetry with close(): the assignment itself happens before any
+      // caller can reach execute() (the open handler has not fired yet), but leaving one access
+      // unguarded is how the invariant gets lost later.
+      const std::scoped_lock lock(protostellar_mutex_);
+      protostellar_ = std::make_shared<protostellar::component>(
+        ctx_,
+        protostellar::component_config{ std::move(channel),
+                                        origin_.credentials(),
+                                        make_component_timeouts(options),
+                                        make_compression_settings(options) });
+    }
+    CB_LOG_INFO(
+      R"(open couchbase2 cluster, id: "{}", endpoint: "{}")", id_, logger::system_data(endpoint));
+    return handler({});
+  }
+#endif
+
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+  // The KV component, or nullptr when this cluster is not a couchbase2 one. Returns a copy under
+  // the lock, in the same shape as find_bucket_by_name(): execute() runs on the caller's thread
+  // while close() resets the member on the io thread, and reading a shared_ptr that another thread
+  // is writing is a data race whatever the refcount does. Holding a copy also keeps the component
+  // alive for the duration of the call that is about to use it.
+  [[nodiscard]] auto protostellar_component() const -> std::shared_ptr<protostellar::component>
+  {
+    const std::scoped_lock lock(protostellar_mutex_);
+    return protostellar_;
+  }
+
+  // Whether the couchbase2 channel is READY. An idle channel is asked to connect, so polling this
+  // also establishes the connection. cluster_closed once the cluster is closed.
+  [[nodiscard]] auto protostellar_channel_ready() const -> std::pair<std::error_code, bool>
+  {
+    const auto component = protostellar_component();
+    if (stopped_ || component == nullptr) {
+      return { errc::network::cluster_closed, false };
+    }
+    const auto& channel = component->channel();
+    auto state = channel->GetState(/* try_to_connect */ true);
+    if (state != GRPC_CHANNEL_READY && state != GRPC_CHANNEL_SHUTDOWN) {
+      // On gRPC builds that progress a connection only under polling, an attempt stalls while no
+      // call is in flight. A wait whose deadline has already passed polls once without blocking.
+      channel->WaitForStateChange(state, std::chrono::system_clock::now());
+      state = channel->GetState(/* try_to_connect */ false);
+    }
+    switch (state) {
+      case GRPC_CHANNEL_READY:
+        return { {}, true };
+      case GRPC_CHANNEL_SHUTDOWN:
+        return { errc::network::cluster_closed, false };
+      default:
+        return { {}, false };
+    }
+  }
+#endif
+
+  // True when the cluster was configured with a couchbase2:// connection string -- a property of
+  // the origin, so it holds from construction and stays true after close(). Compound /
+  // self-dispatching operations (replica reads, legacy durability) check this to reject cleanly
+  // instead of falling through to the MCBP bootstrap path, which does not exist on couchbase2.
+  //
+  // It answers "which transport was configured", never "is the transport usable". Most callers want
+  // exactly the former and reject with feature_not_available, which is a capability statement and
+  // is correct whether the cluster is open or closed. The callers that do need liveness test
+  // stopped_ themselves, or route into a dispatch that re-reads the component under the lock.
+  [[nodiscard]] auto is_protostellar() const -> bool
+  {
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+    return origin_.uses_protostellar();
+#else
+    return false;
+#endif
+  }
+
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+  // Execute a couchbase2 operation through the component with transport-level retry. Retryable
+  // errors (see protostellar::retry_reason_for) consult the request's retry strategy (falling back
+  // to the origin default), and on a positive decision the request is re-issued after a backoff.
+  // Idempotency is enforced by the strategy, so ambiguous mutations are not replayed.
+  //
+  // The deadline is resolved here, before the first attempt, and every attempt is issued against
+  // it. Falling back to the cluster's KV default when the request carries no timeout is what bounds
+  // the loop at all: the public API leaves the per-operation timeout unset unless the caller asks
+  // for one, and the strategy never refuses a retry for service_not_available, so a request issued
+  // with default options against an unavailable gateway would otherwise retry until the process
+  // ended -- never completing, and never reporting an error either.
+  //
+  // Which default applies is resolve_kv_timeout's rule, not a second copy of it: a durable mutation
+  // is bounded by KvDurableTimeout and everything else by the standard KV timeout. It has to be
+  // applied here, because dispatch_protostellar narrows request->timeout on every attempt including
+  // the first -- so the component is always handed an engaged timeout and its own fallback never
+  // selects for a request that arrives through this loop. Resolving with the standard default here
+  // would cap a durable mutation at the budget the durable default exists to replace.
+  template<class Request, class Handler>
+  void execute_protostellar(Request request, Handler&& handler)
+  {
+    // The fallback below is a KV default, so routing anything else here would bound it with a
+    // budget belonging to another service. Non-KV requests carry no retry_context and have their
+    // own path.
+    static_assert(protostellar::component_supports_v<Request>,
+                  "execute_protostellar resolves the key-value timeout");
+    const auto deadline =
+      std::chrono::steady_clock::now() +
+      protostellar::resolve_kv_timeout(request.timeout,
+                                       protostellar::requested_durability(request),
+                                       make_component_timeouts(origin_.options()));
+    // Held by shared_ptr and re-issued from there. The request owns the document body for a
+    // mutation, so copying it to keep a re-issue possible charged every operation on the data plane
+    // for a retry that in normal operation never happens.
+    dispatch_protostellar(
+      std::make_shared<Request>(std::move(request)), std::forward<Handler>(handler), deadline);
+  }
+
+  // One attempt of the above, re-entered from the backoff timer for each retry.
+  template<class Request, class Handler>
+  void dispatch_protostellar(std::shared_ptr<Request> request,
+                             Handler&& handler,
+                             std::chrono::steady_clock::time_point deadline)
+  {
+    // Each attempt gets what is LEFT of the operation's budget rather than a fresh full-length one.
+    // Without this an attempt started just inside the deadline would run for the whole timeout
+    // again, so a retried operation could take roughly twice its nominal budget. Narrowing keeps
+    // the request carrying a duration -- which is all the component accepts -- while making that
+    // duration mean "until the operation's deadline". A non-positive remainder is not
+    // special-cased, and is in fact how the loop ends: the component rejects an exhausted budget
+    // as a timeout instead of dispatching a call with no deadline.
+    request->timeout = std::chrono::duration_cast<std::chrono::milliseconds>(
+      deadline - std::chrono::steady_clock::now());
+    // Re-read through the locked accessor on every attempt: a retry re-enters this
+    // function from a timer, long after the caller checked.
+    auto component = protostellar_component();
+    if (!component) {
+      return handler(
+        request->make_response(make_key_value_error_context(errc::network::cluster_closed,
+                                                            request->id,
+                                                            request->retries.retry_attempts(),
+                                                            request->retries.retry_reasons()),
+                               typename Request::encoded_response_type{}));
+    }
+    component->execute(
+      *request,
+      [self = shared_from_this(), request, handler = std::forward<Handler>(handler), deadline](
+        auto response) mutable {
+        if (auto reason = protostellar::retry_reason_for(protostellar_response_ec(response.ctx));
+            reason.has_value()) {
+          auto strategy = request->retries.strategy()
+                            ? request->retries.strategy()
+                            : self->origin_.options().default_retry_strategy_;
+          if (strategy) {
+            const auto action = strategy->retry_after(request->retries, reason.value());
+            // The wait is capped at the deadline rather than the retry being refused for landing
+            // past it. Refusing would end the operation early on the last attempt's transport
+            // error -- temporary_failure for an unreachable gateway -- while the caller's budget
+            // was still running, so the same condition that times out over the classic transport
+            // would report a different code here. Capping lets the operation use its whole budget
+            // and end on the deadline: the attempt scheduled at it gets a non-positive remainder
+            // above, which the component answers as a timeout carrying the accumulated attempts
+            // and reasons. That is terminal, so the loop cannot spin on it -- retry_reason_for
+            // does not classify a timeout as retryable. Both other implementations of this loop
+            // cap the same way (io/retry_orchestrator.hxx cap_duration, and Java's
+            // RetryOrchestratorProtostellar.capDuration).
+            const auto when =
+              std::min(std::chrono::steady_clock::now() + action.duration(), deadline);
+            if (action.need_to_retry()) {
+              if (self->stopped_) {
+                // A retry was due and will not happen: close() latches stopped_ before it clears
+                // the component, so this completion arrived after the close. The transport error
+                // the next attempt would have replaced is not the caller's answer -- reporting it
+                // says "try again" about a cluster that is gone -- so report the close, as the
+                // re-entry below does once the component is cleared. Gating on a due retry keeps a
+                // terminal response out of this: request_canceled in particular carries the
+                // CXXCBC-909 rule that the statement must not be replayed.
+                return handler(request->make_response(
+                  make_key_value_error_context(errc::network::cluster_closed,
+                                               request->id,
+                                               request->retries.retry_attempts(),
+                                               request->retries.retry_reasons()),
+                  typename Request::encoded_response_type{}));
+              }
+              // Recorded before the re-issue, so the next attempt carries the accumulated count
+              // and the error context it builds reports the retries that preceded it.
+              request->retries.record_retry_attempt(reason.value());
+              auto timer = std::make_shared<asio::steady_timer>(self->ctx_);
+              timer->expires_at(when);
+              timer->async_wait([self,
+                                 request,
+                                 handler = std::move(handler),
+                                 deadline,
+                                 response = std::move(response),
+                                 timer](const std::error_code& timer_ec) mutable {
+                if (timer_ec) {
+                  // Timer cancelled: deliver the last retryable response rather than dropping
+                  // the caller's completion, which would hang it.
+                  handler(std::move(response));
+                  return;
+                }
+                // A cluster closed during the backoff is answered by dispatch_protostellar,
+                // which re-reads the component under the lock and reports cluster_closed. The
+                // last retryable response would instead report a temporary failure, which reads
+                // as "retry later" for a cluster that is gone.
+                self->dispatch_protostellar(std::move(request), std::move(handler), deadline);
+              });
+              return;
+            }
+          }
+        }
+        // A declined retry reports the transport error even when the cluster is closing: the
+        // strategy, not the close, is what ended the operation, and the caller gets the answer a
+        // close-free run would have given. The close is reported only where it is the more specific
+        // answer -- above, where a retry was due and will not happen, and at the top of this
+        // function, where no attempt was made and there is no transport error to report.
+        handler(std::move(response));
+      });
+  }
+
+  template<typename Request>
+  static auto timeout_for(const protostellar::component_timeouts& timeouts)
+    -> std::chrono::milliseconds
+  {
+    if constexpr (std::is_same_v<Request, operations::query_request>) {
+      return timeouts.query;
+    } else if constexpr (std::is_same_v<Request, operations::analytics_request>) {
+      return timeouts.analytics;
+    } else if constexpr (std::is_same_v<Request, operations::search_request>) {
+      return timeouts.search;
+    } else if constexpr (std::is_same_v<Request, operations::document_view_request>) {
+      return timeouts.view;
+    } else {
+      return timeouts.management;
+    }
+  }
+
+  // Retry for non-KV couchbase2 operations (query/analytics/search/view/management). These
+  // HTTP-shaped requests carry no retry_context, so the retry state lives here: a heap
+  // retry_context threaded across re-dispatches, mutated in place so the strategy sees the
+  // accumulated attempts. In practice only service_not_available (a transport UNAVAILABLE -- the
+  // call never reached a server) arises on this path: retry_reason_for is shared with the KV path
+  // and can also report key_value_locked, which no query/analytics/search/view/management response
+  // produces. The strategy permits service_not_available for non-idempotent ops too, so the fixed
+  // retry_context<false> idempotency is not load-bearing. The strategy is the origin
+  // default (these requests have no per-request override). Like the KV path, retries are bounded by
+  // the strategy and by an overall deadline stamped before the first attempt: the request's own
+  // timeout when it carries one, the per-service default otherwise. Every attempt is therefore
+  // bounded, including the first.
+  //
+  // This overload stamps that deadline; the one below carries it. Taking a plain time_point rather
+  // than an optional keeps "no deadline yet" unrepresentable once the loop has started.
+  template<class Request, class Handler>
+  void execute_protostellar_http(Request request, Handler&& handler)
+  {
+    const auto default_timeout = timeout_for<Request>(make_component_timeouts(origin_.options()));
+    const auto deadline =
+      std::chrono::steady_clock::now() + request.timeout.value_or(default_timeout);
+    execute_protostellar_http(
+      std::move(request),
+      std::forward<Handler>(handler),
+      std::make_shared<io::retry_context<false>>(origin_.options().default_retry_strategy_),
+      deadline);
+  }
+
+  template<class Request, class Handler>
+  void execute_protostellar_http(Request request,
+                                 Handler&& handler,
+                                 std::shared_ptr<io::retry_context<false>> retries,
+                                 std::chrono::steady_clock::time_point deadline)
+  {
+    // Re-read through the locked accessor on every attempt: a retry re-enters this
+    // function from a timer, long after the caller checked.
+    auto component = protostellar_component();
+    if (!component) {
+      auto response = request.make_response({ errc::network::cluster_closed },
+                                            typename Request::encoded_response_type{});
+      // A cluster closed mid-backoff reaches here with attempts already behind it, and dropping
+      // them would report the operation as never retried.
+      response.ctx.retry_attempts = retries->retry_attempts();
+      response.ctx.retry_reasons = retries->retry_reasons();
+      return handler(std::move(response));
+    }
+
+    auto request_ptr = std::make_shared<Request>(std::move(request));
+    component->execute(
+      *request_ptr,
+      [self = shared_from_this(),
+       request_ptr,
+       handler = std::forward<Handler>(handler),
+       retries,
+       deadline](auto response) mutable {
+        if (auto reason = protostellar::retry_reason_for(protostellar_response_ec(response.ctx));
+            reason.has_value()) {
+          if (retries->strategy()) {
+            const auto action = retries->strategy()->retry_after(*retries, reason.value());
+            const auto when =
+              std::min(std::chrono::steady_clock::now() + action.duration(), deadline);
+            if (action.need_to_retry()) {
+              if (self->stopped_) {
+                // See dispatch_protostellar(): a retry the close will not let happen reports the
+                // close, not the error the next attempt would have replaced.
+                auto closed = request_ptr->make_response({ errc::network::cluster_closed },
+                                                         typename Request::encoded_response_type{});
+                closed.ctx.retry_attempts = retries->retry_attempts();
+                closed.ctx.retry_reasons = retries->retry_reasons();
+                return handler(std::move(closed));
+              }
+              retries->record_retry_attempt(reason.value());
+              auto timer = std::make_shared<asio::steady_timer>(self->ctx_);
+              timer->expires_at(when);
+              timer->async_wait([self,
+                                 request_ptr = std::move(request_ptr),
+                                 handler = std::move(handler),
+                                 retries,
+                                 deadline,
+                                 response = std::move(response),
+                                 timer](const std::error_code& timer_ec) mutable {
+                if (timer_ec) {
+                  // Timer cancelled: deliver the last response rather than dropping the caller's
+                  // completion, which would hang it.
+                  response.ctx.retry_attempts = retries->retry_attempts();
+                  response.ctx.retry_reasons = retries->retry_reasons();
+                  handler(std::move(response));
+                  return;
+                }
+                // A cluster closed during the backoff is answered by the re-entry below, which
+                // re-reads the component under the lock and reports cluster_closed -- the same
+                // answer a caller gets when the cluster is already closed on arrival.
+                auto next_request = *request_ptr;
+                next_request.timeout = std::chrono::duration_cast<std::chrono::milliseconds>(
+                  deadline - std::chrono::steady_clock::now());
+                self->execute_protostellar_http(
+                  std::move(next_request), std::move(handler), retries, deadline);
+              });
+              return;
+            }
+          }
+        }
+        // As in dispatch_protostellar(): a declined retry reports the transport error, because the
+        // strategy rather than the close is what ended the operation.
+        response.ctx.retry_attempts = retries->retry_attempts();
+        response.ctx.retry_reasons = retries->retry_reasons();
+        handler(std::move(response));
+      });
+  }
+#endif
+
   void do_open(utils::movable_function<void(std::error_code)> handler)
   {
+    // After a DNS SRV lookup, close() may already have run; a bootstrap now would outlive it.
+    if (stopped_) {
+      return handler(errc::network::cluster_closed);
+    }
     // Warn users if idle_http_connection_timeout is too close to server idle timeouts
     if (origin_.options().idle_http_connection_timeout > std::chrono::milliseconds(4'500)) {
       CB_LOG_INFO("[{}]: The SDK may produce trivial warnings due to the idle HTTP connection "
@@ -841,7 +1640,16 @@ public:
 
     if (origin_.options().enable_tls) {
       const auto ctx = tls_.get_ctx();
-      auto ec = configure_tls_context(ctx);
+      std::error_code ec{};
+      {
+        // configure_tls_context() reads the credentials, which a forked child's
+        // set_authenticator() can rewrite while its reopen runs.
+        const std::scoped_lock lock(update_credentials_mutex_);
+        ec = configure_tls_context(ctx);
+        if (!ec) {
+          session_ = io::mcbp_session(id_, {}, ctx_, tls_, origin_, dns_srv_tracker_);
+        }
+      }
       if (ec) {
 #ifdef __clang_analyzer__
         // TODO(CXXCBC-549): clang-tidy-19 reports potential memory leak here
@@ -851,13 +1659,14 @@ public:
           return handler(ec);
         });
       }
-      session_ = io::mcbp_session(id_, {}, ctx_, tls_, origin_, dns_srv_tracker_);
     } else {
+      const std::scoped_lock lock(update_credentials_mutex_);
       session_ = io::mcbp_session(id_, {}, ctx_, origin_, dns_srv_tracker_);
     }
     session_->bootstrap([self = shared_from_this(), handler = std::move(handler)](
                           std::error_code ec, const topology::configuration& config) mutable {
       if (!ec) {
+        std::unique_lock origin_lock(self->origin_mutex_);
         if (self->origin_.options().network == "auto") {
           self->origin_.options().network =
             config.select_network(self->session_->bootstrap_hostname());
@@ -871,208 +1680,44 @@ public:
                         self->origin_.options().network);
           }
         }
-        if (self->origin_.options().network != "default") {
-          self->origin_.set_nodes_from_config(config);
-          CB_LOG_INFO(
-            "replace list of bootstrap nodes with addresses of alternative network \"{}\": [{}]",
-            self->origin_.options().network,
-            utils::join_strings(self->origin_.get_nodes(), ","));
-        }
-        // FIXME(SA): fix the session manager to receive initial configuration and cluster-wide
-        // session to poll for updates like the bucket does. Or just subscribe before the bootstrap.
-        self->session_manager_->set_configuration(config, self->origin_.options());
-        self->session_->on_configuration_update(self->session_manager_);
-        self->session_->on_configuration_update(self->app_telemetry_reporter_);
-        self->session_->on_configuration_update(self->cluster_label_listener_);
-        self->app_telemetry_reporter_->update_config(config);
-        self->cluster_label_listener_->update_config(config);
-        self->session_->on_stop([self]() {
-          if (self->session_) {
-            self->session_.reset();
-          }
-        });
-      }
-      if (ec) {
-#ifdef __clang_analyzer__
-        // TODO(CXXCBC-549): clang-tidy-19 reports potential memory leak here
-        [[clang::suppress]]
-#endif
-        return self->close([ec, handler = std::move(handler)]() mutable {
-          handler(ec);
-        });
-      }
-      handler(ec);
-    });
-  }
-
-#ifdef COUCHBASE_CXX_CLIENT_COLUMNAR
-  void do_background_open()
-  {
-    // TODO(JC): retries on more failures?  Right now only retry if load_verify_file() fails...
-
-    // Disables TLS v1.2 which should be okay cloud/columnar default.
-    auto ctx = tls_.get_ctx();
-    configure_tls_options(true, ctx);
-    if (origin_.options().security_options.trust_only_capella) {
-      std::error_code ec{};
-      CB_LOG_DEBUG(R"([{}]: use Capella CA for TLS verify)", id_);
-      ctx->add_certificate_authority(
-        asio::const_buffer(couchbase::core::default_ca::capellaCaCert,
-                           strlen(couchbase::core::default_ca::capellaCaCert)),
-        ec);
-      if (ec) {
-        CB_LOG_WARNING("[{}]: unable to load Capella CAs: {}", id_, ec.message());
-        // we don't consider this fatal and try to continue without it
-      }
-    } else if (origin_.options().security_options.trust_only_pem_file ||
-               origin_.options().security_options.trust_only_pem_string) {
-      if (origin_.options().trust_certificate.empty() /* No CA certificate (or other SDK-specific
-                                                         trust source) is specified */
-          && origin_.options()
-               .trust_certificate_value.empty() /* and certificate value has not been specified */
-          && origin_.options().tls_verify !=
-               tls_verify_mode::none /* The user did not disable all TLS verification */) {
-        CB_LOG_WARNING("[{}] When TLS is enabled, the cluster options must specify certificate(s) "
-                       "to trust or ensure that they are "
-                       "available in system CA store.",
-                       id_);
-      }
-      std::error_code ec{};
-      // load only the explicit certificate
-      // system and default capella certificates are not loaded
-      if (!origin_.options().trust_certificate_value.empty()) {
-        CB_LOG_DEBUG(R"([{}]: use TLS certificate passed through via options object)", id_);
-        ctx->add_certificate_authority(
-          asio::const_buffer(origin_.options().trust_certificate_value.data(),
-                             origin_.options().trust_certificate_value.size()),
-          ec);
-        if (ec) {
-          CB_LOG_WARNING(
-            "[{}]: unable to load CA passed via options object: {}", id_, ec.message());
-        }
-      }
-      if (!origin_.options().trust_certificate.empty()) {
-        CB_LOG_DEBUG(
-          R"([{}]: use TLS verify file: "{}")", id_, origin_.options().trust_certificate);
-        ctx->load_verify_file(origin_.options().trust_certificate, ec);
-        if (ec) {
-          CB_LOG_ERROR("[{}]: unable to load verify file \"{}\": {}",
-                       id_,
-                       origin_.options().trust_certificate,
-                       ec.message());
-          auto backoff = std::chrono::milliseconds(500);
-          CB_LOG_DEBUG(
-            "[{}] waiting for {}ms before retrying TLS verify file.", id_, backoff.count());
-          backoff_then_retry(backoff, [self = shared_from_this()]() {
-            self->do_background_open();
-          });
-        }
+        if (self->origin_.options().network != "default") {
+          self->origin_.set_nodes_from_config(config);
+          CB_LOG_INFO(
+            "replace list of bootstrap nodes with addresses of alternative network \"{}\": [{}]",
+            self->origin_.options().network,
+            logger::system_data_list(
+              self->origin_.get_node_addresses(), logger::list_entries::quoted, ","));
+        }
+        origin_lock.unlock();
+        // FIXME(SA): fix the session manager to receive initial configuration and cluster-wide
+        // session to poll for updates like the bucket does. Or just subscribe before the bootstrap.
+        self->session_manager_->set_configuration(config, self->origin_.options());
+        self->session_->on_configuration_update(self->session_manager_);
+        self->session_->on_configuration_update(self->app_telemetry_reporter_);
+        self->session_->on_configuration_update(self->cluster_label_listener_);
+        self->app_telemetry_reporter_->update_config(config);
+        self->cluster_label_listener_->update_config(config);
+        self->session_->on_stop([self]() {
+          if (self->session_) {
+            self->session_.reset();
+          }
+        });
       }
-    } else if (origin_.options().security_options.trust_only_platform) {
-      // TODO(CXXCBC-548): security_options updates (use Mozilla certs?)
-      CB_LOG_DEBUG(R"([{}]: use default CA for TLS verify)", id_);
-      std::error_code ec{};
-      // load system certificates
-      ctx->set_default_verify_paths(ec);
       if (ec) {
-        CB_LOG_WARNING(R"([{}]: failed to load system CAs: {})", id_, ec.message());
-      }
-    } else if (!origin_.options().security_options.trust_only_certificates.empty()) {
-      std::error_code ec{};
-      CB_LOG_DEBUG("[{}]: loading {} user provided CA certificates.",
-                   id_,
-                   origin_.options().security_options.trust_only_certificates.size());
-      for (const auto& cert : origin_.options().security_options.trust_only_certificates) {
-        ctx->add_certificate_authority(asio::const_buffer(cert.data(), cert.size()), ec);
-        if (ec) {
-          CB_LOG_WARNING("[{}]: unable to load CA: {}", id_, ec.message());
-        }
+#ifdef __clang_analyzer__
+        // TODO(CXXCBC-549): clang-tidy-19 reports potential memory leak here
+        [[clang::suppress]]
+#endif
+        return self->close([ec, handler = std::move(handler)]() mutable {
+          handler(ec);
+        });
       }
-    }
-    // TODO(CXXCBC-548): security_options updates (support cipher suites)
-    // if (!origin_.options().security_options.cipher_suites.empty()) {
-    // }
-    config_tracker_ = std::make_shared<couchbase::core::io::cluster_config_tracker>(
-      id_, origin_, ctx_, tls_, dns_srv_tracker_);
-    config_tracker_->register_bootstrap_notification_subscriber(session_manager_);
-    create_cluster_sessions();
-  }
-
-  void backoff_then_retry(std::chrono::milliseconds backoff,
-                          utils::movable_function<void()> callback)
-  {
-    retry_backoff_.expires_after(backoff);
-    retry_backoff_.async_wait(
-      [self = shared_from_this(), cb = std::move(callback)](std::error_code ec) {
-        if (ec == asio::error::operation_aborted || self->stopped_) {
-          return;
-        }
-        if (ec) {
-          CB_LOG_WARNING("[{}] Retry callback received error ec={}.", self->id_, ec.message());
-        }
-        cb();
-      });
-  }
-
-  void do_background_dns_srv_open()
-  {
-    std::string hostname;
-    std::string port;
-    std::tie(hostname, port) = origin_.next_address();
-    dns_srv_tracker_ = std::make_shared<impl::dns_srv_tracker>(
-      ctx_, hostname, origin_.options().dns_config, origin_.options().enable_tls);
-    return asio::post(asio::bind_executor(
-      ctx_, [self = shared_from_this(), hostname = std::move(hostname)]() mutable {
-        return self->dns_srv_tracker_->get_srv_nodes(
-          [self, hostname = std::move(hostname)](origin::node_list nodes,
-                                                 std::error_code ec) mutable {
-            if (ec) {
-              auto backoff = std::chrono::milliseconds(500);
-              self->session_manager_->notify_bootstrap_error({ ec, ec.message(), hostname, {} });
-              CB_LOG_DEBUG(
-                "[{}] waiting for {}ms before retrying DNS query.", self->id_, backoff.count());
-              self->backoff_then_retry(backoff, [self]() {
-                self->do_background_dns_srv_open();
-              });
-              return;
-            }
-            if (!nodes.empty()) {
-              self->origin_.set_nodes(std::move(nodes));
-              CB_LOG_INFO(
-                "[{}] Replace list of bootstrap nodes with addresses from DNS SRV of \"{}\": [{}]",
-                self->id_,
-                hostname,
-                utils::join_strings(self->origin_.get_nodes(), ", "));
-            }
-            return self->do_background_open();
-          });
-      }));
-  }
-
-  void create_cluster_sessions()
-  {
-    config_tracker_->create_sessions(
-      [self = shared_from_this()](std::error_code ec,
-                                  const topology::configuration& cfg,
-                                  const cluster_options& options) mutable {
-        if (ec) {
-          auto backoff = std::chrono::milliseconds(500);
-          CB_LOG_DEBUG("[{}] Waiting for {}ms before retrying to create cluster sessions.",
-                       self->id_,
-                       backoff.count());
-          self->backoff_then_retry(backoff, [self]() {
-            self->create_cluster_sessions();
-          });
-        } else {
-          self->session_manager_->set_configuration(cfg, options);
-          self->config_tracker_->on_configuration_update(self->session_manager_);
-          self->config_tracker_->on_configuration_update(self->app_telemetry_reporter_);
-          self->app_telemetry_reporter_->update_config(cfg);
-          self->config_tracker_->register_state_listener();
-        }
-      });
+      // After the open handler, so a held request sees what the handler set up inline, such as the
+      // transactions connect() creates when no metadata collection is configured.
+      handler(ec);
+      self->run_deferred_until_open();
+    });
   }
-#endif
 
   void with_bucket_configuration(
     const std::string& bucket_name,
@@ -1089,6 +1734,13 @@ public:
       bucket_name,
       [self = shared_from_this(), bucket_name, handler = std::move(handler)](auto ec) mutable {
         if (ec) {
+          // If the cluster was torn down while this open_bucket was parked in the bootstrap window,
+          // the bucket bootstrap is aborted with request_canceled. Surface that to the caller as
+          // cluster_closed so an in-flight operation parked here (e.g. a scan) observes the
+          // cluster-close contract rather than a bare cancellation.
+          if (self->stopped_) {
+            return handler(errc::network::cluster_closed, nullptr);
+          }
           return handler(ec, nullptr);
         }
 
@@ -1099,6 +1751,32 @@ public:
       });
   }
 
+  // with_bucket_configuration(), or unambiguous_timeout with no configuration once `deadline`
+  // passes.
+  void with_bucket_configuration(
+    const std::string& bucket_name,
+    std::chrono::steady_clock::time_point deadline,
+    utils::movable_function<void(std::error_code, std::shared_ptr<topology::configuration>)>&&
+      handler)
+  {
+    // Written before the completion is dispatched, and read only after it ran.
+    auto config = std::make_shared<std::shared_ptr<topology::configuration>>();
+    wait_until(
+      deadline,
+      [config, handler = std::move(handler)](std::error_code ec) mutable {
+        handler(ec, ec ? nullptr : std::move(*config));
+      },
+      [&](auto&& done) {
+        with_bucket_configuration(
+          bucket_name,
+          [config, done = std::forward<decltype(done)>(done)](
+            std::error_code ec, std::shared_ptr<topology::configuration> c) mutable {
+            *config = std::move(c);
+            done(ec);
+          });
+      });
+  }
+
   void ping(std::optional<std::string> report_id,
             std::optional<std::string> bucket_name,
             std::set<service_type> services,
@@ -1108,7 +1786,7 @@ public:
     if (!report_id) {
       report_id = std::make_optional(uuid::to_string(uuid::random()));
     }
-    if (stopped_) {
+    if (stopped_ || is_protostellar()) {
       return handler({ report_id.value(), meta::sdk_id() });
     }
     if (services.empty()) {
@@ -1128,20 +1806,44 @@ public:
        handler = std::move(handler)]() mutable {
         auto collector =
           std::make_shared<ping_collector_impl>(report_id.value(), std::move(handler));
+        // Held until every endpoint this ping covers has taken a reporter. This prevents returning
+        // early when the number of in-flight pings momentarily drops to 0.
+        auto dispatch = collector->begin_dispatch();
         if (bucket_name) {
           if (services.find(service_type::key_value) != services.end()) {
             if (auto bucket = cluster->find_bucket_by_name(bucket_name.value()); bucket) {
-              return bucket->ping(collector, timeout);
-            }
-            cluster->open_bucket(
-              bucket_name.value(), [collector, cluster, bucket_name, timeout](std::error_code ec) {
-                if (!ec) {
-                  if (auto bucket = cluster->find_bucket_by_name(bucket_name.value()); bucket) {
-                    return bucket->ping(collector, timeout);
+              bucket->ping(collector, timeout);
+            } else {
+              // Capture a weak_ptr, not a strong cluster: open_bucket parks this callback in the
+              // bucket-bootstrap queue, which close() does not drain. A strong self-capture would
+              // form a cluster<->parked-callback cycle that pins the ping collector past cluster
+              // close, so its destructor -- the backstop that reports the ping result -- would
+              // never run and the caller would hang. With a weak capture the callback is released
+              // when the cluster is torn down, the collector is destroyed, and its destructor
+              // delivers the report.
+              //
+              // The dispatch scope rides along so that the KV sessions this callback adds are
+              // still covered by it.
+              cluster->open_bucket(
+                bucket_name.value(),
+                [collector, dispatch, weak = std::weak_ptr(cluster), bucket_name, timeout](
+                  std::error_code ec) {
+                  if (!ec) {
+                    if (auto cluster = weak.lock()) {
+                      if (auto bucket = cluster->find_bucket_by_name(bucket_name.value()); bucket) {
+                        return bucket->ping(collector, timeout);
+                      }
+                    }
                   }
-                }
-              });
+                });
+            }
           }
+          // Query, search, analytics, management, eventing and views are cluster-level services,
+          // not bucket-scoped. Ping them through the session manager just like the no-bucket path
+          // so a bucket-scoped ping -- and therefore bucket::wait_until_ready() -- reports the
+          // non-KV services too, rather than only key/value. The session manager pings only the
+          // HTTP services it owns and ignores key_value in the requested set.
+          cluster->session_manager_->ping(services, timeout, collector);
         } else {
           if (services.find(service_type::key_value) != services.end()) {
             if (cluster->session_) {
@@ -1162,7 +1864,7 @@ public:
     if (!report_id) {
       report_id = std::make_optional(uuid::to_string(uuid::random()));
     }
-    if (stopped_) {
+    if (stopped_ || is_protostellar()) {
       return handler({ report_id.value(), couchbase::core::meta::sdk_id() });
     }
     asio::post(asio::bind_executor(
@@ -1179,6 +1881,27 @@ public:
       }));
   }
 
+  // IMPORTANT — do not std::move observability members out of *self* below.
+  //
+  // The public-API cluster::notify_fork(fork_event::child) in
+  // core/impl/public_cluster.cxx replaces the outer cluster_impl and drops
+  // the old one; the old impl's destructor calls do_close() which lands
+  // here. But user code that acquired a bucket/collection *before* the
+  // fork holds its own copy of core::cluster — and core::cluster is a
+  // shared_ptr<cluster_impl> wrapper — so the inner cluster_impl's
+  // refcount stays > 0 and this object survives close().
+  //
+  // Anything moved out of `self->X_` becomes silently empty to those
+  // still-live references on the next operation. tracer() and meter()
+  // accessors return the member directly without checking stopped_, so an
+  // empty shared_ptr there gets converted to an empty weak_ptr in
+  // observability_recorder and then dereferenced as `this=nullptr` inside
+  // tracer_wrapper::create_span. Same shape for the rest of the
+  // observability/telemetry/orphan set.
+  //
+  // Members whose accessor already gates on stopped_ (e.g. session_manager_
+  // via http_session_manager()) are safe to move out and intentionally
+  // remain that way — callers there get a clean errc::network::cluster_closed.
   void close(utils::movable_function<void()>&& handler)
   {
     if (stopped_) {
@@ -1187,17 +1910,22 @@ public:
     stopped_ = true;
     asio::post(asio::bind_executor(
       ctx_, [self = shared_from_this(), handler = std::move(handler)]() mutable {
-        if (auto session = std::move(self->session_); session) {
-          session->stop(retry_reason::do_not_retry);
+        // Re-issued after stopped_ is set, so each deferred request completes with cluster_closed.
+        self->run_deferred_until_open();
+        if (auto open_handler = self->take_dns_srv_open_handler(); open_handler) {
+          open_handler(errc::network::cluster_closed);
         }
-#ifdef COUCHBASE_CXX_CLIENT_COLUMNAR
-        if (self->config_tracker_) {
-          self->config_tracker_->close();
-          self->config_tracker_->unregister_bootstrap_notification_subscriber(
-            self->session_manager_);
+        std::optional<io::mcbp_session> session{};
+        std::shared_ptr<io::http_session_manager> session_manager{};
+        {
+          // update_credentials() uses both from the caller's thread.
+          const std::scoped_lock lock(self->update_credentials_mutex_);
+          session = std::move(self->session_);
+          session_manager = std::move(self->session_manager_);
+        }
+        if (session) {
+          session->stop(retry_reason::do_not_retry);
         }
-        self->retry_backoff_.cancel();
-#endif
 
         std::map<std::string, std::shared_ptr<bucket>> buckets{};
         {
@@ -1207,29 +1935,86 @@ public:
         for (const auto& [_, bucket] : buckets) {
           bucket->close();
         }
-        if (const auto session_manager = std::move(self->session_manager_); session_manager) {
-          session_manager->close();
-        }
-        self->work_.reset();
-        if (const auto tracer = std::move(self->tracer_); tracer) {
-          tracer->stop();
-        }
-        if (const auto meter = std::move(self->meter_); meter) {
-          meter->stop();
-        }
-        if (const auto meter = std::move(self->app_telemetry_meter_); meter) {
-          meter->disable();
-        }
-        if (const auto reporter = std::move(self->app_telemetry_reporter_); reporter) {
-          reporter->stop();
-        }
-        if (const auto orphan_reporter = std::move(self->orphan_reporter_); orphan_reporter) {
-          orphan_reporter->stop();
+        // The rest of the teardown waits until every HTTP session is stopped and holds no
+        // read_some() call. The caller may stop the io_context as soon as `handler` runs, and an
+        // HTTP session whose stop is still queued then is never torn down.
+        if (session_manager) {
+          return session_manager->close([self, handler = std::move(handler)]() mutable {
+            self->finish_close(std::move(handler));
+          });
         }
-        handler();
+        self->finish_close(std::move(handler));
       }));
   }
 
+  // The part of close() that runs once every HTTP session is stopped and holds no read_some() call.
+  void finish_close(utils::movable_function<void()>&& handler)
+  {
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+    {
+      // Drop the reference under the lock, but destroy the component outside it: ~component
+      // drains in-flight gRPC calls, and holding protostellar_mutex_ across that would block
+      // every concurrent execute() on the io thread for the duration of the drain.
+      std::shared_ptr<protostellar::component> component;
+      {
+        const std::scoped_lock lock(protostellar_mutex_);
+        component = std::move(protostellar_);
+        protostellar_.reset();
+      }
+    }
+#endif
+    // Hooks run before the handler: the caller may stop the io_context as soon as it runs, and an
+    // operation waiting on a timer would then never complete.
+    decltype(close_hooks_) hooks{};
+    {
+      const std::scoped_lock lock(close_hooks_mutex_);
+      hooks = std::move(close_hooks_);
+      close_hooks_.clear();
+    }
+    for (auto& [owner, hook] : hooks) {
+      if (!owner.expired()) {
+        hook();
+      }
+    }
+    work_.reset();
+    // Observability members: stop in place, do NOT std::move. See the
+    // comment above close() for why this matters across fork(child).
+    if (tracer_) {
+      tracer_->stop();
+    }
+    if (meter_) {
+      meter_->stop();
+    }
+    if (app_telemetry_meter_) {
+      app_telemetry_meter_->disable();
+    }
+    if (app_telemetry_reporter_) {
+      app_telemetry_reporter_->stop();
+    }
+    if (orphan_reporter_) {
+      orphan_reporter_->stop();
+    }
+    handler();
+  }
+
+  auto add_close_hook(std::weak_ptr<void> owner, utils::movable_function<void()>&& hook) -> bool
+  {
+    const std::scoped_lock lock(close_hooks_mutex_);
+    // close() sets stopped_ before it posts the teardown, and finish_close() takes the hooks under
+    // this mutex, so a hook that passes this check is called.
+    if (stopped_) {
+      return false;
+    }
+    close_hooks_.erase(std::remove_if(close_hooks_.begin(),
+                                      close_hooks_.end(),
+                                      [](const auto& entry) {
+                                        return entry.first.expired();
+                                      }),
+                       close_hooks_.end());
+    close_hooks_.emplace_back(std::move(owner), std::move(hook));
+    return true;
+  }
+
   auto direct_dispatch(const std::string& bucket_name,
                        std::shared_ptr<couchbase::core::mcbp::queue_request> req) -> std::error_code
   {
@@ -1249,7 +2034,11 @@ public:
         if (ec) {
           return req->cancel(ec);
         }
-        self->direct_dispatch(bucket_name, std::move(req));
+        // open_bucket()'s caller has already returned, so nothing reads this
+        // error code and nothing else completes the request.
+        if (const auto rc = self->direct_dispatch(bucket_name, req); rc) {
+          req->try_callback({}, rc);
+        }
       });
     return {};
   }
@@ -1274,11 +2063,99 @@ public:
                   if (ec) {
                     return req->cancel(ec);
                   }
-                  self->direct_re_queue(bucket_name, std::move(req), is_retry);
+                  // As in direct_dispatch(): this error code has no other
+                  // reader. Every error the bucket-level re-queue returns has
+                  // already completed the request, so this is a backstop for a
+                  // future path that does not -- try_callback() is idempotent.
+                  if (const auto rc = self->direct_re_queue(bucket_name, req, is_retry); rc) {
+                    req->try_callback({}, rc);
+                  }
                 });
     return {};
   }
 
+  // A request issued while open() bootstraps would read origin_ and session_, which the IO thread
+  // writes until the bootstrap ends. While that window is open, the request made by `make_resume`
+  // is held and this returns true. `make_resume` is called only then, so a request that is not
+  // held is not moved from.
+  //
+  // The held request resumes exactly once: with no error when run_deferred_until_open() closes the
+  // window, or with unambiguous_timeout when `deadline` passes first.
+  template<typename MakeResume>
+  auto defer_until_open(MakeResume&& make_resume,
+                        std::optional<std::chrono::steady_clock::time_point> deadline = {}) -> bool
+  {
+    const std::scoped_lock lock(deferred_until_open_mutex_);
+    if (!opening_) {
+      return false;
+    }
+    auto entry = std::make_shared<deferred_request>();
+    entry->resume = std::forward<MakeResume>(make_resume)();
+    if (deadline) {
+      entry->deadline = std::make_unique<asio::steady_timer>(ctx_, deadline.value());
+      entry->deadline->async_wait([weak_self = weak_from_this(), entry](std::error_code ec) {
+        if (ec == asio::error::operation_aborted) {
+          return;
+        }
+        // Removed now, or each request that times out during a slow bootstrap stays queued
+        // until the bootstrap ends.
+        if (auto self = weak_self.lock()) {
+          const std::scoped_lock lock(self->deferred_until_open_mutex_);
+          if (entry->queued) {
+            self->deferred_until_open_.erase(*entry->queued);
+            entry->queued.reset();
+          }
+        }
+        entry->complete(errc::common::unambiguous_timeout);
+      });
+    }
+    entry->queued = deferred_until_open_.insert(deferred_until_open_.end(), entry);
+    return true;
+  }
+
+  // Closes the bootstrap window and resumes what it held. Runs on the IO thread, at the end of a
+  // successful bootstrap or at the start of close(); a failed bootstrap reaches close() first.
+  void run_deferred_until_open()
+  {
+    std::list<std::shared_ptr<deferred_request>> deferred{};
+    {
+      const std::scoped_lock lock(deferred_until_open_mutex_);
+      opening_ = false;
+      std::swap(deferred, deferred_until_open_);
+      for (const auto& entry : deferred) {
+        entry->queued.reset();
+      }
+    }
+    for (const auto& entry : deferred) {
+      entry->complete({});
+    }
+  }
+
+  // A DNS SRV open's handler, taken by whichever of the lookup and close() finishes first.
+  auto take_dns_srv_open_handler() -> utils::movable_function<void(std::error_code)>
+  {
+    const std::scoped_lock lock(dns_srv_open_handler_mutex_);
+    auto handler = std::move(dns_srv_open_handler_);
+    dns_srv_open_handler_ = nullptr;
+    return handler;
+  }
+
+  // The timeouts are not among the fields the bootstrap rewrites, so no lock is needed.
+  [[nodiscard]] auto default_timeout_for(service_type type) const -> std::chrono::milliseconds
+  {
+    return origin_.options().default_timeout_for(type);
+  }
+
+  // origin_ copied under origin_mutex_: the IO thread rewrites it while open() bootstraps.
+  auto origin() const -> std::pair<std::error_code, couchbase::core::origin>
+  {
+    if (stopped_) {
+      return { errc::network::cluster_closed, {} };
+    }
+    const std::scoped_lock lock(origin_mutex_);
+    return { {}, origin_ };
+  }
+
   auto http_session_manager()
     -> std::pair<std::error_code, std::shared_ptr<io::http_session_manager>>
   {
@@ -1304,6 +2181,29 @@ public:
   }
 
 private:
+  // Must be called from every open path, before the connection string is logged and before any
+  // session or bucket is constructed, so that connection-context prefixes built later carry their
+  // tags.
+  //
+  // Redaction state is process-wide while it is configured per cluster, so opening a cluster may
+  // only turn it on, never off: one cluster must not silently disable redaction for another, or
+  // for an application that enabled it directly.
+  void apply_log_redaction() const
+  {
+    if (origin_.options().log_redaction) {
+      logger::set_log_redaction(true);
+    }
+    // The warning has to test the state that is in effect rather than what this cluster asked for.
+    // Redaction is process-wide, so another cluster or a direct set_log_redaction() call may have
+    // turned it on, and a cluster opened with only dump_configuration would then write
+    // unannotated dumps into a redacted log without saying so.
+    if (origin_.options().dump_configuration && logger::is_log_redaction_enabled()) {
+      CB_LOG_WARNING("log redaction is enabled, but so is dump_configuration: configuration dumps "
+                     "are not annotated for redaction and may contain values that are annotated "
+                     "elsewhere in the log");
+    }
+  }
+
   void setup_observability()
   {
     // ignore the enable_tracing flag if a tracer was passed in
@@ -1352,15 +2252,10 @@ private:
 
   auto has_capella_host() const -> bool
   {
-    bool has_capella_host = false;
-    static const std::string suffix = "cloud.couchbase.com";
-    for (const auto& node : origin_.get_hostnames()) {
-      if (auto pos = node.find(suffix);
-          pos != std::string::npos && pos + suffix.size() == node.size()) {
-        has_capella_host = true;
-      }
-    }
-    return has_capella_host;
+    auto hostnames = origin_.get_hostnames();
+    return std::any_of(hostnames.begin(), hostnames.end(), [](const std::string& host) {
+      return is_capella_host(host);
+    });
   }
 
   std::string id_{ uuid::to_string(uuid::random()) };
@@ -1372,8 +2267,19 @@ private:
   std::optional<io::mcbp_session> session_{};
   std::shared_ptr<impl::dns_srv_tracker> dns_srv_tracker_{};
   std::mutex buckets_mutex_{};
+  // Orders update_credentials() against do_open() constructing session_, and against close() moving
+  // session_ and session_manager_ out.
+  std::mutex update_credentials_mutex_{};
   std::map<std::string, std::shared_ptr<bucket>> buckets_{};
   couchbase::core::origin origin_{};
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+  // Set when the cluster was opened with a couchbase2:// connection string; KV ops route here
+  // instead of to the MCBP session manager. Guarded by protostellar_mutex_: execute() reads it on
+  // the caller's thread while close() resets it on the io thread. Always reach it through
+  // protostellar_component(). Mutable so the const observers can lock.
+  mutable std::mutex protostellar_mutex_{};
+  std::shared_ptr<protostellar::component> protostellar_{};
+#endif
   std::shared_ptr<class cluster_label_listener> cluster_label_listener_{
     std::make_shared<class cluster_label_listener>()
   };
@@ -1381,22 +2287,77 @@ private:
   std::shared_ptr<metrics::meter_wrapper> meter_{ nullptr };
   std::shared_ptr<orphan_reporter> orphan_reporter_{ nullptr };
   std::atomic_bool stopped_{ false };
+  std::mutex close_hooks_mutex_{};
+  std::vector<std::pair<std::weak_ptr<void>, utils::movable_function<void()>>> close_hooks_{};
+  std::mutex deferred_until_open_mutex_{};
+  bool opening_{ false };
+  // Each entry's resume holds this cluster until it runs, as session_'s bootstrap callback does.
+  // close() runs them, so the io_context must outlive the cluster and still be running when
+  // close() is called.
+  std::list<std::shared_ptr<deferred_request>> deferred_until_open_{};
+  std::mutex dns_srv_open_handler_mutex_{};
+  utils::movable_function<void(std::error_code)> dns_srv_open_handler_{};
+  // Taken by origin(), update_credentials() and the writes to origin_ that can overlap them: the
+  // assignment in open(), and the DNS SRV and bootstrap callbacks.
+  mutable std::mutex origin_mutex_{};
   std::shared_ptr<core::app_telemetry_meter> app_telemetry_meter_{
     std::make_shared<core::app_telemetry_meter>()
   };
-
-#ifdef COUCHBASE_CXX_CLIENT_COLUMNAR
-  std::shared_ptr<couchbase::core::io::cluster_config_tracker> config_tracker_{};
-  asio::steady_timer retry_backoff_;
-  std::atomic_bool background_open_started_{ false };
-#endif
 };
 
+namespace
+{
+// Holds a replica read issued while open() bootstraps, as cluster_impl::execute() holds a
+// key-value request. These reach the bucket through open_bucket(), which carries no deadline.
+// `make_error` builds the response for a request whose timeout passes first.
+template<typename Request, typename Handler, typename MakeError>
+auto
+defer_replica_read(const cluster& self,
+                   const std::shared_ptr<cluster_impl>& impl,
+                   Request& request,
+                   Handler& handler,
+                   MakeError make_error) -> bool
+{
+  const auto deadline =
+    std::chrono::steady_clock::now() +
+    request.timeout.value_or(impl->default_timeout_for(service_type::key_value));
+  return impl->defer_until_open(
+    [&] {
+      return [self,
+              deadline,
+              request = std::move(request),
+              handler = std::move(handler),
+              make_error = std::move(make_error)](std::error_code ec) mutable {
+        if (ec) {
+          return handler(make_error(request, ec));
+        }
+        request.timeout = remaining_until(deadline);
+        self.execute(std::move(request), std::move(handler));
+      };
+    },
+    deadline);
+}
+
+// The response for a subdocument replica read that did not run.
+template<typename Response, typename Request>
+auto
+subdocument_replica_error(const Request& request, std::error_code ec) -> Response
+{
+  return Response{ make_subdocument_error_context(
+    make_key_value_error_context(ec, request.id), ec, {}, {}, false) };
+}
+} // namespace
+
 cluster::cluster(asio::io_context& ctx)
   : impl_{ std::make_shared<cluster_impl>(ctx) }
 {
 }
 
+cluster::cluster(std::shared_ptr<cluster_impl> impl)
+  : impl_{ std::move(impl) }
+{
+}
+
 auto
 cluster::direct_dispatch(const std::string& bucket_name,
                          std::shared_ptr<couchbase::core::mcbp::queue_request> req) const
@@ -1445,20 +2406,6 @@ cluster::open(couchbase::core::origin origin,
   }
 }
 
-void
-cluster::open_in_background(
-  [[maybe_unused]] const couchbase::core::origin& origin,
-  [[maybe_unused]] utils::movable_function<void(std::error_code)>&& handler) const
-{
-#ifdef COUCHBASE_CXX_CLIENT_COLUMNAR
-  if (impl_) {
-    impl_->open_in_background(origin, std::move(handler));
-  }
-#else
-  CB_LOG_ERROR("Background open only available for Columnar builds.");
-#endif
-}
-
 void
 cluster::diagnostics(std::optional<std::string> report_id,
                      utils::movable_function<void(diag::diagnostics_result)>&& handler) const
@@ -1561,16 +2508,16 @@ cluster::execute(
   operations::get_all_replicas_request request,
   utils::movable_function<void(operations::get_all_replicas_response)>&& handler) const
 {
-  auto bucket_name = request.id.bucket();
-  return open_bucket(
-    bucket_name,
-    [impl = impl_, request = std::move(request), handler = std::move(handler)](auto ec) mutable {
-      if (ec) {
-        return handler(
-          operations::get_all_replicas_response{ make_key_value_error_context(ec, request.id) });
-      }
-      return request.execute(impl, std::move(handler));
-    });
+  if (impl_->is_protostellar()) {
+    return handler(operations::get_all_replicas_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
+  if (defer_replica_read(*this, impl_, request, handler, [](const auto& r, std::error_code ec) {
+        return operations::get_all_replicas_response{ make_key_value_error_context(ec, r.id) };
+      })) {
+    return;
+  }
+  return request.execute(impl_, std::move(handler));
 }
 
 void
@@ -1592,16 +2539,16 @@ cluster::execute(
   operations::get_any_replica_request request,
   utils::movable_function<void(operations::get_any_replica_response)>&& handler) const
 {
-  auto bucket_name = request.id.bucket();
-  return open_bucket(
-    bucket_name,
-    [impl = impl_, request = std::move(request), handler = std::move(handler)](auto ec) mutable {
-      if (ec) {
-        return handler(
-          operations::get_any_replica_response{ make_key_value_error_context(ec, request.id) });
-      }
-      return request.execute(impl, std::move(handler));
-    });
+  if (impl_->is_protostellar()) {
+    return handler(operations::get_any_replica_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
+  if (defer_replica_read(*this, impl_, request, handler, [](const auto& r, std::error_code ec) {
+        return operations::get_any_replica_response{ make_key_value_error_context(ec, r.id) };
+      })) {
+    return;
+  }
+  return request.execute(impl_, std::move(handler));
 }
 
 void
@@ -1637,6 +2584,19 @@ cluster::execute(
   operations::lookup_in_any_replica_request request,
   utils::movable_function<void(operations::lookup_in_any_replica_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::lookup_in_any_replica_response{ make_subdocument_error_context(
+      make_key_value_error_context(errc::common::feature_not_available, request.id),
+      errc::common::feature_not_available,
+      {},
+      {},
+      false) });
+  }
+  if (defer_replica_read(*this, impl_, request, handler, [](const auto& r, std::error_code ec) {
+        return subdocument_replica_error<operations::lookup_in_any_replica_response>(r, ec);
+      })) {
+    return;
+  }
   return request.execute(impl_, std::move(handler));
 }
 
@@ -1645,6 +2605,19 @@ cluster::execute(
   operations::lookup_in_all_replicas_request request,
   utils::movable_function<void(operations::lookup_in_all_replicas_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::lookup_in_all_replicas_response{ make_subdocument_error_context(
+      make_key_value_error_context(errc::common::feature_not_available, request.id),
+      errc::common::feature_not_available,
+      {},
+      {},
+      false) });
+  }
+  if (defer_replica_read(*this, impl_, request, handler, [](const auto& r, std::error_code ec) {
+        return subdocument_replica_error<operations::lookup_in_all_replicas_response>(r, ec);
+      })) {
+    return;
+  }
   return request.execute(impl_, std::move(handler));
 }
 
@@ -1669,6 +2642,111 @@ cluster::execute(operations::query_request request,
   return impl_->execute(std::move(request), std::move(handler));
 }
 
+void
+cluster::query_stream(operations::query_request request,
+                      utils::movable_function<void(couchbase::core::query_stream,
+                                                   error_context::query)>&& handler) const
+{
+  if (const auto deadline =
+        std::chrono::steady_clock::now() +
+        request.timeout.value_or(impl_->default_timeout_for(service_type::query));
+      impl_->defer_until_open(
+        [&] {
+          return
+            [self = *this, deadline, request = std::move(request), handler = std::move(handler)](
+              std::error_code ec) mutable {
+              if (ec) {
+                error_context::query ctx{};
+                ctx.ec = ec;
+                ctx.statement = request.statement;
+                ctx.client_context_id = request.client_context_id.has_value()
+                                          ? *request.client_context_id
+                                          : uuid::to_string(uuid::random());
+                return handler({}, std::move(ctx));
+              }
+              request.timeout = remaining_until(deadline);
+              self.query_stream(std::move(request), std::move(handler));
+            };
+        },
+        deadline)) {
+    return;
+  }
+  // Mirror operations::query_request::encode_to: use_replica is only honored when the cluster
+  // advertises read-from-replica support, otherwise the request is rejected up front. Rejected here
+  // means nothing was dispatched, so the context can only describe the request itself.
+  if (request.use_replica.has_value()) {
+    auto reject = [&request](std::error_code ec) {
+      error_context::query ctx{};
+      ctx.ec = ec;
+      ctx.statement = request.statement;
+      // Generate an id when the caller supplied none, the way every dispatched path does, so even
+      // a request rejected before dispatch has a context that can be correlated with the logs.
+      // Not value_or(): its argument is evaluated whether or not the optional is engaged, which
+      // would generate and format a UUID only to discard it whenever the caller supplied an id.
+      ctx.client_context_id = request.client_context_id.has_value()
+                                ? *request.client_context_id
+                                : uuid::to_string(uuid::random());
+      ctx.method = "POST";
+      ctx.path = "/query/service";
+      return ctx;
+    };
+    auto [ec, manager] = impl_->http_session_manager();
+    if (ec) {
+      return handler({}, reject(ec));
+    }
+    if (!manager->configuration_capabilities().supports_read_from_replica()) {
+      return handler({}, reject(errc::common::feature_not_available));
+    }
+  }
+
+  auto cluster_opts = impl_->origin().second.options();
+  auto default_timeout = cluster_opts.default_timeout_for(service_type::query);
+  http_component http{ impl_->io_context(), core_sdk_shim{ *this } };
+  const query_stream_component component{
+    impl_->io_context(), std::move(http), default_timeout, cluster_opts.streaming
+  };
+  component.execute(std::move(request), std::move(handler));
+}
+
+void
+cluster::analytics_query_stream(
+  operations::analytics_request request,
+  utils::movable_function<void(couchbase::core::analytics_stream, error_context::analytics)>&&
+    handler) const
+{
+  if (const auto deadline =
+        std::chrono::steady_clock::now() +
+        request.timeout.value_or(impl_->default_timeout_for(service_type::analytics));
+      impl_->defer_until_open(
+        [&] {
+          return
+            [self = *this, deadline, request = std::move(request), handler = std::move(handler)](
+              std::error_code ec) mutable {
+              if (ec) {
+                error_context::analytics ctx{};
+                ctx.ec = ec;
+                ctx.statement = request.statement;
+                ctx.client_context_id = request.client_context_id.has_value()
+                                          ? *request.client_context_id
+                                          : uuid::to_string(uuid::random());
+                return handler({}, std::move(ctx));
+              }
+              request.timeout = remaining_until(deadline);
+              self.analytics_query_stream(std::move(request), std::move(handler));
+            };
+        },
+        deadline)) {
+    return;
+  }
+  auto cluster_opts = impl_->origin().second.options();
+  auto default_timeout = cluster_opts.default_timeout_for(service_type::analytics);
+  http_component http{ impl_->io_context(), core_sdk_shim{ *this } };
+  const analytics_stream_component component{
+    impl_->io_context(), std::move(http), default_timeout, cluster_opts.streaming
+  };
+  component.execute(std::move(request), std::move(handler));
+}
+
 void
 cluster::execute(operations::remove_request request,
                  utils::movable_function<void(operations::remove_response)>&& handler) const
@@ -2331,8 +3409,8 @@ cluster::execute(
 }
 
 void
-cluster::execute(impl::get_replica_request request,
-                 utils::movable_function<void(impl::get_replica_response)>&& handler) const
+cluster::execute(operations::get_replica_request request,
+                 utils::movable_function<void(operations::get_replica_response)>&& handler) const
 {
   return impl_->execute(std::move(request), std::move(handler));
 }
@@ -2415,6 +3493,10 @@ void
 cluster::execute(operations::upsert_request_with_legacy_durability request,
                  utils::movable_function<void(operations::upsert_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::upsert_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
   return request.execute(*this, std::move(handler));
 }
 
@@ -2422,6 +3504,10 @@ void
 cluster::execute(operations::insert_request_with_legacy_durability request,
                  utils::movable_function<void(operations::insert_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::insert_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
   return request.execute(*this, std::move(handler));
 }
 
@@ -2429,6 +3515,10 @@ void
 cluster::execute(operations::append_request_with_legacy_durability request,
                  utils::movable_function<void(operations::append_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::append_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
   return request.execute(*this, std::move(handler));
 }
 
@@ -2436,6 +3526,10 @@ void
 cluster::execute(operations::prepend_request_with_legacy_durability request,
                  utils::movable_function<void(operations::prepend_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::prepend_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
   return request.execute(*this, std::move(handler));
 }
 
@@ -2443,6 +3537,10 @@ void
 cluster::execute(operations::replace_request_with_legacy_durability request,
                  utils::movable_function<void(operations::replace_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::replace_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
   return request.execute(*this, std::move(handler));
 }
 
@@ -2450,6 +3548,14 @@ void
 cluster::execute(operations::mutate_in_request_with_legacy_durability request,
                  utils::movable_function<void(operations::mutate_in_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::mutate_in_response{ make_subdocument_error_context(
+      make_key_value_error_context(errc::common::feature_not_available, request.id),
+      errc::common::feature_not_available,
+      {},
+      {},
+      false) });
+  }
   return request.execute(*this, std::move(handler));
 }
 
@@ -2457,6 +3563,10 @@ void
 cluster::execute(operations::remove_request_with_legacy_durability request,
                  utils::movable_function<void(operations::remove_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::remove_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
   return request.execute(*this, std::move(handler));
 }
 
@@ -2464,6 +3574,10 @@ void
 cluster::execute(operations::increment_request_with_legacy_durability request,
                  utils::movable_function<void(operations::increment_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::increment_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
   return request.execute(*this, std::move(handler));
 }
 
@@ -2471,6 +3585,10 @@ void
 cluster::execute(operations::decrement_request_with_legacy_durability request,
                  utils::movable_function<void(operations::decrement_response)>&& handler) const
 {
+  if (impl_->is_protostellar()) {
+    return handler(operations::decrement_response{
+      make_key_value_error_context(errc::common::feature_not_available, request.id) });
+  }
   return request.execute(*this, std::move(handler));
 }
 
@@ -2497,7 +3615,7 @@ cluster::execute(operations::lookup_in_request_with_cancellation request,
 
 void
 cluster::execute(operations::get_replica_request_with_cancellation request,
-                 utils::movable_function<void(impl::get_replica_response)>&& handler) const
+                 utils::movable_function<void(operations::get_replica_response)>&& handler) const
 {
   return impl_->execute(std::move(request), std::move(handler));
 }
@@ -2526,13 +3644,13 @@ cluster::to_string() const -> std::string
 }
 
 auto
-cluster::tracer() const -> const std::shared_ptr<tracing::tracer_wrapper>&
+cluster::tracer() const -> std::shared_ptr<tracing::tracer_wrapper>
 {
   return impl_->tracer();
 }
 
 auto
-cluster::meter() const -> const std::shared_ptr<metrics::meter_wrapper>&
+cluster::meter() const -> std::shared_ptr<metrics::meter_wrapper>
 {
   return impl_->meter();
 }
@@ -2543,4 +3661,42 @@ cluster::cluster_label_listener() const -> const std::shared_ptr<core::cluster_l
   return impl_->cluster_label_listener();
 }
 
+auto
+cluster::find_bucket_by_name(const std::string& name) const -> std::shared_ptr<bucket>
+{
+  return impl_->find_bucket_by_name(name);
+}
+
+auto
+cluster::is_protostellar() const -> bool
+{
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+  if (impl_) {
+    return impl_->is_protostellar();
+  }
+#endif
+  return false;
+}
+
+auto
+cluster::add_close_hook(std::weak_ptr<void> owner, utils::movable_function<void()>&& hook) const
+  -> bool
+{
+  if (!impl_) {
+    return false;
+  }
+  return impl_->add_close_hook(std::move(owner), std::move(hook));
+}
+
+auto
+cluster::protostellar_channel_ready() const -> std::pair<std::error_code, bool>
+{
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+  if (impl_ && impl_->is_protostellar()) {
+    return impl_->protostellar_channel_ready();
+  }
+#endif
+  return { errc::common::feature_not_available, false };
+}
+
 } // namespace couchbase::core