couchbase 3.8.1 → 3.9.0

data/ext/couchbase/couchbase/cluster.hxx

@@ -32,7 +32,9 @@
 #include <couchbase/search_query.hxx>
 #include <couchbase/search_request.hxx>
 #include <couchbase/transactions.hxx>
+#include <couchbase/wait_until_ready_options.hxx>
 
+#include <chrono>
 #include <memory>
 
 namespace couchbase
@@ -67,8 +69,16 @@ public:
    * over this options).
    * @param handler the handler
    *
+   * @note A connection string with the @c couchbase2:// scheme selects the @ref couchbase2
+   * "couchbase2" transport, which routes every operation through a Cloud Native Gateway (CNG). It
+   * requires a library built with that support and restricts how the connection string may be
+   * written; see
+   * @ref couchbase2.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   static void connect(const std::string& connection_string,
                       const cluster_options& options,
@@ -83,8 +93,16 @@ public:
    *
    * @return future object that carries cluster object and operation status
    *
+   * @note A connection string with the @c couchbase2:// scheme selects the @ref couchbase2
+   * "couchbase2" transport, which routes every operation through a Cloud Native Gateway (CNG). It
+   * requires a library built with that support and restricts how the connection string may be
+   * written; see
+   * @ref couchbase2.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] static auto connect(const std::string& connection_string,
                                     const cluster_options& options)
@@ -97,6 +115,39 @@ public:
   auto operator=(const cluster& other) -> cluster& = default;
   auto operator=(cluster&& other) -> cluster& = default;
 
+  /**
+   * Notify the cluster of a fork-related event, so it can keep its I/O usable
+   * across @c fork().
+   *
+   * Call it three times, in this order: @ref fork_event::prepare in the parent
+   * before forking, then @ref fork_event::child in the child and @ref
+   * fork_event::parent in the parent.
+   *
+   * NOTE: @ref fork_event::child reconnects this cluster on a fresh set of
+   * sockets, because the inherited ones belong to the parent. Any @ref bucket,
+   * @ref scope or @ref collection handle obtained before the fork still refers to
+   * the pre-fork connections, so in the child those handles must be re-acquired
+   * from the cluster -- using a stale one fails with @ref
+   * errc::network::cluster_closed. Handles held in the parent stay valid.
+   *
+   * This function must not be called while operations are in flight on this
+   * cluster from another thread.
+   *
+   * On platforms without @c fork(), Windows in particular, this function does
+   * nothing. It remains callable everywhere so that portable code does not have to
+   * guard the calls, but nothing about the cluster changes.
+   *
+   * @param event the fork-related event that is about to happen, or just happened.
+   *
+   * @throws std::system_error if the I/O backend cannot be carried across the fork.
+   * There is no recovery for this: the cluster's io_context is unusable afterwards
+   * and the only thing left to do with the cluster is destroy it. It is reported
+   * rather than swallowed because a caller that went on using such a cluster would
+   * be operating on a reactor that no longer tracks its sockets.
+   *
+   * @since 1.0.0
+   * @uncommitted
+   */
   void notify_fork(fork_event event);
 
   void close(std::function<void()>&& handler);
@@ -120,11 +171,11 @@ public:
   /**
    * Replaces the current authenticator used by this cluster.
    *
-   * NOTE: Setting a new authenticator does not change the authentication status of existing
-   connections.
+   * NOTE: Existing KV connections keep the certificate they were opened with. HTTP requests sent
+   * after the call use a new connection, and a request already in flight completes.
    *
    * @param authenticator the authenticator to replace
-
+   *
    * @exception errc::common::invalid_argument if TLS is not enabled.
    *
    * @return error
@@ -188,6 +239,60 @@ public:
   [[nodiscard]] auto query(std::string statement, const query_options& options) const
     -> std::future<std::pair<error, query_result>>;
 
+  /**
+   * Performs a streaming query against the query (N1QL) services.
+   *
+   * The handler resolves as soon as the response preamble has been parsed; rows are then pulled
+   * lazily from the @ref query_stream_result, so the full result is never buffered in memory.
+   *
+   * @note Prepared statements (@ref query_options#adhoc set to false) are not streamed: such a
+   * request falls back to the buffered @ref query() path and its rows are replayed through the
+   * returned handle.
+   *
+   * The handler runs on the library's I/O thread, so the stream must be drained with the callback
+   * @ref query_stream_result#next() overload rather than the blocking ones:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-async
+   *
+   * @param statement the N1QL query statement.
+   * @param options options to customize the query request.
+   * @param handler the handler that implements @ref query_stream_handler
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  void query_stream(std::string statement,
+                    const query_options& options,
+                    query_stream_handler&& handler) const;
+
+  /**
+   * Performs a streaming query against the query (N1QL) services.
+   *
+   * Rows are pulled from the returned handle one at a time, so a result of any size costs the same
+   * bounded amount of memory:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream
+   *
+   * The document type the rows are decoded into:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx streaming-product
+   *
+   * A failure surfaces either here, before the stream starts, or as the terminal of
+   * @ref query_stream_result#next() — possibly after rows have already been consumed, which a
+   * buffered @ref query() cannot produce. Both channels have to be handled:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-errors
+   *
+   * @param statement the N1QL query statement.
+   * @param options options to customize the query request.
+   * @return future object that carries the streaming result handle
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto query_stream(std::string statement, const query_options& options = {}) const
+    -> std::future<std::pair<error, query_stream_result>>;
+
   /**
    * Performs a request against the full text search services.
    *
@@ -265,8 +370,48 @@ public:
    * @since 1.0.0
    * @committed
    */
-  [[nodiscard]] auto analytics_query(std::string statement, const analytics_options& options = {})
-    const -> std::future<std::pair<error, analytics_result>>;
+  [[nodiscard]] auto analytics_query(std::string statement,
+                                     const analytics_options& options = {}) const
+    -> std::future<std::pair<error, analytics_result>>;
+
+  /**
+   * Performs a streaming query against the analytics services.
+   *
+   * The handler resolves as soon as the response preamble has been parsed; rows are then pulled
+   * lazily from the @ref analytics_stream_result, so the full result is never buffered in memory.
+   *
+   * The handler runs on the library's I/O thread, so the stream must be drained with the callback
+   * @ref analytics_stream_result#next() overload rather than the blocking ones. The query
+   * equivalent shows the pattern:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-query-stream-async
+   *
+   * @param statement the analytics query statement.
+   * @param options options to customize the query request.
+   * @param handler the handler that implements @ref analytics_stream_handler
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  void analytics_query_stream(std::string statement,
+                              const analytics_options& options,
+                              analytics_stream_handler&& handler) const;
+
+  /**
+   * Performs a streaming query against the analytics services.
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-analytics-stream
+   *
+   * @param statement the analytics query statement.
+   * @param options options to customize the query request.
+   * @return future object that carries the streaming result handle
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto analytics_query_stream(std::string statement,
+                                            const analytics_options& options = {}) const
+    -> std::future<std::pair<error, analytics_stream_result>>;
 
   /**
    * Performs application-level ping requests against services in the Couchbase cluster.
@@ -277,8 +422,13 @@ public:
    * @param options custom options to change the default behavior.
    * @param handler the handler that implements @ref ping_handler.
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which has no per-node service
+   * endpoints to probe and reports @ref errc::common::feature_not_available instead.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   void ping(const ping_options& options, ping_handler&& handler) const;
 
@@ -291,8 +441,13 @@ public:
    * @param options custom options to change the default behavior.
    * @return future object that carries result of the operation.
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which has no per-node service
+   * endpoints to probe and reports @ref errc::common::feature_not_available instead.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] auto ping(const ping_options& options = {}) const
     -> std::future<std::pair<error, ping_result>>;
@@ -310,8 +465,14 @@ public:
    * @param options custom options to change the default behavior.
    * @param handler the handler that implements @ref diagnostics_handler.
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which keeps no per-node
+   * connection state to report on and returns @ref errc::common::feature_not_available rather than
+   * an empty report.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   void diagnostics(const diagnostics_options& options, diagnostics_handler&& handler) const;
 
@@ -328,12 +489,62 @@ public:
    * @param options custom options to change the default behavior.
    * @return future object that carries result of the operation.
    *
+   * @note Not served over the @ref couchbase2 "couchbase2" transport, which keeps no per-node
+   * connection state to report on and returns @ref errc::common::feature_not_available rather than
+   * an empty report.
+   *
    * @since 1.0.0
    * @committed
+   * @cng_since{1.4.0}
+   * @cng_uncommitted
    */
   [[nodiscard]] auto diagnostics(const diagnostics_options& options = {}) const
     -> std::future<std::pair<error, diagnostics_result>>;
 
+  /**
+   * Waits until the desired state of the cluster is reached, actively pinging its services until
+   * they respond or the timeout elapses.
+   *
+   * Over couchbase2, the wait ends once the gRPC channel to the gateway is connected. No service is
+   * pinged, the requested services are not considered, and @c cluster_state::online and
+   * @c cluster_state::degraded are the same state.
+   *
+   * Closing the cluster ends a wait in flight with @ref errc::network::cluster_closed, and a wait
+   * started after the cluster is closed fails the same way.
+   *
+   * @param timeout the maximum time to wait for readiness.
+   * @param options custom options to change the default behavior.
+   * @param handler the handler that implements @ref wait_until_ready_handler.
+   *
+   * @since 1.4.0
+   * @committed
+   */
+  void wait_until_ready(std::chrono::milliseconds timeout,
+                        const wait_until_ready_options& options,
+                        wait_until_ready_handler&& handler) const;
+
+  /**
+   * Waits until the desired state of the cluster is reached, actively pinging its services until
+   * they respond or the timeout elapses.
+   *
+   * Over couchbase2, the wait ends once the gRPC channel to the gateway is connected. No service is
+   * pinged, the requested services are not considered, and @c cluster_state::online and
+   * @c cluster_state::degraded are the same state.
+   *
+   * Closing the cluster ends a wait in flight with @ref errc::network::cluster_closed, and a wait
+   * started after the cluster is closed fails the same way.
+   *
+   * @param timeout the maximum time to wait for readiness.
+   * @param options custom options to change the default behavior.
+   * @return future object that carries result of the operation.
+   *
+   * @since 1.4.0
+   * @committed
+   */
+  [[nodiscard]] auto wait_until_ready(std::chrono::milliseconds timeout,
+                                      const wait_until_ready_options& options = {}) const
+    -> std::future<error>;
+
   /**
    * Provides access to the N1QL index management services.
    *

data/ext/couchbase/{core/columnar/security_options.hxx → couchbase/cluster_state.hxx}

@@ -1,6 +1,6 @@
 /* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
 /*
- *   Copyright 2020-2021 Couchbase, Inc.
+ *   Copyright 2026-Present Couchbase, Inc.
  *
  *   Licensed under the Apache License, Version 2.0 (the "License");
  *   you may not use this file except in compliance with the License.
@@ -17,18 +17,22 @@
 
 #pragma once
 
-#include <string>
-#include <vector>
-
-namespace couchbase::core::columnar
+namespace couchbase
 {
-struct security_options {
-public:
-  bool trust_only_capella{ true };
-  bool trust_only_pem_file{ false };
-  bool trust_only_pem_string{ false };
-  bool trust_only_platform{ false };
-  std::vector<std::string> trust_only_certificates{};
-  std::vector<std::string> cipher_suites{};
+/**
+ * Describes the readiness of the cluster (or a bucket) from the SDK's point of view. Used as the
+ * target state of @ref cluster::wait_until_ready() and @ref bucket::wait_until_ready().
+ *
+ * @since 1.4.0
+ * @committed
+ */
+enum class cluster_state {
+  /** Every reachable endpoint of every requested service is responsive. */
+  online,
+  /** At least one endpoint of every requested service is responsive. */
+  degraded,
+  /** Not a meaningful state to wait for; passing it is rejected with @c
+   * errc::common::invalid_argument. */
+  offline,
 };
-} // namespace couchbase::core::columnar
+} // namespace couchbase

data/ext/couchbase/couchbase/codec/lenient_json_transcoder.hxx

@@ -0,0 +1,69 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2020-Present Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#pragma once
+
+#include <couchbase/codec/codec_flags.hxx>
+#include <couchbase/codec/encoded_value.hxx>
+#include <couchbase/codec/transcoder_traits.hxx>
+
+namespace couchbase::codec
+{
+class tao_json_serializer;
+
+/**
+ * A JSON transcoder that encodes with JSON common flags like @ref json_transcoder, but does NOT
+ * validate the document's common flags when decoding.
+ *
+ * It backs the no-transcoder `content_as<Document>()` overloads of the transactions read results
+ * (@ref couchbase::transactions::transaction_get_result and the get-multi results): per the
+ * ExtBinarySupport spec the SDK "ignores [the flags] when reading", so e.g. a document written with
+ * binary common flags but holding valid JSON can still be read. This restores the
+ * pre-ExtBinarySupport behaviour where those accessors did not reject non-JSON flags. Ordinary KV
+ * reads continue to use the strict @ref json_transcoder.
+ *
+ * It is an implementation detail of the transactions read path and is not meant to be named
+ * explicitly by applications.
+ *
+ * @since 1.4.0
+ * @internal
+ */
+template<typename Serializer>
+class lenient_json_transcoder
+{
+public:
+  template<typename Document>
+  static auto encode(Document document) -> encoded_value
+  {
+    return { Serializer::serialize(document), codec_flags::json_common_flags };
+  }
+
+  template<typename Document>
+  static auto decode(const encoded_value& encoded) -> Document
+  {
+    return Serializer::template deserialize<Document>(encoded.data);
+  }
+};
+
+using default_lenient_json_transcoder = lenient_json_transcoder<tao_json_serializer>;
+
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+template<>
+struct is_transcoder<default_lenient_json_transcoder> : public std::true_type {
+};
+#endif
+} // namespace couchbase::codec