couchbase 3.8.1 → 3.9.0

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

@@ -15,6 +15,8 @@
  *   limitations under the License.
  */
 
+#include <couchbase/build_config.hxx>
+
 #include "core/cluster.hxx"
 
 #include "analytics.hxx"
@@ -23,6 +25,7 @@
 #include "core/cluster_options.hxx"
 #include "core/core_sdk_shim.hxx"
 #include "core/io/ip_protocol.hxx"
+#include "core/io/streams.hxx"
 #include "core/origin.hxx"
 #include "core/tls_verify_mode.hxx"
 #include "core/tracing/constants.hxx"
@@ -36,6 +39,7 @@
 #include "observability_recorder.hxx"
 #include "query.hxx"
 #include "search.hxx"
+#include "wait_until_ready.hxx"
 
 #include <couchbase/analytics_index_manager.hxx>
 #include <couchbase/analytics_options.hxx>
@@ -46,6 +50,7 @@
 #include <couchbase/cluster_options.hxx>
 #include <couchbase/diagnostics_options.hxx>
 #include <couchbase/diagnostics_result.hxx>
+#include <couchbase/error_codes.hxx>
 #include <couchbase/fmt/error.hxx>
 #include <couchbase/fork_event.hxx>
 #include <couchbase/ip_protocol.hxx>
@@ -65,6 +70,8 @@
 #include <asio/execution_context.hpp>
 #include <asio/post.hpp>
 
+#include <gsl/assert>
+
 #include <functional>
 #include <future>
 #include <memory>
@@ -173,6 +180,8 @@ options_to_origin(const std::string& connection_string, cluster_options::built o
   user_options.server_group = opts.network.server_group;
 
   user_options.enable_compression = opts.compression.enabled;
+  user_options.compression_min_size = opts.compression.min_size;
+  user_options.compression_min_ratio = opts.compression.min_ratio;
 
   user_options.enable_metrics = opts.metrics.enabled;
   if (opts.metrics.enabled) {
@@ -323,6 +332,28 @@ public:
       });
   }
 
+  // The open notify_fork(child) starts and does not wait for. Requests issued meanwhile wait in the
+  // core for the bootstrap. A failed open leaves the core closed, so they then get cluster_closed.
+  //
+  // The handler captures `this`. It runs inline when open() fails or succeeds without I/O, and
+  // otherwise on the IO thread before do_close() joins it: do_close() closes the core first, which
+  // completes a pending open.
+  void reopen()
+  {
+    opened_future_ = opened_.get_future().share();
+    core_.open(options_to_origin(connection_string_, options_), [this](std::error_code ec) {
+      if (ec) {
+        CB_LOG_ERROR("Unable to reconnect instance after fork: {}", ec.message());
+      }
+      opened_.set_value();
+    });
+    // Created now, not after the bootstrap, so transactions() never sees it unset and nothing
+    // writes it from the IO thread. The requests its cleanup issues wait in the core for the
+    // bootstrap.
+    transactions_ =
+      std::make_shared<core::transactions::transactions>(core_, options_.transactions);
+  }
+
   void query(std::string statement, query_options::built options, query_handler&& handler) const
   {
     auto obs_rec = create_observability_recorder(
@@ -339,6 +370,22 @@ public:
       });
   }
 
+  void query_stream(std::string statement,
+                    query_options::built options,
+                    query_stream_handler&& handler) const
+  {
+    // Instrument the streaming operation exactly like the buffered query(): build the recorder,
+    // thread its operation span into the request as parent_span, and hand the recorder to the
+    // stream so it finishes (latency metric + span end) at the terminal.
+    auto obs_rec = create_observability_recorder(
+      core::tracing::operation::query, core::service_type::query, options.parent_span);
+    obs_rec->with_query_statement(statement, options);
+    auto request = core::impl::build_query_request(
+      std::move(statement), {}, std::move(options), obs_rec->operation_span());
+    core::impl::dispatch_query_stream(
+      core_, std::move(request), std::move(obs_rec), std::move(handler));
+  }
+
   void analytics_query(std::string statement,
                        analytics_options::built options,
                        analytics_handler&& handler) const
@@ -357,10 +404,36 @@ public:
       });
   }
 
+  void analytics_query_stream(std::string statement,
+                              analytics_options::built options,
+                              analytics_stream_handler&& handler) const
+  {
+    // Instrument the streaming operation exactly like the buffered analytics_query() (see
+    // query_stream above for the recorder lifetime).
+    auto obs_rec = create_observability_recorder(
+      core::tracing::operation::analytics, core::service_type::analytics, options.parent_span);
+    obs_rec->with_query_statement(statement, options);
+    auto request = core::impl::build_analytics_request(
+      std::move(statement), std::move(options), {}, {}, obs_rec->operation_span());
+    core::impl::dispatch_analytics_stream(
+      core_, std::move(request), std::move(obs_rec), std::move(handler));
+  }
+
   void ping(const ping_options::built& options, ping_handler&& handler) const
   {
     auto obs_rec = create_observability_recorder(
       core::tracing::operation::ping, std::nullopt, options.parent_span);
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+    if (core_.is_protostellar()) {
+      // couchbase2 is a thin gRPC client with no per-service sessions to actively probe, and RFC 77
+      // defines no ping semantics for it. Mirror Java/Go/.NET, which surface ping as
+      // feature_not_available on this protocol, rather than returning a misleading empty report.
+      obs_rec->finish(errc::common::feature_not_available);
+      return handler(error{ errc::common::feature_not_available,
+                            "ping is not supported over the couchbase2 protocol" },
+                     {});
+    }
+#endif
     return core_.ping(
       options.report_id,
       {},
@@ -376,6 +449,16 @@ public:
   {
     auto obs_rec = create_observability_recorder(
       core::tracing::operation::diagnostics, std::nullopt, options.parent_span);
+#ifdef COUCHBASE_CXX_CLIENT_BUILD_COUCHBASE2
+    if (core_.is_protostellar()) {
+      // No per-service sessions exist to report on over couchbase2, and the RFC 77 Diagnostics
+      // section is empty. Mirror Java/Go/.NET (feature_not_available) instead of an empty report.
+      obs_rec->finish(errc::common::feature_not_available);
+      return handler(error{ errc::common::feature_not_available,
+                            "diagnostics is not supported over the couchbase2 protocol" },
+                     {});
+    }
+#endif
     return core_.diagnostics(
       options.report_id,
       [obs_rec = std::move(obs_rec), handler = std::move(handler)](const auto& resp) mutable {
@@ -384,6 +467,20 @@ public:
       });
   }
 
+  void wait_until_ready(std::chrono::milliseconds timeout,
+                        const wait_until_ready_options::built& options,
+                        wait_until_ready_handler&& handler) const
+  {
+    return core::impl::wait_until_ready(core_,
+                                        std::nullopt,
+                                        timeout,
+                                        options.desired_state,
+                                        core::impl::to_core_service_types(options.service_types),
+                                        [handler = std::move(handler)](std::error_code ec) mutable {
+                                          return handler(couchbase::error{ ec });
+                                        });
+  }
+
   void search(std::string index_name,
               couchbase::search_request request,
               const search_options::built& options,
@@ -414,19 +511,124 @@ public:
 
   void notify_fork(fork_event event)
   {
+    // asio requires notify_fork() to run with no thread inside io_context::run():
+    //
+    //   "This function must not be called while any other execution_context
+    //    function, or any function on an I/O object associated with the
+    //    execution_context, is being called in another thread."
+    //                                       -- asio/execution_context.hpp
+    //
+    // That is not a formality for fork_child: epoll_reactor::notify_fork() closes
+    // and recreates epoll_fd_, timer_fd_ and the interrupter, then rewrites every
+    // descriptor registration. Running it against a live reactor makes the IO
+    // thread epoll_wait() on a descriptor another thread is closing, and then
+    // dereference whatever epoll reports as a descriptor_state.
+    //
+    // So the fixup goes in the window where the IO thread is not running: after
+    // the join in fork_prepare, and before the restart that starts the new one.
     if (event == fork_event::prepare) {
+      // Quiesce the transactions cleanup threads BEFORE stopping the io_context.
+      // transactions_cleanup::stop() joins workers that may be blocking on a KV
+      // operation, and only the IO thread can complete those -- so stopping the
+      // io_context first can leave that join waiting forever.
+      if (transactions_) {
+        transactions_->notify_fork(event);
+      }
       io_.stop();
-      io_thread_.join();
+      // Guarded like do_close() below, and for the same reason: close() already
+      // stopped the io_context and joined this thread, so a notify_fork(prepare)
+      // afterwards has nothing left to join -- and join() on a thread that is not
+      // joinable throws std::system_error, out of a void public API.
+      if (io_thread_.joinable()) {
+        io_thread_.join();
+      }
+    }
+
+    // Our own IO thread is gone at this point, checkable in program order
+    // rather than only by a sanitizer: fork_prepare has just joined it, and
+    // fork_child/fork_parent inherit an already-joined one, because prepare runs
+    // before fork() and only the forking thread survives into the child. If a
+    // later change moves the restart back above this line, this fires
+    // immediately instead of turning into an intermittent use-after-free.
+    //
+    // The transactions cleanup threads were stopped above, before io_.stop(), so
+    // by here the only threads this cluster owned are gone.
+    Expects(!io_thread_.joinable());
+
+    if (event == fork_event::prepare) {
+      try {
+        io_.notify_fork(fork_event_to_asio(event));
+      } catch (...) {
+        // Undo everything this prepare did, then report. Returning stopped and threadless
+        // would hang ~cluster_impl, which waits on a completion only the IO thread can
+        // deliver -- the same hazard as the fork_parent path below. The fork
+        // must not go ahead, but the cluster stays usable and destructible.
+        //
+        // The io_context comes back first: restarting cleanup spawns workers that issue KV
+        // operations, and only the IO thread completes those. Restoring cleanup matters as
+        // much as restoring the thread -- it was stopped above, and leaving it stopped
+        // would silently disable lost-attempts cleanup for the rest of the process while
+        // this function claimed the cluster was fine.
+        //
+        // Note for the caller: do not try to compensate by calling notify_fork(parent)
+        // after this throws. Prepare has already been undone here, and that call would
+        // find a restarted IO thread and trip the precondition above.
+        io_.restart();
+        io_thread_ = std::thread{ [&io = io_] {
+          io.run();
+        } };
+        if (transactions_) {
+          transactions_->notify_fork(fork_event::parent);
+        }
+        throw;
+      }
+    } else if (event == fork_event::parent) {
+      io_.restart();
+      try {
+        io_.notify_fork(fork_event_to_asio(event));
+      } catch (...) {
+        // A service's notify_fork() threw. The io_context is unusable after that (asio says
+        // to destroy it), but destruction itself needs a runner: do_close()
+        // waits on a completion only the IO thread can deliver, so returning
+        // from here stopped and threadless would hang ~cluster_impl instead of
+        // surfacing the failure.
+        io_thread_ = std::thread{ [&io = io_] {
+          io.run();
+        } };
+        throw;
+      }
+      io_thread_ = std::thread{ [&io = io_] {
+        io.run();
+      } };
     } else {
-      // TODO(SA): close all sockets in fork_event::child
+      // The sockets of this io_context share open file descriptions with the parent, and their
+      // pending reads, writes and timers belong to the parent's sessions. The child detaches every
+      // registered stream and socket, then runs the inherited core's teardown to completion. The
+      // teardown cannot reach the parent's connections through them.
+      //
+      // close() comes before the fixup. It sets stopped_, so if the fixup throws, ~cluster_impl
+      // still completes without a runner.
+      std::promise<void> closed;
+      auto closed_future = closed.get_future();
+      core_.close([closed = std::move(closed)]() mutable {
+        closed.set_value();
+      });
+      // The fixup gives the child its own reactor, and on kqueue it is the only code that repairs
+      // kqueue_fd_. It must come before the detach: releasing a socket removes it from the
+      // reactor, and until the fixup that reactor is the parent's.
+      io_.notify_fork(fork_event_to_asio(event));
+      core::io::detach_inherited_sockets(io_);
       io_.restart();
       io_thread_ = std::thread{ [&io = io_] {
         io.run();
       } };
+      closed_future.get();
     }
-    io_.notify_fork(fork_event_to_asio(event));
 
-    if (event != fork_event::child && transactions_) {
+    // prepare was handled above, before the io_context was stopped. The child does
+    // not restart cleanup on this impl: it is about to be replaced, and the
+    // replacement starts its own.
+    if (event == fork_event::parent && transactions_) {
       transactions_->notify_fork(event);
     }
   }
@@ -436,6 +638,13 @@ public:
     // Spawn new thread to avoid joining IO thread from the same thread
     std::thread([self = shared_from_this(), handler = std::move(handler)]() mutable {
       self->do_close();
+      // Drop the reference before signalling completion, not after. handler() is what releases
+      // the caller's wait, so anything this thread still owns afterwards outlives that wait. When
+      // this is the last reference, releasing it later means ~cluster_impl -- which starts another
+      // thread and joins the IO thread -- runs unsynchronised with the caller, and a caller that
+      // returns from main() leaves those threads running while static destructors tear down the
+      // gRPC and abseil singletons underneath them.
+      self.reset();
       handler();
     }).detach();
   }
@@ -445,14 +654,33 @@ public:
     return core_;
   }
 
-  [[nodiscard]] auto transactions() const -> std::shared_ptr<core::transactions::transactions>
+  [[nodiscard]] auto core_transactions() const
+    -> const std::shared_ptr<core::transactions::transactions>&
   {
     return transactions_;
   }
 
+  [[nodiscard]] auto transactions() const -> std::shared_ptr<transactions::transactions>
+  {
+    return std::make_shared<transactions::transactions>(transactions_);
+  }
+
 private:
   void do_close()
   {
+    if (opened_future_.valid() &&
+        opened_future_.wait_for(std::chrono::seconds::zero()) != std::future_status::ready) {
+      // Closing the core fails the pending bootstrap and releases the requests the transactions
+      // cleanup holds, so neither wait below runs to bootstrap_timeout. The second core_.close()
+      // further down finds the core stopped and returns at once.
+      std::promise<void> core_stopped;
+      auto f = core_stopped.get_future();
+      core_.close([core_stopped = std::move(core_stopped)]() mutable {
+        core_stopped.set_value();
+      });
+      f.get();
+      opened_future_.wait();
+    }
     if (auto txns = std::move(transactions_); txns != nullptr) {
       // blocks until cleanup is finished
       txns->close();
@@ -487,7 +715,10 @@ private:
   cluster_options::built options_;
   asio::io_context io_{ ASIO_CONCURRENCY_HINT_SAFE };
   core::cluster core_{ io_ };
-  std::shared_ptr<core::transactions::transactions> transactions_{ nullptr };
+  std::shared_ptr<couchbase::core::transactions::transactions> transactions_{ nullptr };
+  // Set by reopen(); fulfilled once its open has finished, either way. do_close() reads it.
+  std::promise<void> opened_{};
+  std::shared_future<void> opened_future_{};
   std::thread io_thread_{ [&io = io_] {
     io.run();
   } };
@@ -508,6 +739,19 @@ extract_core_cluster(const couchbase::cluster& cluster) -> const core::cluster&
   return reinterpret_cast<const std::shared_ptr<cluster_impl>*>(&cluster)->get()->core();
 }
 
+/*
+ * This function exists only for usage in the unit tests, and might be removed at any moment.
+ * Avoid using it unless it is absolutely necessary.
+ */
+auto
+extract_core_transactions(const couchbase::cluster& cluster)
+  -> const std::shared_ptr<core::transactions::transactions>&
+{
+  return reinterpret_cast<const std::shared_ptr<cluster_impl>*>(&cluster)
+    ->get()
+    ->core_transactions();
+}
+
 void
 cluster::query(std::string statement, const query_options& options, query_handler&& handler) const
 {
@@ -526,6 +770,26 @@ cluster::query(std::string statement, const query_options& options) const
   return future;
 }
 
+void
+cluster::query_stream(std::string statement,
+                      const query_options& options,
+                      query_stream_handler&& handler) const
+{
+  return impl_->query_stream(std::move(statement), options.build(), std::move(handler));
+}
+
+auto
+cluster::query_stream(std::string statement, const query_options& options) const
+  -> std::future<std::pair<error, query_stream_result>>
+{
+  auto barrier = std::make_shared<std::promise<std::pair<error, query_stream_result>>>();
+  auto future = barrier->get_future();
+  query_stream(std::move(statement), options, [barrier](auto err, auto result) {
+    barrier->set_value({ std::move(err), std::move(result) });
+  });
+  return future;
+}
+
 void
 cluster::analytics_query(std::string statement,
                          const analytics_options& options,
@@ -546,6 +810,26 @@ cluster::analytics_query(std::string statement, const analytics_options& options
   return future;
 }
 
+void
+cluster::analytics_query_stream(std::string statement,
+                                const analytics_options& options,
+                                analytics_stream_handler&& handler) const
+{
+  return impl_->analytics_query_stream(std::move(statement), options.build(), std::move(handler));
+}
+
+auto
+cluster::analytics_query_stream(std::string statement, const analytics_options& options) const
+  -> std::future<std::pair<error, analytics_stream_result>>
+{
+  auto barrier = std::make_shared<std::promise<std::pair<error, analytics_stream_result>>>();
+  auto future = barrier->get_future();
+  analytics_query_stream(std::move(statement), options, [barrier](auto err, auto result) {
+    barrier->set_value({ std::move(err), std::move(result) });
+  });
+  return future;
+}
+
 void
 cluster::ping(const couchbase::ping_options& options, couchbase::ping_handler&& handler) const
 {
@@ -581,6 +865,26 @@ cluster::diagnostics(const couchbase::diagnostics_options& options) const
   return barrier->get_future();
 }
 
+void
+cluster::wait_until_ready(std::chrono::milliseconds timeout,
+                          const couchbase::wait_until_ready_options& options,
+                          couchbase::wait_until_ready_handler&& handler) const
+{
+  return impl_->wait_until_ready(timeout, options.build(), std::move(handler));
+}
+
+auto
+cluster::wait_until_ready(std::chrono::milliseconds timeout,
+                          const couchbase::wait_until_ready_options& options) const
+  -> std::future<error>
+{
+  auto barrier = std::make_shared<std::promise<error>>();
+  wait_until_ready(timeout, options, [barrier](auto err) mutable {
+    barrier->set_value(std::move(err));
+  });
+  return barrier->get_future();
+}
+
 void
 cluster::search(std::string index_name,
                 search_request request,
@@ -640,6 +944,16 @@ cluster::connect(const std::string& connection_string,
 auto
 cluster::notify_fork(fork_event event) -> void
 {
+#if defined(_WIN32)
+  // No fork(2) on Windows, so there is nothing to prepare for or recover from.
+  // The function stays part of the API on every platform -- callers, the wrapper
+  // SDKs especially, should not have to compile differently per platform -- but
+  // here it does nothing. Doing the POSIX work instead would stop and restart the
+  // io_context and re-bootstrap the cluster for no reason, and asio's IOCP
+  // backend has no notify_fork to apply either.
+  (void)event;
+  return;
+#else
   if (!impl_) {
     return;
   }
@@ -648,25 +962,11 @@ cluster::notify_fork(fork_event event) -> void
     return;
   }
 
-  auto new_impl = std::make_shared<cluster_impl>(impl_->connection_string(), impl_->options());
-  impl_.reset();
-
-  {
-    auto barrier = std::make_shared<std::promise<void>>();
-    auto future = barrier->get_future();
-
-    new_impl->open([this, barrier, new_impl](const auto& err, const auto& /* c */) {
-      if (err.ec()) {
-        // TODO(SA): we should fall to background reconnect loop similar to Columnar build
-        CB_LOG_ERROR("Unable to reconnect instance after fork: {}", err.ec().message());
-        return;
-      }
-      impl_ = new_impl;
-      barrier->set_value();
-    });
-
-    future.get();
-  }
+  impl_ = std::make_shared<cluster_impl>(impl_->connection_string(), impl_->options());
+  // Does not wait for the bootstrap: a cluster whose nodes do not answer would hold the child for
+  // the bootstrap timeout. The child has one thread here, so nothing reads impl_ concurrently.
+  impl_->reopen();
+#endif
 }
 
 void