couchbase 3.8.2 → 3.9.0

data/ext/couchbase/core/utils/url_codec.cxx

@@ -73,7 +73,7 @@ is_already_escape(T first, T last) -> bool
   ++first; // ignore '%'
   std::size_t jj = 0;
   for (; first != last && jj < 2; ++jj, ++first) {
-    if (!isxdigit(*first)) {
+    if (isxdigit(static_cast<unsigned char>(*first)) == 0) {
       return false;
     }
   }
@@ -81,57 +81,22 @@ is_already_escape(T first, T last) -> bool
 }
 } // namespace priv
 
+// Each byte is decided on its own: with check_encoded, an existing %XX escape is copied as is, a
+// legal URI character is copied, and every other byte is written as %XX.
 template<typename Ti, typename To>
-auto
-url_encode(Ti first, Ti last, To& o, bool check_encoded = true) -> bool
+void
+url_encode(Ti first, Ti last, To& o, bool check_encoded = true)
 {
-  // If re-encoding detection is enabled, this flag indicates not to
-  // re-encode
-  bool skip_encoding = false;
-
   for (; first != last; ++first) {
-    if (!skip_encoding && check_encoded) {
-      if (*first == '%') {
-        skip_encoding = priv::is_already_escape(first, last);
-      } else if (*first == '+') {
-        skip_encoding = true;
-      }
-    }
-    if (skip_encoding || priv::is_legal_uri_char(*first)) {
-      if (skip_encoding && *first != '%' && !priv::is_legal_uri_char(*first)) {
-        return false;
-      }
-
+    if (check_encoded && *first == '%' && priv::is_already_escape(first, last)) {
+      o.insert(o.end(), first, first + 3);
+      first += 2;
+    } else if (priv::is_legal_uri_char(*first)) {
       o.insert(o.end(), first, first + 1);
     } else {
-      const unsigned int c = static_cast<unsigned char>(*first);
-      std::size_t numbytes = 0;
-
-      if ((c & 0x80) == 0) { /* ASCII character */
-        numbytes = 1;
-      } else if ((c & 0xE0) == 0xC0) { /* 110x xxxx */
-        numbytes = 2;
-      } else if ((c & 0xF0) == 0xE0) { /* 1110 xxxx */
-        numbytes = 3;
-      } else if ((c & 0xF8) == 0xF0) { /* 1111 0xxx */
-        numbytes = 4;
-      } else {
-        return false;
-      }
-
-      do {
-        o.append(fmt::format("%{:x}", static_cast<std::uint8_t>(*first)));
-      } while (--numbytes && ++first != last);
+      o.append(fmt::format("%{:02x}", static_cast<std::uint8_t>(*first)));
     }
   }
-  return true;
-}
-
-template<typename Tin, typename Tout>
-auto
-url_encode(const Tin& in, Tout& out) -> bool
-{
-  return url_encode(in.begin(), in.end(), out);
 }
 
 auto
@@ -212,18 +177,14 @@ form_encode(Ti first, Ti last, To& out)
 {
   for (; first != last; ++first) {
     auto c = static_cast<unsigned char>(*first);
-    if (isalnum(c)) {
-      out.insert(out.end(), first, first + 1);
-      continue;
-    }
     if (c == ' ') {
       char tmp = '+';
       out.insert(out.end(), &tmp, &tmp + 1);
     } else if ((c == 0x2A || c == 0x2D || c == 0x2E) || (c >= 0x30 && c <= 0x39) ||
-               (c >= 0x41 && c <= 0x5A) || (c == 0x5F) || (c >= 0x60 && c <= 0x7A)) {
+               (c >= 0x41 && c <= 0x5A) || (c == 0x5F) || (c >= 0x61 && c <= 0x7A)) {
       out.insert(out.end(), static_cast<char>(c));
     } else {
-      out.append(fmt::format("%{:x}", static_cast<std::uint8_t>(*first)));
+      out.append(fmt::format("%{:02x}", static_cast<std::uint8_t>(*first)));
     }
   }
 }

data/ext/couchbase/core/websocket_codec.cxx

@@ -16,6 +16,7 @@
 #include "websocket_codec.hxx"
 
 #include "core/crypto/cbcrypto.h"
+#include "core/mcbp/big_endian.hxx"
 #include "core/platform/base64.h"
 #include "core/platform/random.h"
 
@@ -25,7 +26,6 @@
 #include <algorithm>
 #include <array>
 #include <cstdint>
-#include <cstring>
 #include <map>
 #include <optional>
 #include <random>
@@ -456,32 +456,6 @@ encode_payload_length(std::size_t length) -> std::vector<std::byte>
   };
 }
 
-auto
-decode_uint64(gsl::span<std::byte> data) -> std::uint64_t
-{
-  std::uint64_t result{};
-  std::memcpy(&result, data.data(), sizeof(result));
-
-  return                                  //
-    (result & 0x00000000000000FF) << 56 | //
-    (result & 0x000000000000FF00) << 40 | //
-    (result & 0x0000000000FF0000) << 24 | //
-    (result & 0x00000000FF000000) << 8 |  //
-    (result & 0x000000FF00000000) >> 8 |  //
-    (result & 0x0000FF0000000000) >> 24 | //
-    (result & 0x00FF000000000000) >> 40 | //
-    (result & 0xFF00000000000000) >> 56;
-}
-
-auto
-decode_uint16(gsl::span<std::byte> data) -> std::uint16_t
-{
-  std::uint16_t result{};
-  std::memcpy(&result, data.data(), sizeof(result));
-
-  return static_cast<std::uint16_t>(result << 8 | result >> 8);
-}
-
 auto
 decode_frame(gsl::span<std::byte> data, bool expected_continuation) -> decode_status
 {
@@ -519,7 +493,7 @@ decode_frame(gsl::span<std::byte> data, bool expected_continuation) -> decode_st
         return need_more_data{};
       }
       header_length = 10;
-      payload_length = decode_uint64(data.subspan(2, sizeof(std::uint64_t)));
+      payload_length = mcbp::big_endian::read_uint64(data, 2);
       break;
 
     case 126:
@@ -527,7 +501,7 @@ decode_frame(gsl::span<std::byte> data, bool expected_continuation) -> decode_st
         return need_more_data{};
       }
       header_length = 4;
-      payload_length = decode_uint16(data.subspan(2, sizeof(std::uint16_t)));
+      payload_length = mcbp::big_endian::read_uint16(data, 2);
       break;
 
     default:

data/ext/couchbase/couchbase/analytics_options.hxx

@@ -19,6 +19,7 @@
 
 #include <couchbase/analytics_result.hxx>
 #include <couchbase/analytics_scan_consistency.hxx>
+#include <couchbase/analytics_stream_result.hxx>
 #include <couchbase/common_options.hxx>
 #include <couchbase/error.hxx>
 #include <couchbase/mutation_state.hxx>
@@ -181,10 +182,11 @@ struct analytics_options : public common_options<analytics_options> {
    * mutations. If you want to include all the mutations up to the point of the query, use {@link
    * analytics_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 analytics_scan_consistency::request_plus} on this method.
    *
    * @param scan_consistency the index scan consistency to be used for this query
@@ -207,12 +209,12 @@ struct analytics_options : public common_options<analytics_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(analytics_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 analytics_scan_consistency#request_plus} on {@link
-   * #scan_consistency(analytics_scan_consistency)}.
+   * Note that you cannot use this method and {@link #scan_consistency
+   * scan_consistency(analytics_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 analytics_scan_consistency#request_plus} on {@link #scan_consistency
+   * scan_consistency(analytics_scan_consistency)}.
    *
    * @param state the mutation state containing the mutation tokens.
    * @return this options builder for chaining purposes.
@@ -463,4 +465,13 @@ private:
  * @uncommitted
  */
 using analytics_handler = std::function<void(error, analytics_result)>;
+
+/**
+ * The signature for the handler of the @ref cluster#analytics_query_stream() and @ref
+ * scope#analytics_query_stream() operations
+ *
+ * @since 1.4.0
+ * @volatile
+ */
+using analytics_stream_handler = std::function<void(error, analytics_stream_result)>;
 } // namespace couchbase

data/ext/couchbase/couchbase/analytics_row.hxx

@@ -0,0 +1,105 @@
+/* -*- 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/encoded_value.hxx>
+#include <couchbase/codec/serializer_traits.hxx>
+#include <utility>
+
+namespace couchbase
+{
+
+namespace codec
+{
+class tao_json_serializer;
+} // namespace codec
+
+/**
+ * Represents a single row of a streaming analytics result.
+ *
+ * The raw JSON bytes can be decoded via @ref content_as().
+ *
+ * @since 1.4.0
+ * @volatile
+ */
+class analytics_row
+{
+public:
+  /**
+   * @since 1.4.0
+   * @volatile
+   */
+  analytics_row() = default;
+
+  /**
+   * Constructs a row from raw JSON bytes.
+   *
+   * @param content raw JSON bytes for this row
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  explicit analytics_row(codec::binary content)
+    : content_{ std::move(content) }
+  {
+  }
+
+  /**
+   * Decodes the row content into the requested document type using the given serializer.
+   *
+   * Only call this on a row obtained from a successful @ref analytics_stream_result#next() (falsy
+   * error, engaged optional). The end-of-stream and error sentinels carry an empty @ref
+   * analytics_row, and decoding empty/malformed content throws the serializer's parse exception —
+   * gate on the three-state next() contract (check the error, then the optional) before decoding.
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-analytics-stream
+   *
+   * @tparam Serializer the serializer to use (defaults to @ref codec::tao_json_serializer)
+   * @tparam Document the document type to decode into (defaults to the serializer's document_type)
+   * @return the decoded document
+   * @throws the serializer's deserialization exception if the content is empty or not valid JSON
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  template<typename Serializer = codec::tao_json_serializer,
+           typename Document = typename Serializer::document_type,
+           std::enable_if_t<codec::is_serializer_v<Serializer>, bool> = true>
+  [[nodiscard]] auto content_as() const -> Document
+  {
+    return Serializer::template deserialize<Document>(content_);
+  }
+
+  /**
+   * Returns the raw binary content of this row.
+   *
+   * @return raw JSON bytes
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto content_as_binary() const -> const codec::binary&
+  {
+    return content_;
+  }
+
+private:
+  codec::binary content_{};
+};
+
+} // namespace couchbase

data/ext/couchbase/couchbase/analytics_stream_result.hxx

@@ -0,0 +1,266 @@
+/* -*- Mode: C++; tab-width: 4; c-basic-offset: 4; indent-tabs-mode: nil -*- */
+/*
+ *   Copyright 2026. Couchbase, Inc.
+ *
+ *   Licensed under the Apache License, Version 2.0 (the "License");
+ *   you may not use this file except in compliance with the License.
+ *   You may obtain a copy of the License at
+ *
+ *       http://www.apache.org/licenses/LICENSE-2.0
+ *
+ *   Unless required by applicable law or agreed to in writing, software
+ *   distributed under the License is distributed on an "AS IS" BASIS,
+ *   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ *   See the License for the specific language governing permissions and
+ *   limitations under the License.
+ */
+
+#pragma once
+
+#include <couchbase/analytics_meta_data.hxx>
+#include <couchbase/analytics_row.hxx>
+#include <couchbase/codec/encoded_value.hxx>
+#include <couchbase/error.hxx>
+
+#include <functional>
+#include <future>
+#include <memory>
+#include <optional>
+#include <utility>
+
+namespace couchbase
+{
+#ifndef COUCHBASE_CXX_CLIENT_DOXYGEN
+class internal_analytics_stream_result;
+#endif
+
+/**
+ * The signature for the handler of the @ref analytics_stream_result#next() operation.
+ *
+ * @since 1.4.0
+ * @volatile
+ */
+using analytics_row_handler = std::function<void(error, std::optional<analytics_row>)>;
+
+/**
+ * A streaming result handle for analytics queries.
+ *
+ * Rows are fetched one at a time via @ref next(). The stream must be fully drained
+ * (or @ref cancel() called) before @ref meta_data() resolves. Only a single @ref next()
+ * call may be outstanding at a time.
+ *
+ * @snippet{trimleft} test_integration_examples_streaming.cxx example-analytics-stream
+ *
+ * @note The future-returning overloads (`next()`, `meta_data()`) and the eager @ref iterator
+ * block the calling thread until the result is ready. They must not be called from within an SDK
+ * completion handler (i.e. the library's I/O thread) — doing so blocks that thread against itself
+ * and the stream can never advance. From a completion handler, use the callback @ref next()
+ * overload instead.
+ *
+ * @note Copies of a result handle share one underlying stream: they alias the same rows, the same
+ * single-outstanding-next() budget, and the same @ref cancel(). Copying does not fork the stream;
+ * a @ref next() on any copy consumes the next row for all of them. Use a single handle per stream.
+ *
+ * @since 1.4.0
+ * @volatile
+ */
+class analytics_stream_result
+{
+public:
+  /**
+   * Constructs an empty (no-op) result handle.
+   *
+   * @since 1.4.0
+   * @internal
+   */
+  analytics_stream_result() = default;
+
+  /**
+   * Constructs an analytics stream result from an internal result.
+   *
+   * @param internal the internal result handle
+   *
+   * @since 1.4.0
+   * @internal
+   */
+  explicit analytics_stream_result(std::shared_ptr<internal_analytics_stream_result> internal);
+
+  /**
+   * Fetches the next row asynchronously, invoking the handler when ready.
+   *
+   * The handler receives ({}, row) for a real row, ({}, {}) at clean end-of-stream,
+   * or (error, {}) if the stream ended with an error.
+   *
+   * Only one outstanding call is allowed at a time.
+   *
+   * @param handler callable that implements @ref analytics_row_handler
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  void next(analytics_row_handler&& handler) const;
+
+  /**
+   * Fetches the next row, returning a future.
+   *
+   * Only one outstanding call is allowed at a time.
+   *
+   * @return future object that carries the result of the operation
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto next() const -> std::future<std::pair<error, std::optional<analytics_row>>>;
+
+  /**
+   * Returns the analytics signature captured from the response metadata, if present.
+   *
+   * The signature is part of the response preamble, so — unlike @ref meta_data() — it is available
+   * as soon as the stream has started, without draining it first:
+   *
+   * @snippet{trimleft} test_integration_examples_streaming.cxx example-analytics-stream
+   *
+   * @return optional binary JSON signature
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto signature() const -> std::optional<codec::binary>;
+
+  /**
+   * Returns the analytics metadata.
+   *
+   * The returned future resolves only after the stream has been fully drained
+   * (all rows consumed or the stream cancelled). May be called more than once;
+   * each call returns its own future and all of them resolve together once the
+   * metadata becomes available.
+   *
+   * @return future carrying (error, analytics_meta_data)
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto meta_data() const -> std::future<std::pair<error, analytics_meta_data>>;
+
+  /**
+   * Cancels the stream and closes the underlying HTTP connection.
+   *
+   * Simply dropping the last handle before the stream is fully drained also tears the stream down,
+   * but if a pull is in flight the underlying connection is not released until that pull settles
+   * (up to the inter-read idle timeout). Call cancel() explicitly for prompt, deterministic
+   * teardown of the connection and its timers.
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  void cancel() const;
+
+  /**
+   * Sentinel returned by @ref end(). An @ref iterator compares equal to it once the stream has been
+   * fully drained (after any terminal error element). Using a distinct end type means iterators are
+   * only ever compared against the end sentinel, never against one another.
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  struct end_sentinel {
+  };
+
+  /**
+   * A single-pass input iterator that synchronously fetches rows one at a time.
+   *
+   * Dereferencing yields `std::pair<error, analytics_row>`: for a data row the error is falsy; if
+   * the stream ends with an error, the iterator visits exactly one final element whose error is
+   * truthy (and whose row is empty) before comparing equal to @ref end(). A clean end-of-stream
+   * yields no such element. This guarantees a `for (auto [err, row] : result)` loop can observe a
+   * terminal error rather than silently stopping.
+   *
+   * This is a minimal single-pass iterator intended for range-based for and manual
+   * `while (it != result.end())` loops. It compares only against @ref end() (never against another
+   * iterator), and provides neither `operator->` nor post-increment, so it is deliberately not a
+   * `LegacyInputIterator` and does not work with `<algorithm>` or `std::distance`. @ref begin()
+   * must be called once.
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  class iterator
+  {
+  public:
+    auto operator*() const -> std::pair<error, analytics_row>;
+    auto operator++() -> iterator&;
+
+    /**
+     * Constructs an iterator over an internal result; prefer @ref begin().
+     *
+     * @since 1.4.0
+     * @internal
+     */
+    explicit iterator(std::shared_ptr<internal_analytics_stream_result> internal);
+
+    /**
+     * Compares an iterator against the end sentinel. Provided in both argument orders (and as
+     * both @c == and @c !=) so the range-for idiom, `while (it != result.end())` loops, and wrapper
+     * code all work regardless of which operand is written first. Iterators are intentionally never
+     * comparable to one another: a single-pass stream has one position, so iterator-to-iterator
+     * equality would be meaningless — the type only ever compares against @ref end().
+     */
+    friend auto operator==(const iterator& it, end_sentinel /* end */) -> bool
+    {
+      return it.terminal_;
+    }
+    friend auto operator==(end_sentinel end, const iterator& it) -> bool
+    {
+      return it == end;
+    }
+    friend auto operator!=(const iterator& it, end_sentinel end) -> bool
+    {
+      return !(it == end);
+    }
+    friend auto operator!=(end_sentinel end, const iterator& it) -> bool
+    {
+      return !(it == end);
+    }
+
+    // Intentionally no std::iterator_traits typedefs (notably no iterator_category). This is a
+    // deliberately minimal single-pass iterator for range-based for and `while (it !=
+    // result.end())` loops only (see the class doc); it omits post-increment and operator->.
+    // Declaring an input_iterator_tag while omitting those would falsely advertise
+    // LegacyInputIterator / std::input_iterator conformance and could break generic code that
+    // trusts iterator_traits. Range-based for needs none of these typedefs.
+
+  private:
+    void fetch_item();
+
+    std::shared_ptr<internal_analytics_stream_result> internal_{};
+    std::pair<error, analytics_row> item_{};
+    bool terminal_{ false };
+    // Set when fetch_item() lands on a terminal error: the error element is delivered once (the
+    // iterator is not yet equal to end()), and the next increment advances to true end.
+    bool error_pending_{ false };
+  };
+
+  /**
+   * Returns an iterator to the beginning.
+   *
+   * @return iterator to the first row
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto begin() const -> iterator;
+
+  /**
+   * Returns the end sentinel.
+   *
+   * @return sentinel that an @ref iterator compares equal to once the stream is drained
+   *
+   * @since 1.4.0
+   * @volatile
+   */
+  [[nodiscard]] auto end() const -> end_sentinel;
+
+private:
+  std::shared_ptr<internal_analytics_stream_result> internal_{};
+};
+} // namespace couchbase

data/ext/couchbase/couchbase/boolean_query.hxx

@@ -47,11 +47,11 @@ namespace couchbase
  * In the example below the following rules enforced by the boolean query:
  * * retrieved documents MUST match `"hostel room"` in their `reviews.content` field AND have `true`
  * in `free_breakfast` field.
- * * also the documents SHOULD have EITHER `reviews.ratings.Overall > 4` OR `reviews.ratings.Service
- * > 5`.
+ * * also the documents SHOULD have EITHER `reviews.ratings.Overall > 4` OR
+ * `reviews.ratings.Service > 5`.
  * * and finally, exclude documents with `city` `"Padfield"` or `"Gilingham"`.
  *
- * @snippet{trimleft} test_unit_search.cxx search-boolean
+ * @snippet{trimleft} unit/management/search.cxx search-boolean
  *
  * @see https://docs.couchbase.com/server/current/fts/fts-supported-queries-boolean-field-query.html
  * server documentation

data/ext/couchbase/couchbase/bucket.hxx

@@ -21,7 +21,9 @@
 #include <couchbase/collection_manager.hxx>
 #include <couchbase/ping_options.hxx>
 #include <couchbase/scope.hxx>
+#include <couchbase/wait_until_ready_options.hxx>
 
+#include <chrono>
 #include <memory>
 
 namespace couchbase
@@ -88,8 +90,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 opens no per-bucket
+   * sessions 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;
 
@@ -102,12 +109,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 opens no per-bucket
+   * sessions 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>>;
 
+  /**
+   * Waits until the desired state of the bucket is reached, actively pinging its services until
+   * they respond or the timeout elapses.
+   *
+   * When the desired state is @c cluster_state::online, this additionally waits until the bucket's
+   * vbucket map is fully placed -- every vbucket has its active and all replica copies assigned to
+   * a node. That is the readiness durable writes require and that a freshly created bucket does not
+   * satisfy immediately. The @c cluster_state::degraded target is ping-only, since it deliberately
+   * tolerates partial availability.
+   *
+   * Over couchbase2, the wait ends once the gRPC channel to the gateway is connected. Neither the
+   * bucket nor the credentials are checked, 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 bucket is reached.
+   *
+   * @see wait_until_ready(std::chrono::milliseconds, const wait_until_ready_options&,
+   * wait_until_ready_handler&&) const
+   *
+   * @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 collection management services.
    *