couchbase 3.8.2 → 3.9.0

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

@@ -0,0 +1,180 @@
+/* -*- 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 "core/cluster.hxx"
+#include "core/topology/configuration.hxx"
+
+#include <couchbase/error.hxx>
+#include <couchbase/error_codes.hxx>
+
+#include <asio/error.hpp>
+#include <asio/io_context.hpp>
+#include <asio/post.hpp>
+#include <asio/steady_timer.hpp>
+
+#include <atomic>
+#include <chrono>
+#include <memory>
+#include <string>
+#include <system_error>
+#include <utility>
+
+namespace couchbase::core::impl
+{
+/**
+ * Async scaffold shared between @c collection_impl::node_id_for and
+ * @c collection_impl::node_ids — and any future client-side API that needs
+ * to wait for a bucket configuration with a hard timeout.
+ *
+ * The scaffold owns the atomic-done guard, the timer, and the asio::post
+ * back to the io_context. Callers supply a resolver that maps a topology
+ * snapshot to a (error_code, payload) pair; the user handler is invoked
+ * with (error, payload) exactly once — including on io_context shutdown,
+ * where a fail-closed destructor backstop completes the handler with
+ * @c errc::network::cluster_closed rather than leaking a dropped completion
+ * (which would surface as a broken_promise to a std::future caller or a
+ * permanent hang to a callback caller).
+ *
+ * Thread-safety: the SDK's core io_context is single-threaded for KV work
+ * in the current release. The timer and atomic-done dance are safe under
+ * that assumption. If the io_context is ever multi-threaded, both
+ * @c timer.cancel() and the handler dispatch must be wrapped in a strand
+ * because @c asio::steady_timer is not thread-safe.
+ *
+ * @tparam Payload      The success-path payload type (e.g. @c node_id or
+ *                      @c std::vector<node_id>). Must be default-
+ *                      constructible (used for the timeout / error branches)
+ *                      and move-constructible.
+ * @tparam Handler      Callable accepting @c (couchbase::error, Payload).
+ * @tparam Resolver     Callable accepting
+ *                      @c const std::shared_ptr<topology::configuration>&
+ *                      and returning @c std::pair<std::error_code, Payload>.
+ *                      Invoked at most once, on the config-callback path
+ *                      when @c ec is falsy.
+ */
+template<typename Payload, typename Handler, typename Resolver>
+void
+with_bucket_config_or_timeout(const couchbase::core::cluster& core,
+                              const std::string& bucket_name,
+                              std::chrono::milliseconds timeout,
+                              Handler handler,
+                              Resolver resolver)
+{
+  struct state {
+    std::atomic<bool> done{ false };
+    std::atomic<bool> delivered{ false };
+    asio::steady_timer timer;
+    Handler handler;
+
+    state(asio::io_context& ioc, Handler&& h)
+      : timer{ ioc }
+      , handler{ std::move(h) }
+    {
+    }
+
+    // Invoke the user handler at most once. The `done` flag arbitrates the
+    // timer-vs-config race; `delivered` guards the handler call itself so the
+    // destructor can fail closed (below) without ever risking a double call.
+    void deliver(couchbase::error err, Payload payload)
+    {
+      if (!delivered.exchange(true, std::memory_order_acq_rel)) {
+        handler(std::move(err), std::move(payload));
+      }
+    }
+
+    // Fail-closed backstop. If every async continuation is torn down without
+    // the handler having run — io_context stopped on shutdown drops both the
+    // pending timer wait and any deferred asio::post — complete here so a
+    // std::future caller never observes broken_promise and a callback caller
+    // never hangs. By the time the destructor runs the last shared_ptr
+    // reference is gone, so no other thread can be in deliver() concurrently.
+    // The handler is user code; a destructor must not let an exception escape.
+    ~state()
+    {
+      try {
+        deliver(couchbase::error{ errc::network::cluster_closed }, Payload{});
+      } catch (...) { // NOLINT(bugprone-empty-catch)
+      }
+    }
+  };
+
+  auto shared = std::make_shared<state>(core.io_context(), std::move(handler));
+  // Capture the io_context by pointer value (not by reference to a local
+  // reference variable): core and its io_context outlive this operation, so
+  // the pointer stays valid even though the bucket-config callback may run
+  // after this function has returned.
+  auto* io_context = &core.io_context();
+
+  shared->timer.expires_after(timeout);
+  shared->timer.async_wait([shared](std::error_code timer_ec) -> void {
+    if (timer_ec == asio::error::operation_aborted) {
+      return;
+    }
+    // acq_rel matches the other writer (config callback): the only thing
+    // we synchronise on is whether we won the race to fire the handler.
+    if (shared->done.exchange(true, std::memory_order_acq_rel)) {
+      return;
+    }
+    shared->deliver(couchbase::error{ errc::common::unambiguous_timeout }, Payload{});
+  });
+
+  core.with_bucket_configuration(
+    bucket_name,
+    // Capture a weak_ptr, not a strong one. with_bucket_configuration() queues
+    // this callback in the bucket's deferred-commands list until a config
+    // arrives; if the timeout fires first and a config never arrives, a strong
+    // capture would pin the user handler, promise and timer in that queue
+    // indefinitely. The pending timer owns the state while we wait, so a config
+    // that arrives before the timeout still locks successfully; once the
+    // timeout has fired the state is released and this callback is a no-op.
+    [weak = std::weak_ptr<state>(shared), io_context, resolver = std::move(resolver)](
+      std::error_code ec,
+      const std::shared_ptr<core::topology::configuration>& config) mutable -> void {
+      auto shared = weak.lock();
+      if (!shared || shared->done.exchange(true, std::memory_order_acq_rel)) {
+        return;
+      }
+
+      std::error_code result_ec = ec;
+      Payload payload{};
+      if (!ec) {
+        std::tie(result_ec, payload) = resolver(config);
+      }
+
+      // Hop back onto the io_context before touching the timer or invoking
+      // the user handler. with_bucket_configuration() invokes its callback
+      // synchronously on the caller's thread when the bucket configuration
+      // is already cached (see bucket.cxx). Two things must therefore not
+      // happen inline here:
+      //   1. timer.cancel() — asio::steady_timer is not thread-safe and is
+      //      bound to core.io_context(); cancelling it from an arbitrary
+      //      application thread races with the io_context processing the
+      //      pending async_wait. It must run on the timer's executor.
+      //   2. the user handler — it reasonably expects an async hop and may
+      //      itself re-enter the SDK.
+      // The done flag above is atomic, so the race is already decided; the
+      // deferred cancel() is a harmless no-op if the timer has since fired
+      // (its handler short-circuits on operation_aborted / done).
+      asio::post(*io_context, [shared, result_ec, payload = std::move(payload)]() mutable {
+        shared->timer.cancel();
+        shared->deliver(couchbase::error{ result_ec }, std::move(payload));
+      });
+    });
+}
+} // namespace couchbase::core::impl

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

@@ -17,9 +17,9 @@
 
 #pragma once
 
-#include "core/impl/get_replica.hxx"
 #include "core/impl/lookup_in_replica.hxx"
 #include "core/operations/document_get.hxx"
+#include "core/operations/document_get_replica.hxx"
 #include "core/operations/document_lookup_in.hxx"
 #include "core/operations/operation_traits.hxx"
 #include "core/utils/movable_function.hxx"
@@ -35,7 +35,7 @@ class cancellation_token
 public:
   void setup(utils::movable_function<void()> cancel_fn)
   {
-    const std::lock_guard lock(mutex_);
+    const std::scoped_lock lock(mutex_);
     if (cancelled_) {
       cancel_fn();
       return;
@@ -47,7 +47,7 @@ public:
   {
     utils::movable_function<void()> fn{};
     {
-      const std::lock_guard lock(mutex_);
+      const std::scoped_lock lock(mutex_);
       cancelled_ = true;
       fn = std::move(cancel_fn_);
     }
@@ -72,4 +72,12 @@ template<typename kv_operation>
 struct operations::is_cancellable_operation<impl::with_cancellation<kv_operation>>
   : public std::true_type {
 };
+
+// Wrapping must not change how a request is routed: the wrapper inherits the
+// operation, so a trait left behind here would silently drop the wrapped
+// request back onto plain vbucket-map routing.
+template<typename kv_operation>
+struct operations::resolves_own_route<impl::with_cancellation<kv_operation>>
+  : public operations::resolves_own_route<kv_operation> {
+};
 } // namespace couchbase::core

data/ext/couchbase/core/io/configuration_belongs_to_session.hxx

@@ -60,8 +60,7 @@ configuration_belongs_to_session(const std::optional<std::string>& config_bucket
   }
 
   // Stage 3 — both sides name a bucket: accept only if it is the *same* bucket.
-  // Reaching here guarantees both optionals are engaged, so value() is safe.
   // Guards against applying another bucket's map to this session.
-  return config_bucket.value() == session_bucket.value();
+  return config_bucket == session_bucket;
 }
 } // namespace couchbase::core::io

data/ext/couchbase/core/io/dns_client.cxx

@@ -17,8 +17,11 @@
 
 #include "dns_client.hxx"
 
+#include "core/io/streams.hxx"
 #include "core/logger/logger.hxx"
+#include "core/logger/redaction.hxx"
 #include "core/utils/join_strings.hxx"
+#include "core/utils/process_id.hxx"
 #include "dns_codec.hxx"
 #include "dns_config.hxx"
 
@@ -37,6 +40,29 @@
 
 namespace couchbase::core::io::dns
 {
+namespace
+{
+auto
+rcode_description(response_code rcode) -> const char*
+{
+  switch (rcode) {
+    case response_code::no_error:
+      return "NOERROR";
+    case response_code::format_error:
+      return "FORMERR (server could not interpret the query)";
+    case response_code::server_failure:
+      return "SERVFAIL (server failure — DNS resolver may not support SRV queries)";
+    case response_code::name_error:
+      return "NXDOMAIN (name does not exist — no SRV record registered for this hostname)";
+    case response_code::not_implemented:
+      return "NOTIMP (query type not implemented by the server)";
+    case response_code::refused:
+      return "REFUSED (server refused the query — policy restriction)";
+  }
+  return "UNKNOWN";
+}
+} // namespace
+
 class dns_srv_command : public std::enable_shared_from_this<dns_srv_command>
 {
 public:
@@ -47,7 +73,8 @@ public:
     asio::ip::address address,
     std::uint16_t port,
     utils::movable_function<void(couchbase::core::io::dns::dns_srv_response&& resp)> handler)
-    : deadline_(ctx)
+    : ctx_(ctx)
+    , deadline_(ctx)
     , udp_deadline_(ctx)
     , udp_(ctx)
     , tcp_(ctx)
@@ -73,13 +100,19 @@ public:
 
   void execute(std::chrono::milliseconds total_timeout, std::chrono::milliseconds udp_timeout)
   {
-    CB_LOG_TRACE("Query DNS-SRV (UDP) address=\"{}:{}\", udp_timeout={}, total_timeout={}",
-                 address_.to_string(),
-                 port_,
+    CB_LOG_TRACE("Query DNS-SRV (UDP) address=\"{}\", udp_timeout={}, total_timeout={}",
+                 logger::system_data(nameserver_address()),
                  udp_timeout,
                  total_timeout);
     const asio::ip::udp::endpoint endpoint(address_, port_);
     udp_.open(endpoint.protocol());
+    // A process forked while this lookup is pending inherits both sockets. Registering them lets
+    // the forked process's fixup release them, so it cannot read the response this process is
+    // waiting for.
+    register_inherited_socket(ctx_,
+                              std::shared_ptr<asio::ip::udp::socket>(shared_from_this(), &udp_));
+    register_inherited_socket(ctx_,
+                              std::shared_ptr<asio::ip::tcp::socket>(shared_from_this(), &tcp_));
     CB_LOG_PROTOCOL("[DNS, UDP, OUT] host=\"{}\", port={}, buffer_size={}{:a}",
                     address_.to_string(),
                     port_,
@@ -100,9 +133,8 @@ public:
             return;
           }
           CB_LOG_DEBUG(
-            "DNS UDP write operation has got error, retrying with TCP, address=\"{}:{}\", ec={}",
-            self->address_.to_string(),
-            self->port_,
+            "DNS UDP write operation has got error, retrying with TCP, address=\"{}\", ec={}",
+            logger::system_data(self->nameserver_address()),
             ec1.message());
           return self->retry_with_tcp();
         }
@@ -126,20 +158,26 @@ public:
                 return;
               }
               CB_LOG_DEBUG(
-                "DNS UDP read operation has got error, retrying with TCP, address=\"{}:{}\", ec={}",
-                self->address_.to_string(),
-                self->port_,
+                "DNS UDP read operation has got error, retrying with TCP, address=\"{}\", ec={}",
+                logger::system_data(self->nameserver_address()),
                 ec2.message());
               return self->retry_with_tcp();
             }
             self->recv_buf_.resize(bytes_transferred);
             const dns_message message = dns_codec::decode(self->recv_buf_);
             if (message.header.flags.tc == truncation::yes) {
-              self->udp_.close();
+              std::error_code ignored{};
+              self->udp_.close(ignored);
               CB_LOG_DEBUG("DNS UDP read operation returned truncated response, retrying with TCP");
               return self->retry_with_tcp();
             }
             self->deadline_.cancel();
+            if (message.header.flags.rcode != response_code::no_error) {
+              CB_LOG_WARNING("DNS UDP response for \"{}\" returned non-zero RCODE: {} ({})",
+                             logger::system_data(self->nameserver_address()),
+                             static_cast<int>(message.header.flags.rcode),
+                             rcode_description(message.header.flags.rcode));
+            }
             dns_srv_response resp{ ec2 };
             resp.targets.reserve(message.answers.size());
             for (const auto& answer : message.answers) {
@@ -147,7 +185,7 @@ public:
                 utils::join_strings(answer.target.labels, "."), answer.port });
             }
             CB_LOG_DEBUG("DNS UDP returned {} records", resp.targets.size());
-            return self->handler_(std::move(resp));
+            return self->complete(std::move(resp));
           });
       });
     udp_deadline_.expires_after(udp_timeout);
@@ -155,11 +193,11 @@ public:
       if (ec == asio::error::operation_aborted) {
         return;
       }
-      self->udp_.cancel();
+      std::error_code ignored{};
+      self->udp_.cancel(ignored);
       CB_LOG_DEBUG("DNS UDP deadline has been reached, cancelling UDP operation and fall back to "
-                   "TCP, address=\"{}:{}\"",
-                   self->address_.to_string(),
-                   self->port_);
+                   "TCP, address=\"{}\"",
+                   logger::system_data(self->nameserver_address()));
       return self->retry_with_tcp();
     });
 
@@ -169,29 +207,52 @@ public:
         return;
       }
       CB_LOG_DEBUG("DNS deadline has been reached, cancelling in-flight operations "
-                   "(tcp.is_open={}, address=\"{}:{}\")",
+                   "(tcp.is_open={}, address=\"{}\")",
                    self->tcp_.is_open(),
-                   self->address_.to_string(),
-                   self->port_);
-      self->udp_.cancel();
+                   logger::system_data(self->nameserver_address()));
+      std::error_code ignored{};
+      self->udp_.cancel(ignored);
       if (self->tcp_.is_open()) {
-        self->tcp_.cancel();
+        self->tcp_.cancel(ignored);
       }
-      return self->handler_({ errc::common::unambiguous_timeout });
+      return self->complete({ errc::common::unambiguous_timeout });
     });
   }
 
 private:
+  // A lookup that a forked process inherited belongs to the process that started it. The child
+  // fixup releases its sockets, which fails their pending operations; neither those failures nor
+  // its timers may retry or complete the lookup in that process.
+  [[nodiscard]] auto inherited() const -> bool
+  {
+    return owner_pid_ != utils::current_process_id();
+  }
+
+  void complete(dns_srv_response&& resp)
+  {
+    if (inherited()) {
+      return;
+    }
+    handler_(std::move(resp));
+  }
+
+  [[nodiscard]] auto nameserver_address() const -> std::string
+  {
+    return fmt::format("{}:{}", address_.to_string(), port_);
+  }
+
   void retry_with_tcp()
   {
+    if (inherited()) {
+      return;
+    }
     if (bool expected_state{ false };
         !retrying_with_tcp_.compare_exchange_strong(expected_state, true)) {
       return;
     }
 
-    CB_LOG_TRACE("Query DNS-SRV (TCP) address=\"{}:{}\", time_left={}",
-                 address_.to_string(),
-                 port_,
+    CB_LOG_TRACE("Query DNS-SRV (TCP) address=\"{}\", time_left={}",
+                 logger::system_data(nameserver_address()),
                  std::chrono::duration_cast<std::chrono::milliseconds>(
                    deadline_.expiry() - std::chrono::steady_clock::now()));
 
@@ -205,11 +266,10 @@ private:
           return;
         }
         self->deadline_.cancel();
-        CB_LOG_DEBUG("DNS TCP connection has been aborted, address=\"{}:{}\", ec={}",
-                     self->address_.to_string(),
-                     self->port_,
+        CB_LOG_DEBUG("DNS TCP connection has been aborted, address=\"{}\", ec={}",
+                     logger::system_data(self->nameserver_address()),
                      ec1.message());
-        return self->handler_({ ec1 });
+        return self->complete({ ec1 });
       }
       auto send_size = static_cast<std::uint16_t>(self->send_buf_.size());
       self->send_buf_.insert(self->send_buf_.begin(), static_cast<std::uint8_t>(send_size & 0xffU));
@@ -232,12 +292,11 @@ private:
             if (ec2 == asio::error::operation_aborted) {
               return;
             }
-            CB_LOG_DEBUG("DNS TCP write operation has been aborted, address=\"{}:{}\", ec={}",
-                         self->address_.to_string(),
-                         self->port_,
+            CB_LOG_DEBUG("DNS TCP write operation has been aborted, address=\"{}\", ec={}",
+                         logger::system_data(self->nameserver_address()),
                          ec2.message());
             self->deadline_.cancel();
-            return self->handler_({ ec2 });
+            return self->complete({ ec2 });
           }
           asio::async_read(
             self->tcp_,
@@ -257,14 +316,13 @@ private:
                   return;
                 }
                 CB_LOG_DEBUG(
-                  "DNS TCP buf size read operation has been aborted, address=\"{}:{}\", ec={}",
-                  self->address_.to_string(),
-                  self->port_,
+                  "DNS TCP buf size read operation has been aborted, address=\"{}\", ec={}",
+                  logger::system_data(self->nameserver_address()),
                   ec3.message());
                 self->deadline_.cancel();
-                return self->handler_({ ec3 });
+                return self->complete({ ec3 });
               }
-              self->recv_buf_size_ = utils::byte_swap(self->recv_buf_size_);
+              self->recv_buf_size_ = utils::network_to_host(self->recv_buf_size_);
               self->recv_buf_.resize(self->recv_buf_size_);
               CB_LOG_DEBUG("DNS TCP schedule read of {} bytes", self->recv_buf_size_);
               asio::async_read(
@@ -285,15 +343,19 @@ private:
                   }
                   self->deadline_.cancel();
                   if (ec4) {
-                    CB_LOG_DEBUG(
-                      "DNS TCP read operation has been aborted, address=\"{}:{}\", ec={}",
-                      self->address_.to_string(),
-                      self->port_,
-                      ec4.message());
-                    return self->handler_({ ec4 });
+                    CB_LOG_DEBUG("DNS TCP read operation has been aborted, address=\"{}\", ec={}",
+                                 logger::system_data(self->nameserver_address()),
+                                 ec4.message());
+                    return self->complete({ ec4 });
                   }
                   self->recv_buf_.resize(bytes_transferred4);
                   const dns_message message = dns_codec::decode(self->recv_buf_);
+                  if (message.header.flags.rcode != response_code::no_error) {
+                    CB_LOG_WARNING("DNS TCP response for \"{}\" returned non-zero RCODE: {} ({})",
+                                   logger::system_data(self->nameserver_address()),
+                                   static_cast<int>(message.header.flags.rcode),
+                                   rcode_description(message.header.flags.rcode));
+                  }
                   dns_srv_response resp{ ec4 };
                   resp.targets.reserve(message.answers.size());
                   for (const auto& answer : message.answers) {
@@ -301,13 +363,14 @@ private:
                       utils::join_strings(answer.target.labels, "."), answer.port });
                   }
                   CB_LOG_DEBUG("DNS TCP returned {} records", resp.targets.size());
-                  return self->handler_(std::move(resp));
+                  return self->complete(std::move(resp));
                 });
             });
         });
     });
   }
 
+  asio::io_context& ctx_;
   asio::steady_timer deadline_;
   asio::steady_timer udp_deadline_;
   asio::ip::udp::socket udp_;
@@ -323,6 +386,7 @@ private:
   std::vector<std::uint8_t> recv_buf_{};
 
   std::atomic_bool retrying_with_tcp_{ false };
+  std::int64_t owner_pid_{ utils::current_process_id() };
 };
 
 void
@@ -332,12 +396,25 @@ dns_client::query_srv(const std::string& name,
                       utils::movable_function<void(dns_srv_response&&)>&& handler)
 {
   if (config.nameserver().empty()) {
+    CB_LOG_WARNING(
+      "DNS-SRV query for \"{}/{}\" skipped: no nameserver configured (DNS-SRV bootstrap is "
+      "disabled). Check that /etc/resolv.conf contains a valid IP address on a \"nameserver\" "
+      "line, or set the nameserver explicitly in the cluster options.",
+      logger::system_data(name),
+      service);
     return handler({ {} });
   }
 
   std::error_code ec;
   auto address = asio::ip::make_address(config.nameserver(), ec);
   if (ec) {
+    CB_LOG_WARNING(
+      "DNS-SRV query for \"{}/{}\" skipped: configured nameserver \"{}\" could not be parsed as "
+      "an IP address ({}). Only numeric IP addresses are supported as nameserver values.",
+      logger::system_data(name),
+      service,
+      logger::system_data(config.nameserver()),
+      ec.message());
     return handler({ ec });
   }
   auto cmd = std::make_shared<dns_srv_command>(