couchbase 3.8.2 → 3.9.0

data/ext/rcb_utils.hxx

@@ -24,10 +24,14 @@
 #include <couchbase/persist_to.hxx>
 #include <couchbase/read_preference.hxx>
 #include <couchbase/replicate_to.hxx>
+#include <couchbase/retry_strategy.hxx>
 #include <couchbase/store_semantics.hxx>
 
 #include <chrono>
+#include <cstdarg>
 #include <cstdint>
+#include <exception>
+#include <memory>
 #include <optional>
 #include <string>
 #include <vector>
@@ -40,6 +44,119 @@
 
 namespace couchbase::ruby
 {
+// Runs fn, which calls Ruby code, under rb_protect. A Ruby non-local exit from fn stops at
+// rb_protect and continues as ruby_jump, so the C++ frames between the caller and cb_method
+// unwind. The longjmp still skips objects held in fn's own frames. fn must not throw; the
+// rb_protect callback is noexcept, so an exception terminates instead of crossing rb_protect's
+// frame.
+template<typename Callable>
+inline void
+cb_protect(const Callable& fn)
+{
+  int state = 0;
+  rb_protect(
+    [](VALUE arg) noexcept -> VALUE {
+      // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+      (*reinterpret_cast<const Callable*>(arg))();
+      return Qnil;
+    },
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    reinterpret_cast<VALUE>(&fn),
+    &state);
+  if (state != 0) {
+    throw ruby_jump(state);
+  }
+}
+
+// rb_sprintf under cb_protect. A PRIsVALUE argument is formatted with its inspect or to_s, which
+// may raise. Call it only from a method body registered through cb_method.
+RBIMPL_ATTR_FORMAT(RBIMPL_PRINTF_FORMAT, 1, 2)
+inline auto
+cb_sprintf(const char* format, ...) -> VALUE
+{
+  VALUE str = Qnil;
+  std::va_list args;
+  va_start(args, format);
+  try {
+    cb_protect([format, &args, &str] {
+      str = rb_vsprintf(format, args);
+    });
+  } catch (...) {
+    va_end(args);
+    throw;
+  }
+  va_end(args);
+  return str;
+}
+
+// NUM2ULL, NUM2LL, NUM2UINT and NUM2INT under cb_protect. Each raises RangeError for a value out of
+// its target range. Call them only from a method body registered through cb_method.
+inline auto
+cb_num2ull(VALUE num) -> std::uint64_t
+{
+  std::uint64_t value{};
+  cb_protect([num, &value] {
+    value = NUM2ULL(num);
+  });
+  return value;
+}
+
+inline auto
+cb_num2ll(VALUE num) -> std::int64_t
+{
+  std::int64_t value{};
+  cb_protect([num, &value] {
+    value = NUM2LL(num);
+  });
+  return value;
+}
+
+inline auto
+cb_num2uint(VALUE num) -> std::uint32_t
+{
+  std::uint32_t value{};
+  cb_protect([num, &value] {
+    value = NUM2UINT(num);
+  });
+  return value;
+}
+
+inline auto
+cb_num2int(VALUE num) -> std::int32_t
+{
+  std::int32_t value{};
+  cb_protect([num, &value] {
+    value = NUM2INT(num);
+  });
+  return value;
+}
+
+// Wraps Method, which may throw ruby_exception or ruby_jump, for rb_define_method. Method's
+// frames unwind first; the Ruby raise or jump happens here, where no C++ object is live and no
+// catch handler is active.
+template<auto Method, typename = decltype(Method)>
+struct cb_method;
+
+template<auto Method, typename... Args>
+struct cb_method<Method, VALUE (*)(Args...)> {
+  static auto invoke(Args... args) -> VALUE
+  {
+    int state = 0;
+    VALUE exc = Qnil;
+    try {
+      return Method(args...);
+    } catch (const ruby_jump& e) {
+      state = e.state();
+    } catch (const ruby_exception& e) {
+      exc = e.exception_object();
+    }
+    if (state != 0) {
+      rb_jump_tag(state);
+    }
+    rb_exc_raise(exc);
+  }
+};
+
 template<typename Future>
 inline auto
 cb_wait_for_future(Future&& f) -> decltype(f.get())
@@ -48,17 +165,84 @@ cb_wait_for_future(Future&& f) -> decltype(f.get())
     // NOLINTNEXTLINE(cppcoreguidelines-avoid-const-or-ref-data-members)
     Future&& f;
     decltype(f.get()) res{};
-  } arg{ std::forward<Future>(f) };
-  rb_thread_call_without_gvl(
-    [](void* param) -> void* {
+    std::exception_ptr error{};
+    bool done{ false };
+
+    // Runs without the GVL, inside Ruby C frames, so no exception leaves it.
+    static auto wait(void* param) -> void*
+    {
       auto* pack = static_cast<arg_pack*>(param);
-      pack->res = std::move(pack->f.get());
+      try {
+        pack->res = std::move(pack->f.get());
+      } catch (...) {
+        pack->error = std::current_exception();
+      }
+      pack->done = true;
       return nullptr;
-    },
-    &arg,
-    nullptr,
-    nullptr);
-  flush_logger();
+    }
+
+    // No unblocking function: the wait ends only when the operation completes or times out.
+    // Interrupts are checked before and after it, and a pending one raises there.
+    static auto protected_wait(VALUE param) -> VALUE
+    {
+      rb_thread_call_without_gvl(
+        wait,
+        // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast,performance-no-int-to-ptr)
+        reinterpret_cast<void*>(param),
+        nullptr,
+        nullptr);
+      return Qnil;
+    }
+  } arg{ std::forward<Future>(f) };
+
+  // rb_protect stops an interrupt (Timeout, Thread#raise, Thread#kill, a signal) raised at the
+  // checks around the wait. One raised before the wait leaves the operation in flight, so the
+  // wait is retried until the operation completes; no attempt waits with the GVL held. A later
+  // interrupt replaces the earlier one, which is discarded.
+  int state = 0;
+  VALUE interrupt = Qnil;
+  // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+  rb_protect(arg_pack::protected_wait, reinterpret_cast<VALUE>(&arg), &state);
+  if (state != 0) {
+    interrupt = rb_errinfo();
+  }
+  while (!arg.done) {
+    int next = 0;
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    rb_protect(arg_pack::protected_wait, reinterpret_cast<VALUE>(&arg), &next);
+    if (next != 0) {
+      state = next;
+      interrupt = rb_errinfo();
+    }
+  }
+  if (state != 0) {
+    // A trap handler run by a retry's interrupt check can clear errinfo by rescuing, so a raised
+    // exception is restored before ruby_jump carries the interrupt to cb_method. Trap handlers run
+    // only on the main thread, which never receives a kill interrupt. errinfo holds an Exception
+    // only after a raise: a kill leaves an Integer, and a throw (Timeout on Ruby 3.2 uses catch
+    // and throw) leaves internal throw data, which rb_obj_is_kind_of cannot read.
+    if (RB_TYPE_P(interrupt, T_OBJECT) && rb_obj_is_kind_of(interrupt, rb_eException) == Qtrue) {
+      rb_set_errinfo(interrupt);
+    }
+    throw ruby_jump(state);
+  }
+  // Only when no interrupt was stopped: the logger runs Ruby code, which would replace errinfo.
+  // Otherwise its messages stay queued for the next flush.
+  cb_protect([] {
+    flush_logger();
+  });
+  if (arg.error) {
+    // The promises waited on here are fulfilled only with set_value, so a future fails only with
+    // std::future_error, when its promise is destroyed unfulfilled.
+    std::string message{ "unable to wait for the operation result" };
+    try {
+      std::rethrow_exception(arg.error);
+    } catch (const std::exception& e) {
+      message.append(": ").append(e.what());
+    } catch (...) {
+    }
+    throw ruby_exception(cb_exc_new(exc_couchbase_error(), message));
+  }
   return std::move(arg.res);
 }
 
@@ -72,6 +256,15 @@ cb_str_new(const StringLike str)
 void
 cb_check_type(VALUE object, int type);
 
+// rb_sym2id for a value not yet checked to be a Symbol. A non-Symbol throws the TypeError, with the
+// message, that rb_sym2id raises. Call it only from a method body registered through cb_method.
+inline auto
+cb_sym2id(VALUE sym) -> ID
+{
+  cb_check_type(sym, T_SYMBOL);
+  return rb_sym2id(sym);
+}
+
 std::string
 cb_string_new(VALUE str);
 
@@ -124,11 +317,11 @@ cb_extract_timeout(Request& req, VALUE options)
         return cb_extract_timeout(req, rb_hash_aref(options, rb_id2sym(rb_intern("timeout"))));
       case T_FIXNUM:
       case T_BIGNUM:
-        req.timeout = std::chrono::milliseconds(NUM2ULL(options));
+        req.timeout = std::chrono::milliseconds(cb_num2ull(options));
         break;
       default:
         throw ruby_exception(
-          rb_eArgError, rb_sprintf("timeout must be an Integer, but given %+" PRIsVALUE, options));
+          rb_eArgError, cb_sprintf("timeout must be an Integer, but given %+" PRIsVALUE, options));
     }
   }
 }
@@ -143,7 +336,7 @@ cb_extract_durability_level(Request& req, VALUE options)
 
   if (TYPE(options) != T_HASH) {
     throw ruby_exception(rb_eArgError,
-                         rb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
+                         cb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
   }
 
   static VALUE property_name = rb_id2sym(rb_intern("durability_level"));
@@ -154,7 +347,7 @@ cb_extract_durability_level(Request& req, VALUE options)
   }
   if (TYPE(val) != T_SYMBOL) {
     throw ruby_exception(
-      rb_eArgError, rb_sprintf("durability_level must be a Symbol, but given %+" PRIsVALUE, val));
+      rb_eArgError, cb_sprintf("durability_level must be a Symbol, but given %+" PRIsVALUE, val));
   }
   if (ID level = rb_sym2id(val); level == rb_intern("none")) {
     req.durability_level = couchbase::durability_level::none;
@@ -166,7 +359,7 @@ cb_extract_durability_level(Request& req, VALUE options)
     req.durability_level = couchbase::durability_level::persist_to_majority;
   } else {
     throw ruby_exception(rb_eArgError,
-                         rb_sprintf("unexpected durability_level, given %+" PRIsVALUE, val));
+                         cb_sprintf("unexpected durability_level, given %+" PRIsVALUE, val));
   }
 }
 
@@ -178,7 +371,7 @@ cb_extract_read_preference(Request& req, VALUE options)
   if (!NIL_P(options)) {
     if (TYPE(options) != T_HASH) {
       throw ruby_exception(rb_eArgError,
-                           rb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
+                           cb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
     }
 
     VALUE val = rb_hash_aref(options, property_name);
@@ -187,7 +380,7 @@ cb_extract_read_preference(Request& req, VALUE options)
     }
     if (TYPE(val) != T_SYMBOL) {
       throw ruby_exception(
-        rb_eArgError, rb_sprintf("read_preference must be a Symbol, but given %+" PRIsVALUE, val));
+        rb_eArgError, cb_sprintf("read_preference must be a Symbol, but given %+" PRIsVALUE, val));
     }
 
     if (ID mode = rb_sym2id(val); mode == rb_intern("no_preference")) {
@@ -196,7 +389,7 @@ cb_extract_read_preference(Request& req, VALUE options)
       req.read_preference = couchbase::read_preference::selected_server_group;
     } else {
       throw ruby_exception(rb_eArgError,
-                           rb_sprintf("unexpected read_preference, given %+" PRIsVALUE, val));
+                           cb_sprintf("unexpected read_preference, given %+" PRIsVALUE, val));
     }
   }
 }
@@ -211,15 +404,29 @@ cb_extract_duration(Field& field, VALUE options, const char* name)
         return cb_extract_duration(field, rb_hash_aref(options, rb_id2sym(rb_intern(name))), name);
       case T_FIXNUM:
       case T_BIGNUM:
-        field = std::chrono::milliseconds(NUM2ULL(options));
+        field = std::chrono::milliseconds(cb_num2ull(options));
         break;
       default:
         throw ruby_exception(
-          rb_eArgError, rb_sprintf("%s must be an Integer, but given %+" PRIsVALUE, name, options));
+          rb_eArgError, cb_sprintf("%s must be an Integer, but given %+" PRIsVALUE, name, options));
     }
   }
 }
 
+// The default upper bound of cb_to_timeout. It lies far inside the range of steady_clock, so a
+// deadline steady_clock::now() + timeout cannot overflow.
+constexpr std::chrono::milliseconds cb_max_timeout{ std::chrono::hours{ 24 * 365 } };
+static_assert(cb_max_timeout < std::chrono::steady_clock::duration::max() / 2);
+
+// Converts timeout, an Integer number of milliseconds from 0 to max_timeout, which must not be
+// negative. Throws ArgumentError for a non-Integer, and Error::InvalidArgument for a value out of
+// that range; name labels the value in the messages. Call it only from a method body registered
+// through cb_method.
+[[nodiscard]] auto
+cb_to_timeout(VALUE timeout,
+              const char* name,
+              std::chrono::milliseconds max_timeout = cb_max_timeout) -> std::chrono::milliseconds;
+
 void
 cb_extract_content(std::vector<std::byte>& field, VALUE content);
 
@@ -246,6 +453,11 @@ cb_extract_timeout(std::chrono::milliseconds& field, VALUE options);
 void
 cb_extract_timeout(std::optional<std::chrono::milliseconds>& field, VALUE options);
 
+// nil selects the cluster's default strategy; :best_effort and :fail_fast select the built-ins.
+// Any other value raises InvalidArgument.
+auto
+cb_extract_retry_strategy(VALUE options) -> std::shared_ptr<couchbase::retry_strategy>;
+
 void
 cb_extract_option_symbol(VALUE& val, VALUE options, const char* name);
 
@@ -276,7 +488,7 @@ cb_extract_option_bool(Boolean& field, VALUE options, const char* name)
         break;
       default:
         throw ruby_exception(rb_eArgError,
-                             rb_sprintf("%s must be a Boolean, but given %+" PRIsVALUE, name, val));
+                             cb_sprintf("%s must be a Boolean, but given %+" PRIsVALUE, name, val));
     }
   }
 }
@@ -291,7 +503,7 @@ cb_extract_option_uint64(T& field, VALUE options, const char* name)
   VALUE val = Qnil;
   cb_extract_option_bignum(val, options, name);
   if (!NIL_P(val)) {
-    field = NUM2ULL(val);
+    field = cb_num2ull(val);
   }
 }
 
@@ -309,11 +521,11 @@ cb_extract_option_number(Integer& field, VALUE options, const char* name)
         field = static_cast<Integer>(FIX2ULONG(val));
         break;
       case T_BIGNUM:
-        field = static_cast<Integer>(NUM2ULL(val));
+        field = static_cast<Integer>(cb_num2ull(val));
         break;
       default:
         throw ruby_exception(rb_eArgError,
-                             rb_sprintf("%s must be a Integer, but given %+" PRIsVALUE, name, val));
+                             cb_sprintf("%s must be a Integer, but given %+" PRIsVALUE, name, val));
     }
   }
 }
@@ -417,7 +629,7 @@ set_timeout(CommandOptions& opts, VALUE options)
   if (!NIL_P(options)) {
     if (TYPE(options) != T_HASH) {
       throw ruby_exception(rb_eArgError,
-                           rb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
+                           cb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
     }
     VALUE val = rb_hash_aref(options, property_name);
     if (NIL_P(val)) {
@@ -426,12 +638,12 @@ set_timeout(CommandOptions& opts, VALUE options)
     switch (TYPE(val)) {
       case T_FIXNUM:
       case T_BIGNUM:
-        opts.timeout(std::chrono::milliseconds(NUM2ULL(val)));
+        opts.timeout(std::chrono::milliseconds(cb_num2ull(val)));
         break;
 
       default:
         throw ruby_exception(rb_eArgError,
-                             rb_sprintf("timeout must be an Integer, but given %+" PRIsVALUE, val));
+                             cb_sprintf("timeout must be an Integer, but given %+" PRIsVALUE, val));
     }
   }
 }
@@ -453,7 +665,7 @@ set_expiry(CommandOptions& opts, VALUE options)
   if (!NIL_P(options)) {
     if (TYPE(options) != T_HASH) {
       throw ruby_exception(rb_eArgError,
-                           rb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
+                           cb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
     }
     VALUE val = rb_hash_aref(options, property_name);
     if (NIL_P(val)) {
@@ -483,7 +695,7 @@ set_preserve_expiry(CommandOptions& opts, VALUE options)
   if (!NIL_P(options)) {
     if (TYPE(options) != T_HASH) {
       throw ruby_exception(rb_eArgError,
-                           rb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
+                           cb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
     }
     VALUE val = rb_hash_aref(options, property_name);
     if (NIL_P(val)) {
@@ -499,7 +711,7 @@ set_preserve_expiry(CommandOptions& opts, VALUE options)
       default:
         throw ruby_exception(
           rb_eArgError,
-          rb_sprintf("preserve_expiry must be a Boolean, but given %+" PRIsVALUE, val));
+          cb_sprintf("preserve_expiry must be a Boolean, but given %+" PRIsVALUE, val));
     }
   }
 }
@@ -517,7 +729,7 @@ set_durability(CommandOptions& opts, VALUE options)
   if (!NIL_P(options)) {
     if (TYPE(options) != T_HASH) {
       throw ruby_exception(rb_eArgError,
-                           rb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
+                           cb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
     }
     if (auto level = extract_durability_level(options); level.has_value()) {
       opts.durability(level.value());
@@ -541,7 +753,7 @@ cb_extract_store_semantics(Request& req, VALUE options)
   }
   if (TYPE(options) != T_HASH) {
     throw ruby_exception(rb_eArgError,
-                         rb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
+                         cb_sprintf("expected options to be Hash, given %+" PRIsVALUE, options));
   }
 
   VALUE val = rb_hash_aref(options, property_name);
@@ -550,7 +762,7 @@ cb_extract_store_semantics(Request& req, VALUE options)
   }
   if (TYPE(val) != T_SYMBOL) {
     throw ruby_exception(
-      rb_eArgError, rb_sprintf("store_semantics must be a Symbol, but given %+" PRIsVALUE, val));
+      rb_eArgError, cb_sprintf("store_semantics must be a Symbol, but given %+" PRIsVALUE, val));
   }
 
   if (ID mode = rb_sym2id(val); mode == rb_intern("replace")) {
@@ -561,8 +773,50 @@ cb_extract_store_semantics(Request& req, VALUE options)
     req.store_semantics = couchbase::store_semantics::upsert;
   } else {
     throw ruby_exception(rb_eArgError,
-                         rb_sprintf("unexpected store_semantics, given %+" PRIsVALUE, val));
+                         cb_sprintf("unexpected store_semantics, given %+" PRIsVALUE, val));
+  }
+}
+
+// Copies a Hash of String => String into target. The type check does not raise or throw inside
+// rb_hash_foreach: the callback records the first entry of another type and stops, and the
+// ArgumentError is thrown after rb_hash_foreach returns. kind names the option in the message.
+template<typename Map>
+void
+cb_extract_string_hash(Map& target, VALUE hash, const char* kind)
+{
+  struct state {
+    Map& target;
+    VALUE key{ Qundef };
+    VALUE value{ Qundef };
+  } st{ target };
+  rb_hash_foreach(
+    hash,
+    [](VALUE key, VALUE value, VALUE arg) -> int {
+      // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+      auto* s = reinterpret_cast<state*>(arg);
+      if (!RB_TYPE_P(key, T_STRING) || !RB_TYPE_P(value, T_STRING)) {
+        s->key = key;
+        s->value = value;
+        return ST_STOP;
+      }
+      s->target[cb_string_new(key)] = cb_string_new(value);
+      return ST_CONTINUE;
+    },
+    // NOLINTNEXTLINE(cppcoreguidelines-pro-type-reinterpret-cast)
+    reinterpret_cast<VALUE>(&st));
+  if (st.key == Qundef) {
+    return;
+  }
+  if (!RB_TYPE_P(st.key, T_STRING)) {
+    throw ruby_exception(
+      rb_eArgError, cb_sprintf("%s key must be a String, but given %+" PRIsVALUE, kind, st.key));
   }
+  throw ruby_exception(rb_eArgError,
+                       cb_sprintf("%s value for %+" PRIsVALUE
+                                  " must be a String, but given %+" PRIsVALUE,
+                                  kind,
+                                  st.key,
+                                  st.value));
 }
 } // namespace couchbase::ruby
 

data/ext/rcb_version.cxx

@@ -120,7 +120,7 @@ init_version(VALUE mCouchbase)
         name == "mozilla_ca_bundle_size") {
       rb_hash_aset(cb_CoreInfo, rb_id2sym(rb_intern(name.c_str())), INT2FIX(std::stoi(value)));
     } else if (name == "snapshot" || name == "static_stdlib" || name == "static_openssl" ||
-               name == "static_boringssl" || name == "columnar" || name == "static_target" ||
+               name == "static_boringssl" || name == "static_target" ||
                name == "mozilla_ca_bundle_embedded") {
       rb_hash_aset(
         cb_CoreInfo, rb_id2sym(rb_intern(name.c_str())), value == "true" ? Qtrue : Qfalse);