couchbase 3.8.2 → 3.9.0

data/ext/couchbase/core/http_component.hxx

@@ -49,11 +49,7 @@ public:
                  std::shared_ptr<retry_strategy> default_retry_strategy = {});
 
   auto do_http_request(const http_request& request, free_form_http_request_callback&& callback)
-#ifdef COUCHBASE_CXX_CLIENT_COLUMNAR
-    -> tl::expected<std::shared_ptr<pending_operation>, error_union>;
-#else
     -> tl::expected<std::shared_ptr<pending_operation>, std::error_code>;
-#endif
 
   auto do_http_request_buffered(const http_request& request,
                                 buffered_free_form_http_request_callback&& callback)

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

@@ -18,29 +18,36 @@
 #include "analytics.hxx"
 
 #include "core/analytics_scan_consistency.hxx"
+#include "core/analytics_stream.hxx"
+#include "core/cluster.hxx"
 #include "core/operations/document_analytics.hxx"
 #include "core/utils/binary.hxx"
+#include "error.hxx"
+#include "internal_analytics_stream_result.hxx"
+#include "observability_recorder.hxx"
 
 #include <couchbase/analytics_metrics.hxx>
 #include <couchbase/analytics_options.hxx>
 #include <couchbase/analytics_result.hxx>
 #include <couchbase/analytics_scan_consistency.hxx>
 #include <couchbase/analytics_status.hxx>
+#include <couchbase/analytics_stream_result.hxx>
 #include <couchbase/analytics_warning.hxx>
 #include <couchbase/codec/encoded_value.hxx>
+#include <couchbase/error.hxx>
 
 #include <cstddef>
+#include <memory>
 #include <optional>
+#include <system_error>
 #include <utility>
 #include <vector>
 
 namespace couchbase::core::impl
 {
-namespace
-{
-
 auto
-map_status(core::operations::analytics_response::analytics_status status) -> analytics_status
+map_analytics_status(core::operations::analytics_response::analytics_status status)
+  -> analytics_status
 {
   switch (status) {
     case core::operations::analytics_response::running:
@@ -67,6 +74,9 @@ map_status(core::operations::analytics_response::analytics_status status) -> ana
   return analytics_status::unknown;
 }
 
+namespace
+{
+
 auto
 map_scan_consistency(std::optional<couchbase::analytics_scan_consistency> consistency)
   -> std::optional<couchbase::core::analytics_scan_consistency>
@@ -136,7 +146,7 @@ build_result(core::operations::analytics_response& resp) -> analytics_result
     analytics_meta_data{
       std::move(resp.meta.request_id),
       std::move(resp.meta.client_context_id),
-      map_status(resp.meta.status),
+      map_analytics_status(resp.meta.status),
       map_warnings(resp),
       map_metrics(resp),
       map_signature(resp),
@@ -145,6 +155,29 @@ build_result(core::operations::analytics_response& resp) -> analytics_result
   };
 }
 
+void
+dispatch_analytics_stream(const core::cluster& core,
+                          core::operations::analytics_request request,
+                          std::unique_ptr<observability_recorder> obs_rec,
+                          analytics_stream_handler&& handler)
+{
+  core.analytics_query_stream(
+    std::move(request),
+    [obs_rec = std::move(obs_rec), handler = std::move(handler)](
+      core::analytics_stream stream, core::error_context::analytics ctx) mutable {
+      if (ctx.ec) {
+        obs_rec->finish(ctx.ec);
+        return handler(make_error(ctx), {});
+      }
+      // Transfer the recorder to the handle; it finishes the operation at the stream terminal. The
+      // context travels with it so a terminal error is reported with the same statement/endpoint
+      // detail as a failure to start, plus whatever the trailer said.
+      auto internal = std::make_shared<internal_analytics_stream_result>(
+        std::move(stream), std::move(obs_rec), std::move(ctx));
+      handler({}, analytics_stream_result{ std::move(internal) });
+    });
+}
+
 auto
 build_analytics_request(std::string statement,
                         analytics_options::built options,

data/ext/couchbase/core/impl/analytics.hxx

@@ -20,15 +20,49 @@
 #include "core/operations/document_analytics.hxx"
 
 #include <couchbase/analytics_options.hxx>
+#include <couchbase/analytics_status.hxx>
 
+#include <memory>
 #include <optional>
 #include <string>
 
+namespace couchbase::core
+{
+class cluster;
+} // namespace couchbase::core
+
 namespace couchbase::core::impl
 {
+class observability_recorder;
+
+/**
+ * Maps the core analytics status enum onto the public analytics_status enum. Shared by the buffered
+ * result builder and the streaming result handle so there is one source of truth.
+ */
+auto
+map_analytics_status(core::operations::analytics_response::analytics_status status)
+  -> analytics_status;
+
 auto
 build_result(core::operations::analytics_response& resp) -> analytics_result;
 
+/**
+ * Dispatches an analytics query as a streaming request and resolves the handler with an
+ * analytics_stream_result. Unlike query there is no prepared-statement fallback; every request
+ * takes the lazy streaming path.
+ *
+ * @param obs_rec the operation's observability recorder. Its operation span is already threaded
+ * into request.parent_span by the caller; ownership is transferred to the resulting stream handle,
+ * which calls finish() once when the stream reaches its terminal (drained, errored, or cancelled),
+ * so the streaming path emits the same operation span + latency metric as buffered
+ * analytics_query().
+ */
+void
+dispatch_analytics_stream(const core::cluster& core,
+                          core::operations::analytics_request request,
+                          std::unique_ptr<observability_recorder> obs_rec,
+                          analytics_stream_handler&& handler);
+
 auto
 build_analytics_request(std::string statement,
                         analytics_options::built options,

data/ext/couchbase/core/impl/bootstrap_error.hxx

@@ -20,7 +20,6 @@
 #include <optional>
 #include <string>
 #include <system_error>
-#include <variant>
 
 namespace couchbase::core
 {
@@ -37,6 +36,4 @@ struct bootstrap_error {
 
 } // namespace impl
 
-using error_union = std::variant<std::monostate, std::error_code, impl::bootstrap_error>;
-
 } // namespace couchbase::core

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

@@ -24,12 +24,15 @@
 #include "invoke_with_node_id.hxx"
 #include "observability_recorder.hxx"
 #include "observe_poll.hxx"
+#include "resolve_node_id.hxx"
+#include "with_bucket_config_or_timeout.hxx"
 
 #include "core/agent_group.hxx"
 #include "core/agent_group_config.hxx"
 #include "core/cluster.hxx"
 #include "core/impl/subdoc/command.hxx"
 #include "core/logger/logger.hxx"
+#include "core/logger/redaction.hxx"
 #include "core/metrics/meter_wrapper.hxx"
 #include "core/operations/document_append.hxx"
 #include "core/operations/document_decrement.hxx"
@@ -98,6 +101,7 @@
 #include <spdlog/fmt/bundled/core.h>
 
 #include <asio/error.hpp>
+#include <asio/post.hpp>
 #include <asio/steady_timer.hpp>
 
 #include <atomic>
@@ -328,6 +332,51 @@ public:
                          });
   }
 
+  void get_replica(std::string document_key,
+                   const get_replica_strategy::built& strategy,
+                   const get_replica_options::built& options,
+                   core::operations::movable_get_replica_handler&& handler) const
+  {
+    auto obs_rec = create_observability_recorder(core::tracing::operation::mcbp_get_replica,
+                                                 options.parent_span);
+
+    core::operations::get_replica_request request{
+      core::document_id{
+        bucket_name_,
+        scope_name_,
+        name_,
+        std::move(document_key),
+      },
+      options.timeout,
+      {},
+      {},
+      { options.retry_strategy },
+      obs_rec->operation_span(),
+      // The public strategy is translated here, so core carries no public type.
+      core::impl::replica_selection{ strategy.replica_index, strategy.wrap },
+    };
+    return core_.execute(std::move(request),
+                         [obs_rec = std::move(obs_rec),
+                          crypto_manager = crypto_manager_,
+                          handler = std::move(handler)](auto resp) mutable {
+                           // A document the replica does not hold reaches the
+                           // caller as document_not_found_on_replica, so that
+                           // is the error this operation is observed to have
+                           // produced. resp.ctx.ec() still carries the
+                           // document_not_found underneath it.
+                           auto error = core::impl::make_get_replica_error(resp.ctx);
+                           obs_rec->finish(resp.ctx.retry_attempts(), error.ec());
+                           invoke_with_node_id(std::move(handler),
+                                               std::move(error),
+                                               get_replica_result{
+                                                 resp.cas,
+                                                 true,
+                                                 { std::move(resp.value), resp.flags },
+                                                 std::move(crypto_manager),
+                                               });
+                         });
+  }
+
   void get_all_replicas(std::string document_key,
                         const get_all_replicas_options::built& options,
                         core::impl::movable_get_all_replicas_handler&& handler) const
@@ -346,25 +395,25 @@ public:
       options.read_preference,
       obs_rec->operation_span(),
     };
-    return core_.execute(std::move(request),
-                         [obs_rec = std::move(obs_rec),
-                          crypto_manager = crypto_manager_,
-                          handler = std::move(handler)](auto resp) mutable {
-                           get_all_replicas_result result{};
-                           for (auto& entry : resp.entries) {
-                             get_replica_result replica_result{
-                               entry.cas,
-                               entry.replica,
-                               { std::move(entry.value), entry.flags },
-                               crypto_manager,
-                             };
-                             replica_result.node_id(std::move(entry.dispatched_to_node_id));
-                             result.emplace_back(std::move(replica_result));
-                           }
-                           obs_rec->finish(resp.ctx.ec());
-                           return handler(core::impl::make_error(std::move(resp.ctx)),
-                                          std::move(result));
-                         });
+    return core_.execute(
+      std::move(request),
+      [obs_rec = std::move(obs_rec),
+       crypto_manager = crypto_manager_,
+       handler = std::move(handler)](auto resp) mutable {
+        get_all_replicas_result result{};
+        for (auto& entry : resp.entries) {
+          get_replica_result replica_result{
+            entry.cas,
+            entry.replica,
+            { std::move(entry.value), entry.flags },
+            crypto_manager,
+          };
+          replica_result.set_node_id_internal(std::move(entry.dispatched_to_node_id));
+          result.emplace_back(std::move(replica_result));
+        }
+        obs_rec->finish(resp.ctx.ec());
+        return handler(core::impl::make_error(std::move(resp.ctx)), std::move(result));
+      });
   }
 
   void remove(std::string document_key,
@@ -578,11 +627,8 @@ public:
       [obs_rec = std::move(obs_rec), handler = std::move(handler)](auto resp) mutable {
         obs_rec->finish(resp.ctx.retry_attempts(), resp.ctx.ec());
 
-        if (resp.ctx.ec()) {
-          invoke_with_node_id(
-            std::move(handler), core::impl::make_error(std::move(resp.ctx)), lookup_in_result{});
-          return;
-        }
+        // Don't short-circuit on ctx.ec(): document-level success with per-path failures is
+        // normal for subdoc; fields is empty on document-level error so the loop is a no-op.
 
         std::vector<lookup_in_result::entry> entries{};
         entries.reserve(resp.fields.size());
@@ -643,7 +689,7 @@ public:
             res.deleted,
             res.is_replica,
           };
-          replica_result.node_id(std::move(res.dispatched_to_node_id));
+          replica_result.set_node_id_internal(std::move(res.dispatched_to_node_id));
           result.emplace_back(std::move(replica_result));
         }
         obs_rec->finish(resp.ctx.ec());
@@ -1157,86 +1203,91 @@ public:
         break;
     }
 
-    return core_.open_bucket(
+    // Fetch the bucket configuration through the shared async scaffold rather than nesting
+    // open_bucket + with_bucket_configuration directly: the latter parks its continuation in the
+    // core (in the bucket-bootstrap window it is not drained on close), so capturing the moved
+    // scan_handler there would strand it -- a std::future caller would observe broken_promise and a
+    // callback caller would hang -- if the cluster is torn down mid-scan. The scaffold anchors the
+    // wait on an io_context timer and fails closed with errc::network::cluster_closed. Everything
+    // the continuation needs is captured by value (not `this`): the scan handler outlives
+    // collection_impl when the caller drops the collection but keeps the future, so a raw-`this`
+    // capture would be a use-after-free.
+    core::impl::with_bucket_config_or_timeout<std::shared_ptr<core::topology::configuration>>(
+      core_,
       bucket_name_,
-      [this,
-       obs_rec = std::move(obs_rec),
-       handler = std::move(handler),
+      orchestrator_opts.timeout,
+      [core = core_,
+       bucket_name = bucket_name_,
+       scope_name = scope_name_,
+       name = name_,
+       crypto_manager = crypto_manager_,
        orchestrator_opts,
-       core_scan_type](std::error_code ec) mutable {
-        if (ec) {
+       core_scan_type,
+       obs_rec = std::move(obs_rec),
+       handler = std::move(handler)](
+        couchbase::error err, std::shared_ptr<core::topology::configuration> config) mutable {
+        if (err.ec()) {
+          obs_rec->finish(err.ec());
+          return handler(
+            error(err.ec(), "An error occurred when attempting to fetch the bucket configuration."),
+            {});
+        }
+        if (!config->capabilities.supports_range_scan()) {
+          obs_rec->finish(errc::common::feature_not_available);
+          return handler(
+            error(errc::common::feature_not_available, "This bucket does not support range scan."),
+            {});
+        }
+        auto agent_group =
+          core::agent_group(core.io_context(), core::agent_group_config{ { core } });
+        if (auto ec = agent_group.open_bucket(bucket_name); ec) {
           obs_rec->finish(ec);
-          return handler(error(ec), {});
+          return handler(
+            error(ec, fmt::format("An error occurred while opening the `{}` bucket.", bucket_name)),
+            {});
+        }
+        auto agent = agent_group.get_agent(bucket_name);
+        if (!agent.has_value()) {
+          obs_rec->finish(agent.error());
+          return handler(
+            error(
+              agent.error(),
+              fmt::format("An error occurred while getting an operation agent for the `{}` bucket.",
+                          bucket_name)),
+            {});
+        }
+        if (!config->vbmap.has_value() || config->vbmap->empty()) {
+          CB_LOG_WARNING("Unable to get vbucket map for `{}` - cannot perform scan operation",
+                         core::logger::metadata(bucket_name));
+          obs_rec->finish(errc::common::request_canceled);
+          return handler(error(errc::common::request_canceled,
+                               "No vbucket map included with the bucket config."),
+                         {});
         }
-        return core_.with_bucket_configuration(
-          bucket_name_,
-          [this,
-           obs_rec = std::move(obs_rec),
-           handler = std::move(handler),
-           orchestrator_opts,
-           core_scan_type](std::error_code ec,
-                           const std::shared_ptr<core::topology::configuration>& config) mutable {
-            if (ec) {
-              obs_rec->finish(ec);
-              return handler(
-                error(ec, "An error occurred when attempting to fetch the bucket configuration."),
-                {});
-            }
-            if (!config->capabilities.supports_range_scan()) {
-              obs_rec->finish(ec);
-              return handler(error(errc::common::feature_not_available,
-                                   "This bucket does not support range scan."),
-                             {});
-            }
-            auto agent_group =
-              core::agent_group(core_.io_context(), core::agent_group_config{ { core_ } });
-            ec = agent_group.open_bucket(bucket_name_);
-            if (ec) {
-              obs_rec->finish(ec);
-              return handler(error(ec,
-                                   fmt::format("An error occurred while opening the `{}` bucket.",
-                                               bucket_name_)),
-                             {});
-            }
-            auto agent = agent_group.get_agent(bucket_name_);
-            if (!agent.has_value()) {
-              obs_rec->finish(ec);
-              return handler(
-                error(agent.error(),
-                      fmt::format(
-                        "An error occurred while getting an operation agent for the `{}` bucket",
-                        bucket_name_)),
-                {});
-            }
-            if (!config->vbmap.has_value() || config->vbmap->empty()) {
-              CB_LOG_WARNING("Unable to get vbucket map for `{}` - cannot perform scan operation",
-                             bucket_name_);
-              obs_rec->finish(ec);
-              return handler(error(errc::common::request_canceled,
-                                   "No vbucket map included with the bucket config"),
-                             {});
-            }
 
-            auto orchestrator = core::range_scan_orchestrator(core_.io_context(),
-                                                              agent.value(),
-                                                              config->vbmap.value(),
-                                                              scope_name_,
-                                                              name_,
-                                                              core_scan_type,
-                                                              orchestrator_opts);
-            return orchestrator.scan(
-              [obs_rec = std::move(obs_rec),
-               crypto_manager = crypto_manager_,
-               handler = std::move(handler)](auto ec, auto core_scan_result) mutable {
-                obs_rec->finish(ec);
-                if (ec) {
-                  return handler(error(ec, "Error while starting the range scan"), {});
-                }
-                auto internal_result = std::make_shared<internal_scan_result>(
-                  std::move(core_scan_result), std::move(crypto_manager));
-                return handler({}, scan_result{ internal_result });
-              });
-          });
+        auto orchestrator = core::range_scan_orchestrator(core.io_context(),
+                                                          agent.value(),
+                                                          config->vbmap.value(),
+                                                          scope_name,
+                                                          name,
+                                                          core_scan_type,
+                                                          orchestrator_opts);
+        return orchestrator.scan([obs_rec = std::move(obs_rec),
+                                  crypto_manager = std::move(crypto_manager),
+                                  handler = std::move(handler)](auto ec,
+                                                                auto core_scan_result) mutable {
+          obs_rec->finish(ec);
+          if (ec) {
+            return handler(error(ec, "Error while starting the range scan"), {});
+          }
+          auto internal_result = std::make_shared<internal_scan_result>(std::move(core_scan_result),
+                                                                        std::move(crypto_manager));
+          return handler({}, scan_result{ internal_result });
+        });
+      },
+      [](const std::shared_ptr<core::topology::configuration>& config)
+        -> std::pair<std::error_code, std::shared_ptr<core::topology::configuration>> {
+        return { {}, config };
       });
   }
 
@@ -1248,66 +1299,29 @@ public:
     if (origin_ec) {
       return handler(error{ origin_ec }, node_id{});
     }
-    const bool is_tls = origin.options().enable_tls;
-    const auto timeout = options.timeout.value_or(origin.options().key_value_timeout);
-
-    // Shared state so that only one of {timeout timer, bucket-config callback}
-    // can invoke the user handler. with_bucket_configuration() is not
-    // cancellable — if config never arrives, the timer is the only way to
-    // guarantee the handler completes.
-    struct state {
-      std::atomic<bool> done{ false };
-      asio::steady_timer timer;
-      node_id_for_handler handler;
-
-      state(asio::io_context& ioc, node_id_for_handler&& h)
-        : timer{ ioc }
-        , handler{ std::move(h) }
-      {
-      }
-    };
-    auto shared = std::make_shared<state>(core_.io_context(), std::move(handler));
+    // Validate the document key up front: an empty key would otherwise hash
+    // to vbucket 0 unconditionally, producing a deterministic-but-meaningless
+    // node_id. Surface this as invalid_argument rather than silently
+    // succeeding with garbage.
+    if (document_key.empty()) {
+      return handler(error{ errc::common::invalid_argument }, node_id{});
+    }
 
-    shared->timer.expires_after(timeout);
-    shared->timer.async_wait([shared](std::error_code timer_ec) -> void {
-      if (timer_ec == asio::error::operation_aborted) {
-        return;
-      }
-      if (shared->done.exchange(true)) {
-        return;
-      }
-      shared->handler(error{ errc::common::unambiguous_timeout }, node_id{});
-    });
+    const auto transport_kind = origin.options().enable_tls ? core::topology::transport::tls
+                                                            : core::topology::transport::plain;
+    const auto timeout = options.timeout.value_or(origin.options().key_value_timeout);
 
-    core_.with_bucket_configuration(
+    // The state struct + timer + atomic-done + asio::post scaffold lives
+    // in with_bucket_config_or_timeout(). See that header for the
+    // single-threaded-io_context assumption the timer relies on.
+    core::impl::with_bucket_config_or_timeout<couchbase::node_id>(
+      core_,
       bucket_name_,
-      [shared, document_key = std::move(document_key), is_tls](
-        std::error_code ec, const std::shared_ptr<core::topology::configuration>& config) -> void {
-        if (shared->done.exchange(true)) {
-          return;
-        }
-        shared->timer.cancel();
-        if (ec) {
-          return shared->handler(error{ ec }, node_id{});
-        }
-        if (!config || !config->vbmap.has_value() || config->vbmap->empty()) {
-          return shared->handler(error{ errc::network::configuration_not_available }, node_id{});
-        }
-        // Only server_index is needed here; vbucket is intentionally unused.
-        // Binding it as [[maybe_unused]] would require C++20 structured-
-        // binding attribute support, so take the pair by value and pull the
-        // field we need instead.
-        const auto mapping = config->map_key(document_key, 0);
-        const auto& server_index = mapping.second;
-        if (!server_index.has_value() || server_index.value() >= config->nodes.size()) {
-          // An unresolvable server_index means the vBucket map is present
-          // but does not map this key to a known node (out-of-range or
-          // missing entry). Surface this as configuration_not_available
-          // rather than request_canceled so callers can distinguish an
-          // unusable map from an actual caller-initiated cancellation.
-          return shared->handler(error{ errc::network::configuration_not_available }, node_id{});
-        }
-        return shared->handler({}, config->nodes[server_index.value()].effective_node_id(is_tls));
+      timeout,
+      std::move(handler),
+      [document_key = std::move(document_key),
+       transport_kind](const std::shared_ptr<core::topology::configuration>& config) {
+        return core::impl::resolve_node_id_from_config(config, document_key, transport_kind);
       });
   }
 
@@ -1317,54 +1331,29 @@ public:
     if (origin_ec) {
       return handler(error{ origin_ec }, {});
     }
-    const bool is_tls = origin.options().enable_tls;
+    const auto transport_kind = origin.options().enable_tls ? core::topology::transport::tls
+                                                            : core::topology::transport::plain;
     const auto timeout = options.timeout.value_or(origin.options().key_value_timeout);
 
-    // Same shape as node_id_for: with_bucket_configuration() is not
-    // cancellable, so a steady_timer guarded by an atomic done-flag is
-    // the only way to bound the wait when no config arrives.
-    struct state {
-      std::atomic<bool> done{ false };
-      asio::steady_timer timer;
-      node_ids_handler handler;
-
-      state(asio::io_context& ioc, node_ids_handler&& h)
-        : timer{ ioc }
-        , handler{ std::move(h) }
-      {
-      }
-    };
-    auto shared = std::make_shared<state>(core_.io_context(), std::move(handler));
-
-    shared->timer.expires_after(timeout);
-    shared->timer.async_wait([shared](std::error_code timer_ec) -> void {
-      if (timer_ec == asio::error::operation_aborted) {
-        return;
-      }
-      if (shared->done.exchange(true)) {
-        return;
-      }
-      shared->handler(error{ errc::common::unambiguous_timeout }, {});
-    });
-
-    core_.with_bucket_configuration(
+    // Same async scaffold as node_id_for — see the long comment there for
+    // the single-threaded-io_context assumption the timer relies on, and
+    // for why with_bucket_configuration() needs a steady_timer to bound
+    // the wait when no config ever arrives.
+    //
+    // Note: node_ids deliberately does not need to inspect the vBucket
+    // map (effective_node_ids enumerates topology nodes directly, not via
+    // a key->vbucket->node lookup), so the "vbmap missing" branch from
+    // node_id_for is absent here. A null or empty result is collapsed
+    // onto configuration_not_available below, matching the sibling's
+    // contract that an empty/unusable bucket configuration is a hard
+    // error rather than a silent empty success.
+    core::impl::with_bucket_config_or_timeout<std::vector<couchbase::node_id>>(
+      core_,
       bucket_name_,
-      [shared, is_tls](std::error_code ec,
-                       const std::shared_ptr<core::topology::configuration>& config) -> void {
-        if (shared->done.exchange(true)) {
-          return;
-        }
-        shared->timer.cancel();
-        if (ec) {
-          return shared->handler(error{ ec }, {});
-        }
-        if (!config) {
-          // No config arrived but no error either — this should not
-          // happen in practice, but surface it the same way node_id_for
-          // does so callers can distinguish from request_canceled.
-          return shared->handler(error{ errc::network::configuration_not_available }, {});
-        }
-        return shared->handler({}, config->effective_node_ids(is_tls));
+      timeout,
+      std::move(handler),
+      [transport_kind](const std::shared_ptr<core::topology::configuration>& config) {
+        return core::impl::resolve_node_ids_from_config(config, transport_kind);
       });
   }
 
@@ -1636,6 +1625,30 @@ collection::get_any_replica(std::string document_id, const get_any_replica_optio
   return future;
 }
 
+void
+collection::get_replica(std::string document_id,
+                        const get_replica_strategy& strategy,
+                        const get_replica_options& options,
+                        get_replica_handler&& handler) const
+{
+  return impl_->get_replica(
+    std::move(document_id), strategy.build(), options.build(), std::move(handler));
+}
+
+auto
+collection::get_replica(std::string document_id,
+                        const get_replica_strategy& strategy,
+                        const get_replica_options& options) const
+  -> std::future<std::pair<error, get_replica_result>>
+{
+  auto barrier = std::make_shared<std::promise<std::pair<error, get_replica_result>>>();
+  auto future = barrier->get_future();
+  get_replica(std::move(document_id), strategy, options, [barrier](auto err, auto result) {
+    barrier->set_value({ std::move(err), std::move(result) });
+  });
+  return future;
+}
+
 void
 collection::get_all_replicas(std::string document_id,
                              const get_all_replicas_options& options,