couchbase 3.8.2 → 3.9.1

data/ext/rcb_views.cxx

@@ -23,6 +23,7 @@
 #include <core/operations/management/view_index_get.hxx>
 #include <core/operations/management/view_index_get_all.hxx>
 #include <core/operations/management/view_index_upsert.hxx>
+#include <core/utils/url_codec.hxx>
 #undef COUCHBASE_CXX_CLIENT_IGNORE_CORE_DEPRECATIONS
 
 #include <future>
@@ -46,8 +47,8 @@ cb_Backend_view_index_get_all(VALUE self,
 {
   auto cluster = cb_backend_to_core_api_cluster(self);
 
-  Check_Type(bucket_name, T_STRING);
-  Check_Type(name_space, T_SYMBOL);
+  cb_check_type(bucket_name, T_STRING);
+  cb_check_type(name_space, T_SYMBOL);
 
   core::design_document_namespace ns{};
   if (ID type = rb_sym2id(name_space); type == rb_intern("development")) {
@@ -55,8 +56,8 @@ cb_Backend_view_index_get_all(VALUE self,
   } else if (type == rb_intern("production")) {
     ns = core::design_document_namespace::production;
   } else {
-    rb_raise(rb_eArgError, "Unknown design document namespace: %+" PRIsVALUE, type);
-    return Qnil;
+    throw ruby_exception(rb_eArgError,
+                         cb_sprintf("Unknown design document namespace: %+" PRIsVALUE, name_space));
   }
 
   try {
@@ -106,10 +107,8 @@ cb_Backend_view_index_get_all(VALUE self,
     }
     return res;
   } catch (const std::system_error& se) {
-    rb_exc_raise(cb_map_error_code(
+    throw ruby_exception(cb_map_error_code(
       se.code(), fmt::format("failed to perform {}: {}", __func__, se.what()), false));
-  } catch (const ruby_exception& e) {
-    rb_exc_raise(e.exception_object());
   }
   return Qnil;
 }
@@ -124,9 +123,9 @@ cb_Backend_view_index_get(VALUE self,
 {
   auto cluster = cb_backend_to_core_api_cluster(self);
 
-  Check_Type(bucket_name, T_STRING);
-  Check_Type(document_name, T_STRING);
-  Check_Type(name_space, T_SYMBOL);
+  cb_check_type(bucket_name, T_STRING);
+  cb_check_type(document_name, T_STRING);
+  cb_check_type(name_space, T_SYMBOL);
 
   core::design_document_namespace ns{};
   if (ID type = rb_sym2id(name_space); type == rb_intern("development")) {
@@ -134,8 +133,8 @@ cb_Backend_view_index_get(VALUE self,
   } else if (type == rb_intern("production")) {
     ns = core::design_document_namespace::production;
   } else {
-    rb_raise(rb_eArgError, "Unknown design document namespace: %+" PRIsVALUE, type);
-    return Qnil;
+    throw ruby_exception(rb_eArgError,
+                         cb_sprintf("Unknown design document namespace: %+" PRIsVALUE, name_space));
   }
 
   try {
@@ -186,10 +185,8 @@ cb_Backend_view_index_get(VALUE self,
     rb_hash_aset(res, rb_id2sym(rb_intern("views")), views);
     return res;
   } catch (const std::system_error& se) {
-    rb_exc_raise(cb_map_error_code(
+    throw ruby_exception(cb_map_error_code(
       se.code(), fmt::format("failed to perform {}: {}", __func__, se.what()), false));
-  } catch (const ruby_exception& e) {
-    rb_exc_raise(e.exception_object());
   }
   return Qnil;
 }
@@ -204,9 +201,9 @@ cb_Backend_view_index_drop(VALUE self,
 {
   auto cluster = cb_backend_to_core_api_cluster(self);
 
-  Check_Type(bucket_name, T_STRING);
-  Check_Type(document_name, T_STRING);
-  Check_Type(name_space, T_SYMBOL);
+  cb_check_type(bucket_name, T_STRING);
+  cb_check_type(document_name, T_STRING);
+  cb_check_type(name_space, T_SYMBOL);
 
   core::design_document_namespace ns{};
   if (ID type = rb_sym2id(name_space); type == rb_intern("development")) {
@@ -214,8 +211,8 @@ cb_Backend_view_index_drop(VALUE self,
   } else if (type == rb_intern("production")) {
     ns = core::design_document_namespace::production;
   } else {
-    rb_raise(rb_eArgError, "Unknown design document namespace: %+" PRIsVALUE, type);
-    return Qnil;
+    throw ruby_exception(rb_eArgError,
+                         cb_sprintf("Unknown design document namespace: %+" PRIsVALUE, name_space));
   }
 
   try {
@@ -242,10 +239,8 @@ cb_Backend_view_index_drop(VALUE self,
     }
     return Qtrue;
   } catch (const std::system_error& se) {
-    rb_exc_raise(cb_map_error_code(
+    throw ruby_exception(cb_map_error_code(
       se.code(), fmt::format("failed to perform {}: {}", __func__, se.what()), false));
-  } catch (const ruby_exception& e) {
-    rb_exc_raise(e.exception_object());
   }
   return Qnil;
 }
@@ -260,9 +255,9 @@ cb_Backend_view_index_upsert(VALUE self,
 {
   auto cluster = cb_backend_to_core_api_cluster(self);
 
-  Check_Type(bucket_name, T_STRING);
-  Check_Type(document, T_HASH);
-  Check_Type(name_space, T_SYMBOL);
+  cb_check_type(bucket_name, T_STRING);
+  cb_check_type(document, T_HASH);
+  cb_check_type(name_space, T_SYMBOL);
 
   core::design_document_namespace ns{};
   if (ID type = rb_sym2id(name_space); type == rb_intern("development")) {
@@ -270,8 +265,8 @@ cb_Backend_view_index_upsert(VALUE self,
   } else if (type == rb_intern("production")) {
     ns = core::design_document_namespace::production;
   } else {
-    rb_raise(rb_eArgError, "Unknown design document namespace: %+" PRIsVALUE, type);
-    return Qnil;
+    throw ruby_exception(rb_eArgError,
+                         cb_sprintf("Unknown design document namespace: %+" PRIsVALUE, name_space));
   }
 
   try {
@@ -280,18 +275,18 @@ cb_Backend_view_index_upsert(VALUE self,
     req.document.ns = ns;
     if (VALUE document_name = rb_hash_aref(document, rb_id2sym(rb_intern("name")));
         !NIL_P(document_name)) {
-      Check_Type(document_name, T_STRING);
+      cb_check_type(document_name, T_STRING);
       req.document.name = cb_string_new(document_name);
     }
     if (VALUE views = rb_hash_aref(document, rb_id2sym(rb_intern("views"))); !NIL_P(views)) {
-      Check_Type(views, T_ARRAY);
+      cb_check_type(views, T_ARRAY);
       auto entries_num = static_cast<std::size_t>(RARRAY_LEN(views));
       for (std::size_t i = 0; i < entries_num; ++i) {
         VALUE entry = rb_ary_entry(views, static_cast<long>(i));
-        Check_Type(entry, T_HASH);
+        cb_check_type(entry, T_HASH);
         core::management::views::design_document::view view;
         VALUE name = rb_hash_aref(entry, rb_id2sym(rb_intern("name")));
-        Check_Type(name, T_STRING);
+        cb_check_type(name, T_STRING);
         view.name = cb_string_new(name);
         if (VALUE map = rb_hash_aref(entry, rb_id2sym(rb_intern("map"))); !NIL_P(map)) {
           view.map.emplace(cb_string_new(map));
@@ -322,10 +317,8 @@ cb_Backend_view_index_upsert(VALUE self,
     }
     return Qtrue;
   } catch (const std::system_error& se) {
-    rb_exc_raise(cb_map_error_code(
+    throw ruby_exception(cb_map_error_code(
       se.code(), fmt::format("failed to perform {}: {}", __func__, se.what()), false));
-  } catch (const ruby_exception& e) {
-    rb_exc_raise(e.exception_object());
   }
   return Qnil;
 }
@@ -341,10 +334,10 @@ cb_Backend_document_view(VALUE self,
 {
   auto cluster = cb_backend_to_core_api_cluster(self);
 
-  Check_Type(bucket_name, T_STRING);
-  Check_Type(design_document_name, T_STRING);
-  Check_Type(view_name, T_STRING);
-  Check_Type(name_space, T_SYMBOL);
+  cb_check_type(bucket_name, T_STRING);
+  cb_check_type(design_document_name, T_STRING);
+  cb_check_type(view_name, T_STRING);
+  cb_check_type(name_space, T_SYMBOL);
 
   core::design_document_namespace ns{};
   if (ID type = rb_sym2id(name_space); type == rb_intern("development")) {
@@ -352,11 +345,11 @@ cb_Backend_document_view(VALUE self,
   } else if (type == rb_intern("production")) {
     ns = core::design_document_namespace::production;
   } else {
-    rb_raise(rb_eArgError, "Unknown design document namespace: %+" PRIsVALUE, type);
-    return Qnil;
+    throw ruby_exception(rb_eArgError,
+                         cb_sprintf("Unknown design document namespace: %+" PRIsVALUE, name_space));
   }
   if (!NIL_P(options)) {
-    Check_Type(options, T_HASH);
+    cb_check_type(options, T_HASH);
   }
 
   try {
@@ -439,6 +432,17 @@ cb_Backend_document_view(VALUE self,
           req.keys.emplace_back(cb_string_new(entry));
         }
       }
+      if (VALUE raw_params = rb_hash_aref(options, rb_id2sym(rb_intern("raw_parameters")));
+          !NIL_P(raw_params)) {
+        cb_check_type(raw_params, T_HASH);
+        std::map<std::string, std::string> raw{};
+        cb_extract_string_hash(raw, raw_params, "raw_parameters");
+        // The core appends raw entries to the query string verbatim.
+        for (const auto& [name, value] : raw) {
+          req.raw[core::utils::string_codec::form_encode(name)] =
+            core::utils::string_codec::form_encode(value);
+        }
+      }
     }
 
     auto parent_span = cb_create_parent_span(req, self);
@@ -486,10 +490,8 @@ cb_Backend_document_view(VALUE self,
 
     return res;
   } catch (const std::system_error& se) {
-    rb_exc_raise(cb_map_error_code(
+    throw ruby_exception(cb_map_error_code(
       se.code(), fmt::format("failed to perform {}: {}", __func__, se.what()), false));
-  } catch (const ruby_exception& e) {
-    rb_exc_raise(e.exception_object());
   }
   return Qnil;
 }
@@ -499,11 +501,13 @@ cb_Backend_document_view(VALUE self,
 void
 init_views(VALUE cBackend)
 {
-  rb_define_method(cBackend, "document_view", cb_Backend_document_view, 6);
-
-  rb_define_method(cBackend, "view_index_get_all", cb_Backend_view_index_get_all, 4);
-  rb_define_method(cBackend, "view_index_get", cb_Backend_view_index_get, 5);
-  rb_define_method(cBackend, "view_index_drop", cb_Backend_view_index_drop, 5);
-  rb_define_method(cBackend, "view_index_upsert", cb_Backend_view_index_upsert, 5);
+  rb_define_method(cBackend, "document_view", cb_method<cb_Backend_document_view>::invoke, 6);
+
+  rb_define_method(
+    cBackend, "view_index_get_all", cb_method<cb_Backend_view_index_get_all>::invoke, 4);
+  rb_define_method(cBackend, "view_index_get", cb_method<cb_Backend_view_index_get>::invoke, 5);
+  rb_define_method(cBackend, "view_index_drop", cb_method<cb_Backend_view_index_drop>::invoke, 5);
+  rb_define_method(
+    cBackend, "view_index_upsert", cb_method<cb_Backend_view_index_upsert>::invoke, 5);
 }
 } // namespace couchbase::ruby

data/lib/active_support/cache/couchbase_store.rb

@@ -36,6 +36,13 @@ module ActiveSupport
     #       bucket: "app_cache"
     #     }
     #
+    # +delete_matched+ and +clear+ query with +consistent_with+ the store's writes.
+    # By default that covers the last write only, which leaves earlier writes to
+    # other vBuckets out of the query until the index catches up. With
+    # +mutation_tracking: :all+ the store keeps the newest mutation token of every
+    # vBucket it wrote to, so both see every earlier write. It also accepts an
+    # object that responds to +record(*tokens)+ and +mutation_state+.
+    #
     # @see https://guides.rubyonrails.org/caching_with_rails.html#cache-stores
     class CouchbaseStore < Store
       MAX_KEY_BYTESIZE = 250
@@ -43,6 +50,51 @@ module ActiveSupport
         logger&.error { "CouchbaseStore: #{method} failed, returned #{returning.inspect}: #{exception.class}: #{exception.message}" }
       end
 
+      # Default +mutation_tracking+: the token of the last write.
+      class LastMutation
+        def initialize
+          @token = nil
+        end
+
+        def record(*tokens)
+          latest = tokens.compact.max_by(&:sequence_number)
+          @token = latest if latest
+        end
+
+        def mutation_state
+          token = @token
+          token && ::Couchbase::MutationState.new(token)
+        end
+      end
+
+      # +mutation_tracking: :all+: the newest token of every vBucket written to,
+      # at most one per vBucket however many writes there were.
+      class AllMutations
+        def initialize
+          @tokens = {}
+          @lock = Mutex.new
+        end
+
+        def record(*tokens)
+          @lock.synchronize do
+            tokens.compact.each do |token|
+              key = [token.bucket_name, token.partition_id]
+              known = @tokens[key]
+              # After a failover the partition_uuid changes and sequence numbers
+              # do not compare across it, so the token recorded last is kept.
+              next if known && known.partition_uuid == token.partition_uuid && known.sequence_number >= token.sequence_number
+
+              @tokens[key] = token
+            end
+          end
+        end
+
+        def mutation_state
+          tokens = @lock.synchronize { @tokens.values }
+          ::Couchbase::MutationState.new(*tokens) unless tokens.empty?
+        end
+      end
+
       # Advertise cache versioning support.
       def self.supports_cache_versioning?
         true
@@ -70,7 +122,17 @@ module ActiveSupport
           @options.delete(:bucket) { raise ArgumentError, "Missing bucket for Couchbase cache store. Use :bucket in the store options" }
         @couchbase_options[:scope] = @options.delete(:scope) if @options.key?(:scope)
         @couchbase_options[:collection] = @options.delete(:collection) if @options.key?(:collection)
-        @last_mutation_token = nil
+        @mutations =
+          case (tracking = @options.delete(:mutation_tracking) { :last })
+          when :last, "last" then LastMutation.new
+          when :all, "all" then AllMutations.new
+          else
+            unless tracking.respond_to?(:record) && tracking.respond_to?(:mutation_state)
+              raise ArgumentError, "mutation_tracking must be :last, :all, or respond to #record and #mutation_state"
+            end
+
+            tracking
+          end
       end
 
       def collection
@@ -90,9 +152,10 @@ module ActiveSupport
       # The +matcher+ must be valid pattern for N1QL +REGEXP_MATCHES+ function. More info at
       # https://docs.couchbase.com/server/current/n1ql/n1ql-language-reference/patternmatchingfun.html#section_regex_matches
       #
-      # Because the operation performed on query engine, and it might take time to propagate changes
-      # from key/value engine to the indexer. Therefore the keys, that were created a moment ago
-      # might not be deleted.
+      # The query is consistent with the writes this store recorded, as selected by
+      # +mutation_tracking+. With the default +:last+, keys written shortly before the
+      # last write to other vBuckets might not be deleted. Writes by other processes
+      # are not covered.
       #
       # Also this method assumes, that primary index created on the target bucket
       def delete_matched(matcher, _options = nil)
@@ -106,7 +169,8 @@ module ActiveSupport
             raise NotImplementedError, "Unable to convert #{matcher.inspect} to Regexp pattern"
           end
         operation_options = ::Couchbase::Options::Query(named_parameters: {"pattern" => pattern}, metrics: true)
-        operation_options.consistent_with(::Couchbase::MutationState.new(@last_mutation_token)) if @last_mutation_token
+        mutation_state = @mutations.mutation_state
+        operation_options.consistent_with(mutation_state) if mutation_state
         begin
           result = cluster.query("DELETE FROM #{scope_qualifier} cache_store_ WHERE REGEXP_MATCHES(META(cache_store_).id, $pattern)",
                                  operation_options)
@@ -127,7 +191,7 @@ module ActiveSupport
             res = collection.binary.increment(
               key, ::Couchbase::Options::Increment(delta: amount, expiry: expires_in, initial: initial)
             )
-            @last_mutation_token = res.mutation_token
+            @mutations.record(res.mutation_token)
             res.content
           end
         end
@@ -147,7 +211,7 @@ module ActiveSupport
             res = collection.binary.decrement(
               key, ::Couchbase::Options::Decrement(delta: amount, expiry: expires_in, initial: initial)
             )
-            @last_mutation_token = res.mutation_token
+            @mutations.record(res.mutation_token)
             res.content
           end
         end
@@ -164,7 +228,8 @@ module ActiveSupport
             cluster.buckets.flush_bucket(@couchbase_options[:bucket_name])
           else
             operation_options = ::Couchbase::Options::Query.new
-            operation_options.consistent_with(::Couchbase::MutationState.new(@last_mutation_token)) if @last_mutation_token
+            mutation_state = @mutations.mutation_state
+            operation_options.consistent_with(mutation_state) if mutation_state
             cluster.query("DELETE FROM #{scope_qualifier}", operation_options)
           end
         end
@@ -239,7 +304,7 @@ module ActiveSupport
         end
         failsafe(:write_entry, returning: false) do
           res = collection.upsert(key, payload, ::Couchbase::Options::Upsert(transcoder: nil, expiry: expires_in))
-          @last_mutation_token = res.mutation_token
+          @mutations.record(res.mutation_token)
           true
         end
       end
@@ -259,7 +324,7 @@ module ActiveSupport
           successful = collection.upsert_multi(serialize_entries(entries, **options), operation_options).select(&:success?)
           return 0 if successful.empty?
 
-          @last_mutation_token = successful.max_by { |r| r.mutation_token.sequence_number }
+          @mutations.record(*successful.map(&:mutation_token))
           successful.count
         end
       end
@@ -269,7 +334,7 @@ module ActiveSupport
       def delete_entry(key, **_options)
         failsafe(:delete_entry, returning: false) do
           res = collection.remove(key)
-          @last_mutation_token = res.mutation_token
+          @mutations.record(res.mutation_token)
           true
         end
       end
@@ -282,7 +347,7 @@ module ActiveSupport
           successful = collection.remove_multi(entries).select(&:success?)
           return 0 if successful.empty?
 
-          @last_mutation_token = successful.max_by { |r| r.mutation_token.sequence_number }
+          @mutations.record(*successful.map(&:mutation_token))
           successful.count
         end
       end

data/lib/couchbase/bucket.rb

@@ -149,5 +149,25 @@ module Couchbase
         end
       end
     end
+
+    # Waits until the bucket reaches the desired state, actively pinging its services
+    #
+    # With +:online+, the wait also requires the bucket's vbucket map to be placed: every vbucket has its active copy
+    # and each replica the data nodes can hold assigned to a node. +:degraded+ only pings.
+    #
+    # +Thread#raise+ does not interrupt the wait. It ends on success, on +timeout+, or when the cluster is disconnected.
+    #
+    # @param [Integer, #in_milliseconds] timeout the maximum time to wait
+    # @param [Options::WaitUntilReady] options
+    #
+    # @return [void]
+    #
+    # @raise [Error::UnambiguousTimeout] if the desired state is not reached within +timeout+
+    # @raise [Error::ClusterClosed] if the cluster has been disconnected
+    # @raise [Error::InvalidArgument] if +timeout+ is negative or longer than 365 days, or +options+ name an
+    #   unsupported desired state or service type
+    def wait_until_ready(timeout, options = Options::WaitUntilReady::DEFAULT)
+      @backend.wait_until_ready(@name, Utils::Time.extract_duration(timeout), options.to_backend)
+    end
   end
 end

data/lib/couchbase/cluster.rb

@@ -348,6 +348,23 @@ module Couchbase
       end
     end
 
+    # Waits until the cluster reaches the desired state, actively pinging its services
+    #
+    # +Thread#raise+ does not interrupt the wait. It ends on success, on +timeout+, or when the cluster is disconnected.
+    #
+    # @param [Integer, #in_milliseconds] timeout the maximum time to wait
+    # @param [Options::WaitUntilReady] options
+    #
+    # @return [void]
+    #
+    # @raise [Error::UnambiguousTimeout] if the desired state is not reached within +timeout+
+    # @raise [Error::ClusterClosed] if the cluster has been disconnected
+    # @raise [Error::InvalidArgument] if +timeout+ is negative or longer than 365 days, or +options+ name an
+    #   unsupported desired state or service type
+    def wait_until_ready(timeout, options = Options::WaitUntilReady::DEFAULT)
+      @backend.wait_until_ready(nil, Utils::Time.extract_duration(timeout), options.to_backend)
+    end
+
     private
 
     # Initialize {Cluster} object

data/lib/couchbase/collection.rb

@@ -18,6 +18,7 @@ require "couchbase/errors"
 require "couchbase/collection_options"
 require "couchbase/binary_collection"
 require "couchbase/key_value_scan"
+require "couchbase/get_replica_strategy"
 
 module Couchbase
   # Provides access to all collection APIs
@@ -203,6 +204,40 @@ module Couchbase
       end
     end
 
+    # Reads the document from the replica the strategy selects.
+    #
+    # @param [String] id the document id which is used to uniquely identify it.
+    # @param [GetReplicaStrategy] strategy selects the replica to read from
+    # @param [Options::GetReplica] options request customization
+    #
+    # @example Read the document from the second replica
+    #   res = collection.get_replica("airline_10", GetReplicaStrategy.from_index(:second))
+    #   res.replica? #=> true
+    #   res.content["name"]
+    #
+    # @raise [Error::DocumentNotFoundOnReplica] if the replica does not hold the document
+    # @raise [Error::ReplicaIndexOutOfBounds] if the bucket is not configured with the requested replica
+    # @raise [Error::ReplicaIndexCurrentlyUnavailable] if the vbucket map places the requested replica on no node
+    # @raise [Error::UnambiguousTimeout] if the replica does not answer before the timeout
+    # @raise [Error::FeatureNotAvailable] over +couchbase2://+, which does not carry the operation
+    #
+    # @since 3.9.0
+    #
+    # @return [GetReplicaResult]
+    def get_replica(id, strategy, options = Options::GetReplica::DEFAULT)
+      @observability.record_operation(Observability::OP_GET_REPLICA, options.parent_span, self, :kv) do |obs_handler|
+        resp = @backend.document_get_replica(@bucket_name, @scope_name, @name, id, strategy.to_backend,
+                                             options.to_backend, obs_handler)
+        GetReplicaResult.new do |res|
+          res.transcoder = options.transcoder
+          res.cas = resp[:cas]
+          res.flags = resp[:flags]
+          res.encoded = resp[:content]
+          res.is_replica = true
+        end
+      end
+    end
+
     # Reads all available replicas and active, and returns the first found.
     #
     # @param [String] id the document id which is used to uniquely identify it.
@@ -210,7 +245,7 @@ module Couchbase
     #
     # @example Get document contents
     #   res = collection.get_any_replica("customer123")
-    #   res.is_active #=> false
+    #   res.replica? #=> true when a replica answered first, false for the active copy
     #   res.content["addresses"]
     #
     #   # {"billing"=>

data/lib/couchbase/errors.rb

@@ -185,6 +185,24 @@ module Couchbase
     class DocumentNotFound < CouchbaseError
     end
 
+    # Indicates that the replica selected by {Collection#get_replica} does not hold the document.
+    #
+    # @since 3.9.0
+    class DocumentNotFoundOnReplica < DocumentNotFound
+    end
+
+    # Indicates that {Collection#get_replica} requested a replica the bucket is not configured with.
+    #
+    # @since 3.9.0
+    class ReplicaIndexOutOfBounds < CouchbaseError
+    end
+
+    # Indicates that {Collection#get_replica} requested a configured replica. The vbucket map places it on no node.
+    #
+    # @since 3.9.0
+    class ReplicaIndexCurrentlyUnavailable < CouchbaseError
+    end
+
     # Indicates an operation completed but no successful document was retrievable.
     class DocumentIrretrievable < CouchbaseError
     end

data/lib/couchbase/fork_hooks.rb

@@ -17,14 +17,23 @@
 module Couchbase
   module ForkHooks
     def _fork
-      Couchbase::Backend.notify_fork(:prepare)
-      pid = super
-      if pid
-        Couchbase::Backend.notify_fork(:parent)
-      else
-        Couchbase::Backend.notify_fork(:child)
+      # :prepare stops the instances and only :parent or :child restarts them, so an asynchronous
+      # exception is deferred everywhere except inside the fork itself.
+      Thread.handle_interrupt(Object => :never) do
+        parent_pid = Process.pid
+        Couchbase::Backend.notify_fork(:prepare)
+        begin
+          Thread.handle_interrupt(Object => :immediate) do
+            # A check point: an interrupt deferred during :prepare lands here, before the fork.
+            Thread.pass
+            super
+          end
+        ensure
+          # Decided by pid rather than by the return value, which an exception raised after the fork
+          # never delivers.
+          Couchbase::Backend.notify_fork(Process.pid == parent_pid ? :parent : :child)
+        end
       end
-      pid
     end
   end
 end

data/lib/couchbase/get_replica_strategy.rb

@@ -0,0 +1,89 @@
+# frozen_string_literal: true
+
+#  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.
+
+require "couchbase/errors"
+
+module Couchbase
+  # Selects the replica that {Collection#get_replica} reads from.
+  #
+  # @since 3.9.0
+  class GetReplicaStrategy
+    REPLICA_INDEXES = {first: 0, second: 1, third: 2}.freeze
+    private_constant :REPLICA_INDEXES
+
+    # @return [Symbol] the requested replica, one of +:first+, +:second+ or +:third+
+    attr_reader :index
+
+    # @return [Boolean] whether an index that cannot be read resolves to the next replica that can
+    attr_reader :wrap
+
+    private_class_method :new
+
+    # Selects the replica at the given index.
+    #
+    # Without +wrap+, the SDK resolves the index against the vbucket map it already holds. No network round trip
+    # is made for these two errors:
+    # * an index at or beyond the bucket's configured replica count raises {Error::ReplicaIndexOutOfBounds}
+    # * a configured replica the vbucket map places on no node raises {Error::ReplicaIndexCurrentlyUnavailable}
+    #
+    # The replica is chosen from the vbucket map, not from node health. A replica on a node that is down is still
+    # chosen. The read can then wait for that node until the read times out.
+    #
+    # @param [Symbol] index the replica to read from, one of +:first+, +:second+ or +:third+
+    # @param [Boolean] wrap if +true+, an unreadable index moves to the next readable replica. The walk starts at the
+    #   index modulo the configured replica count. A bucket configured without replicas still raises
+    #   {Error::ReplicaIndexOutOfBounds}. If no replica is readable, it still raises
+    #   {Error::ReplicaIndexCurrentlyUnavailable}.
+    #
+    # @raise [Error::InvalidArgument] if +index+ is not one of the supported symbols, or +wrap+ is not a Boolean
+    #
+    # @example Read the first replica, or the next readable one
+    #   collection.get_replica("airline_10", GetReplicaStrategy.from_index(:first, wrap: true))
+    #
+    # @example Bound the wait for a replica whose node is down, then read any copy
+    #   begin
+    #     collection.get_replica("airline_10", GetReplicaStrategy.from_index(:first, wrap: true),
+    #                            Options::GetReplica(timeout: 500))
+    #   rescue Error::UnambiguousTimeout
+    #     collection.get_any_replica("airline_10")
+    #   end
+    #
+    # @return [GetReplicaStrategy]
+    def self.from_index(index, wrap: false)
+      unless REPLICA_INDEXES.key?(index)
+        raise Error::InvalidArgument, "replica index must be one of #{REPLICA_INDEXES.keys.inspect}, but given #{index.inspect}"
+      end
+      raise Error::InvalidArgument, "wrap must be a Boolean, but given #{wrap.inspect}" unless [true, false].include?(wrap)
+
+      new(index, wrap)
+    end
+
+    # @api private
+    def initialize(index, wrap)
+      @index = index
+      @wrap = wrap
+      freeze
+    end
+
+    # @api private
+    def to_backend
+      {
+        replica_index: REPLICA_INDEXES.fetch(@index),
+        wrap: @wrap,
+      }
+    end
+  end
+end