couchbase 3.8.2 → 3.9.0

data/ext/couchbase/couchbase/get_replica_options.hxx

@@ -0,0 +1,68 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   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.
+ *   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/common_options.hxx>
+#include <couchbase/error.hxx>
+#include <couchbase/get_replica_result.hxx>
+
+#include <functional>
+
+namespace couchbase
+{
+/**
+ * Options for collection#get_replica().
+ *
+ * @since 1.5.0
+ * @committed
+ */
+struct get_replica_options : public common_options<get_replica_options> {
+  /**
+   * Immutable value object representing consistent options.
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  struct built : public common_options<get_replica_options>::built {
+  };
+
+  /**
+   * Validates options and returns them as an immutable value.
+   *
+   * @return consistent options as an immutable value
+   *
+   * @exception std::system_error with code errc::common::invalid_argument if the options are not
+   * valid
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> built
+  {
+    return { build_common_options() };
+  }
+};
+
+/**
+ * The signature for the handler of the @ref collection#get_replica() operation
+ *
+ * @since 1.5.0
+ * @committed
+ */
+using get_replica_handler = std::function<void(error, get_replica_result)>;
+} // namespace couchbase

data/ext/couchbase/couchbase/get_replica_result.hxx

@@ -32,8 +32,8 @@ class manager;
 #endif
 
 /**
- * Represents result of @ref collection#get_any_replica operations, also returned by @ref
- * collection#get_all_replicas.
+ * Represents result of @ref collection#get_any_replica, @ref collection#get_all_replicas and
+ * @ref collection#get_replica operations
  *
  * @since 1.0.0
  * @committed
@@ -48,11 +48,13 @@ public:
   get_replica_result() = default;
 
   /**
-   * Constructs result for get_any_replica operation, or an entry for get_all_replicas operation.
+   * Constructs result for get_any_replica or get_replica operation, or an entry for
+   * get_all_replicas operation.
    *
    * @param cas
    * @param is_replica true if the document originates from replica node
    * @param value raw document contents along with flags describing its structure
+   * @param crypto_manager manager handed to the transcoder to decrypt encrypted fields
    *
    * @since 1.0.0
    * @committed

data/ext/couchbase/couchbase/get_replica_strategy.hxx

@@ -0,0 +1,161 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   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.
+ *   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 <cstddef>
+
+namespace couchbase
+{
+/**
+ * Replica to read from, where @ref replica_index::first is the first replica of
+ * the vbucket. The active copy cannot be selected.
+ *
+ * @since 1.5.0
+ * @committed
+ */
+enum class replica_index {
+  first = 0,
+  second = 1,
+  third = 2,
+};
+
+/**
+ * Options for @ref get_replica_strategy::from_index().
+ *
+ * @since 1.5.0
+ * @committed
+ */
+struct get_replica_strategy_from_index_options {
+  /**
+   * Immutable value object representing consistent options.
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  struct built {
+    bool wrap;
+  };
+
+  /**
+   * Resolve an index that cannot be read as requested to the next one that can,
+   * instead of failing with @ref errc::key_value::replica_index_out_of_bounds or
+   * @ref errc::key_value::replica_index_currently_unavailable.
+   *
+   * The search walks the bucket's configured replica count, starting at the
+   * requested index modulo that count. An index beyond the vbucket map's
+   * current row therefore still reaches the replicas the row does list.
+   *
+   * Two failures remain. A bucket configured for no replicas reports
+   * @ref errc::key_value::replica_index_out_of_bounds. A full lap that finds
+   * nothing readable reports
+   * @ref errc::key_value::replica_index_currently_unavailable.
+   *
+   * Resolution follows the vbucket map, not node health: a replica the map
+   * places on a node is selected even when that node cannot be reached, and the
+   * operation retries against it until its timeout rather than moving on to
+   * another replica.
+   *
+   * @param value whether to wrap around the available replicas
+   * @return this options builder for chaining purposes.
+   *
+   * @since 1.5.0
+   * @committed
+   */
+  auto wrap(bool value) -> get_replica_strategy_from_index_options&
+  {
+    wrap_ = value;
+    return *this;
+  }
+
+  /**
+   * Returns the options as an immutable value.
+   *
+   * @return the options as an immutable value
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> built
+  {
+    return { wrap_ };
+  }
+
+private:
+  bool wrap_{ false };
+};
+
+/**
+ * Selects the replica that @ref collection#get_replica() reads from.
+ *
+ * @since 1.5.0
+ * @committed
+ */
+class get_replica_strategy
+{
+public:
+  /**
+   * Read from the replica at the given index.
+   *
+   * @param index the replica to read from
+   * @param options the custom options
+   * @return the strategy to pass to @ref collection#get_replica()
+   *
+   * @since 1.5.0
+   * @committed
+   */
+  [[nodiscard]] static auto from_index(replica_index index,
+                                       const get_replica_strategy_from_index_options& options = {})
+    -> get_replica_strategy
+  {
+    return get_replica_strategy{ static_cast<std::size_t>(index), options.build() };
+  }
+
+  /**
+   * Immutable value object representing a consistent strategy.
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  struct built {
+    std::size_t replica_index;
+    bool wrap;
+  };
+
+  /**
+   * Returns the strategy as an immutable value.
+   *
+   * @return the strategy as an immutable value
+   *
+   * @since 1.5.0
+   * @internal
+   */
+  [[nodiscard]] auto build() const -> built
+  {
+    return built_;
+  }
+
+private:
+  get_replica_strategy(std::size_t index,
+                       const get_replica_strategy_from_index_options::built& options)
+    : built_{ index, options.wrap }
+  {
+  }
+
+  built built_;
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/get_result.hxx

@@ -56,6 +56,7 @@ public:
    * @param cas
    * @param value raw document contents along with flags describing its structure
    * @param expiry_time optional point in time when the document will expire
+   * @param crypto_manager manager handed to the transcoder to decrypt encrypted fields
    *
    * @since 1.0.0
    * @committed

data/ext/couchbase/couchbase/increment_options.hxx

@@ -69,7 +69,7 @@ struct increment_options : public common_durability_options<increment_options> {
    * Sets the expiry for the document. By default the document will never expire.
    *
    * The duration must be less than 50 years. For expiry further in the future, use
-   * {@link #expiry(std::chrono::system_clock::time_point)}.
+   * {@link #expiry expiry(std::chrono::system_clock::time_point)}.
    *
    * @param duration the duration after which the document will expire (zero duration means never
    * expire).

data/ext/couchbase/couchbase/insert_options.hxx

@@ -70,7 +70,7 @@ struct insert_options : public common_durability_options<insert_options> {
    * Sets the expiry for the document. By default the document will never expire.
    *
    * The duration must be less than 50 years. For expiry further in the future, use
-   * {@link #expiry(std::chrono::system_clock::time_point)}.
+   * {@link #expiry expiry(std::chrono::system_clock::time_point)}.
    *
    * @param duration the duration after which the document will expire (zero duration means never
    * expire).

data/ext/couchbase/couchbase/match_phrase_query.hxx

@@ -39,7 +39,7 @@ namespace couchbase
  * Following this processing, the tokens `"locat"` and
  * `"function"` are recognized as common to both input and target; and also as being both in the
  * same sequence as, and at the same distance from one another; and therefore a match is made.
- * @snippet{trimleft} test_unit_search.cxx search-match-phrase
+ * @snippet{trimleft} unit/management/search.cxx search-match-phrase
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-match-phrase.html
  *

data/ext/couchbase/couchbase/match_query.hxx

@@ -33,7 +33,7 @@ namespace couchbase
  *
  * Match documents with both `"location"` and `"hostel"` terms in the field `reviews.content`,
  * ensuring common prefix length `4`, maximum fuzziness and select standard analyzer.
- * @snippet{trimleft} test_unit_search.cxx search-match
+ * @snippet{trimleft} unit/management/search.cxx search-match
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-match.html server
  * documentation

data/ext/couchbase/couchbase/mutate_in_options.hxx

@@ -80,8 +80,8 @@ struct mutate_in_options : public common_durability_options<mutate_in_options> {
    *
    * If true, and the document exists, its expiry will not be modified. Otherwise the document's
    * expiry is determined by
-   * {@link #expiry(std::chrono::seconds)} or {@link
-   * #expiry(std::chrono::system_clock::time_point)}.
+   * {@link #expiry expiry(std::chrono::seconds)} or {@link #expiry
+   * expiry(std::chrono::system_clock::time_point)}.
    *
    * Requires Couchbase Server 7.0 or later.
    *
@@ -101,7 +101,7 @@ struct mutate_in_options : public common_durability_options<mutate_in_options> {
    * Sets the expiry for the document. By default the document will never expire.
    *
    * The duration must be less than 50 years. For expiry further in the future, use
-   * {@link #expiry(std::chrono::system_clock::time_point)}.
+   * {@link #expiry expiry(std::chrono::system_clock::time_point)}.
    *
    * @param duration the duration after which the document will expire (zero duration means never
    * expire).

data/ext/couchbase/couchbase/network_options.hxx

@@ -38,7 +38,7 @@ public:
   /**
    * Selects network to use.
    *
-   * @param name network name as it is exposed in the configuration.
+   * @param network_name network name as it is exposed in the configuration.
    * @return this object for chaining purposes.
    *
    * @see

data/ext/couchbase/couchbase/node_id.hxx

@@ -1,6 +1,6 @@
 /* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
 /*
- *   Copyright 2024-Present 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.
@@ -25,13 +25,13 @@ namespace couchbase
 {
 
 /**
- * Uniquely identifies a cluster node.
+ * @brief Identifies a cluster node.
  *
  * On Couchbase Server 8.0.1+ the identifier is the server-assigned node UUID.
  * On older releases, a stable opaque token is derived from the node's hostname
- * and management port.
+ * and KV port.
  *
- * The type is equality-comparable, ordered, and hashable.
+ * The type is equality-comparable, totally ordered, and hashable.
  *
  * @since 1.3.2
  * @uncommitted
@@ -42,23 +42,33 @@ public:
   /**
    * Creates an empty (invalid) node_id.
    *
+   * @see operator bool()
+   *
    * @since 1.3.2
    * @uncommitted
    */
   node_id() = default;
 
+  // Copy and move are noexcept: all members (std::string + std::uint16_t)
+  // have noexcept moves on every conforming implementation.
+  node_id(const node_id&) = default;
+  node_id(node_id&&) noexcept = default;
+  auto operator=(const node_id&) -> node_id& = default;
+  auto operator=(node_id&&) noexcept -> node_id& = default;
+  ~node_id() = default;
+
   /**
    * User-facing identifier string.
    *
    * Returns node_uuid when the server provides one, otherwise a stable
-   * hex-encoded hash derived from hostname and management port.
+   * hex-encoded hash derived from hostname and KV port.
    *
    * @return opaque identifier string (empty for default-constructed instances)
    *
    * @since 1.3.2
    * @uncommitted
    */
-  [[nodiscard]] auto id() const -> const std::string&;
+  [[nodiscard]] auto id() const noexcept -> const std::string&;
 
   /**
    * The server-assigned node UUID (empty on servers before 8.0.1).
@@ -66,7 +76,7 @@ public:
    * @since 1.3.2
    * @uncommitted
    */
-  [[nodiscard]] auto node_uuid() const -> const std::string&;
+  [[nodiscard]] auto node_uuid() const noexcept -> const std::string&;
 
   /**
    * The hostname of the node.
@@ -74,18 +84,20 @@ public:
    * @since 1.3.2
    * @uncommitted
    */
-  [[nodiscard]] auto hostname() const -> const std::string&;
+  [[nodiscard]] auto hostname() const noexcept -> const std::string&;
 
   /**
    * The port of the node's key-value service.
    *
    * This reflects the port actually used by the client: the TLS port when the
-   * cluster connection is TLS-enabled, otherwise the plain port.
+   * cluster connection is TLS-enabled, otherwise the plain port. A value of
+   * @c 0 indicates the port is unknown or the node is not bound; in that case
+   * @c operator @c bool() also returns @c false.
    *
    * @since 1.3.2
    * @uncommitted
    */
-  [[nodiscard]] auto port() const -> std::uint16_t;
+  [[nodiscard]] auto port() const noexcept -> std::uint16_t;
 
   /**
    * Returns true when the node_id was properly initialized (not default-constructed).
@@ -93,13 +105,25 @@ public:
    * @since 1.3.2
    * @uncommitted
    */
-  explicit operator bool() const;
+  [[nodiscard]] explicit operator bool() const noexcept;
 
-  auto operator==(const node_id& other) const -> bool;
-  auto operator!=(const node_id& other) const -> bool;
-  auto operator<(const node_id& other) const -> bool;
+  /** @since 1.3.2 @uncommitted */
+  [[nodiscard]] auto operator==(const node_id& other) const noexcept -> bool;
+  /** @since 1.3.2 @uncommitted */
+  [[nodiscard]] auto operator!=(const node_id& other) const noexcept -> bool;
+  /** @since 1.3.2 @uncommitted */
+  [[nodiscard]] auto operator<(const node_id& other) const noexcept -> bool;
+  /** @since 1.3.2 @uncommitted */
+  [[nodiscard]] auto operator<=(const node_id& other) const noexcept -> bool;
+  /** @since 1.3.2 @uncommitted */
+  [[nodiscard]] auto operator>(const node_id& other) const noexcept -> bool;
+  /** @since 1.3.2 @uncommitted */
+  [[nodiscard]] auto operator>=(const node_id& other) const noexcept -> bool;
 
 private:
+  // Construction from core-level data is restricted to internal_node_id,
+  // declared in core/impl/node_id.hxx. Public users cannot construct node_id
+  // directly.
   friend class internal_node_id;
 
   node_id(std::string node_uuid, std::string hostname, std::uint16_t port);
@@ -116,6 +140,10 @@ private:
 
 template<>
 struct std::hash<couchbase::node_id> {
+  // Hashes the full id_ string. For the fallback case id_ is 8 hex chars;
+  // for a server-assigned UUID it is typically 32-36 chars. The cost is well
+  // under 100ns per lookup and not on a critical path; if profiling shows
+  // otherwise, cache the hash on node_id and return it from a friend accessor.
   auto operator()(const couchbase::node_id& nid) const noexcept -> std::size_t
   {
     return std::hash<std::string>{}(nid.id());

data/ext/couchbase/couchbase/node_id_for_options.hxx

@@ -27,7 +27,7 @@ namespace couchbase
 {
 
 /**
- * Options for @ref collection#node_id_for().
+ * Options for @ref couchbase::collection::node_id_for().
  *
  * @since 1.3.2
  * @uncommitted
@@ -56,6 +56,12 @@ struct node_id_for_options : public common_options<node_id_for_options> {
   }
 };
 
+/**
+ * Handler signature for @ref couchbase::collection::node_id_for().
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
 using node_id_for_handler = std::function<void(error, node_id)>;
 
 } // namespace couchbase

data/ext/couchbase/couchbase/node_ids_options.hxx

@@ -1,6 +1,6 @@
 /* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
 /*
- *   Copyright 2024-Present 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.
@@ -28,7 +28,7 @@ namespace couchbase
 {
 
 /**
- * Options for @ref collection#node_ids().
+ * Options for @ref couchbase::collection::node_ids().
  *
  * @since 1.3.2
  * @uncommitted
@@ -57,6 +57,12 @@ struct node_ids_options : public common_options<node_ids_options> {
   }
 };
 
+/**
+ * Handler signature for @ref couchbase::collection::node_ids().
+ *
+ * @since 1.3.2
+ * @uncommitted
+ */
 using node_ids_handler = std::function<void(error, std::vector<node_id>)>;
 
 } // namespace couchbase

data/ext/couchbase/couchbase/numeric_range_query.hxx

@@ -34,7 +34,7 @@ namespace couchbase
  *
  * Match documents where field `id` contains numbers in the range `(100, 1000)`:
  *
- * @snippet{trimleft} test_unit_search.cxx search-numeric-range
+ * @snippet{trimleft} unit/management/search.cxx search-numeric-range
  *
  * @since 1.0.0
  * @committed

data/ext/couchbase/couchbase/phrase_query.hxx

@@ -34,7 +34,7 @@ namespace couchbase
  * @ref match_phrase_query should usually be preferred for real-world use cases.
  *
  * Match documents with terms `"nice"` and `"view"` in field `reviews.content`:
- * @snippet{trimleft} test_unit_search.cxx search-phrase
+ * @snippet{trimleft} unit/management/search.cxx search-phrase
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-phrase.html server
  * documentation

data/ext/couchbase/couchbase/prefix_query.hxx

@@ -30,7 +30,7 @@ namespace couchbase
  * @ref match_query.
  *
  * Match documents where field `reviews.content` contains words starting with `"inter"`:
- * @snippet{trimleft} test_unit_search.cxx search-prefix
+ * @snippet{trimleft} unit/management/search.cxx search-prefix
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-prefix-query.html server
  * documentation

data/ext/couchbase/couchbase/query_options.hxx

@@ -23,6 +23,7 @@
 #include <couchbase/query_profile.hxx>
 #include <couchbase/query_result.hxx>
 #include <couchbase/query_scan_consistency.hxx>
+#include <couchbase/query_stream_result.hxx>
 
 #include <chrono>
 #include <functional>
@@ -136,8 +137,9 @@ struct query_options : public common_options<query_options> {
    *
    * If this method is set to true, the server will send metrics back to the client which are
    * available through the
-   * {@link query_meta_data#metrics()} section. As opposed to {@link #profile(query_profile)},
-   * returning metrics is rather cheap and can also be enabled in production if needed.
+   * {@link query_meta_data#metrics()} section. As opposed to {@link #profile
+   * profile(query_profile)}, returning metrics is rather cheap and can also be enabled in
+   * production if needed.
    *
    * @param metrics set to true if the server should return simple query metrics.
    * @return this options builder for chaining purposes.
@@ -384,10 +386,11 @@ struct query_options : public common_options<query_options> {
    * mutations. If you want to include all the mutations up to the point of the query, use {@link
    * query_scan_consistency::request_plus}.
    *
-   * Note that you cannot use this method and {@link #consistent_with(const mutation_state&)} at the
-   * same time, since they are mutually exclusive. As a rule of thumb, if you only care to be
-   * consistent with the mutation you just wrote on the same thread/app, use
-   * {@link #consistent_with(const mutation_state&)}. If you need "global" scan consistency, use
+   * Note that you cannot use this method and {@link #consistent_with consistent_with(const
+   * mutation_state&)} at the same time, since they are mutually exclusive. As a rule of thumb, if
+   * you only care to be consistent with the mutation you just wrote on the same thread/app, use
+   * {@link #consistent_with consistent_with(const mutation_state&)}. If you need "global" scan
+   * consistency, use
    * {@link query_scan_consistency::request_plus} on this method.
    *
    * @param scan_consistency the index scan consistency to be used for this query
@@ -410,12 +413,12 @@ struct query_options : public common_options<query_options> {
    * and if you want your N1QL query to include those you need to pass the mutation tokens into a
    * {@link mutation_state}.
    *
-   * Note that you cannot use this method and {@link #scan_consistency(query_scan_consistency)} at
-   * the same time, since they are mutually exclusive. As a rule of thumb, if you only care to be
-   * consistent with the mutation you just wrote on the same thread/app, use this method. If you
-   * need "global" scan consistency, use
-   * {@link query_scan_consistency#request_plus} on {@link
-   * #scan_consistency(query_scan_consistency)}.
+   * Note that you cannot use this method and {@link #scan_consistency
+   * scan_consistency(query_scan_consistency)} at the same time, since they are mutually exclusive.
+   * As a rule of thumb, if you only care to be consistent with the mutation you just wrote on the
+   * same thread/app, use this method. If you need "global" scan consistency, use
+   * {@link query_scan_consistency#request_plus} on {@link #scan_consistency
+   * scan_consistency(query_scan_consistency)}.
    *
    * @param state the mutation state containing the mutation tokens.
    * @return this options builder for chaining purposes.
@@ -675,4 +678,12 @@ private:
  * @uncommitted
  */
 using query_handler = std::function<void(error, query_result)>;
+
+/**
+ * The signature for the handler of a streaming query operation.
+ *
+ * @since 1.4.0
+ * @volatile
+ */
+using query_stream_handler = std::function<void(error, query_stream_result)>;
 } // namespace couchbase