couchbase 3.5.4 → 3.5.6

data/lib/couchbase/cluster.rb

@@ -48,7 +48,7 @@ module Couchbase
     #   @param [Options::Cluster, nil] options custom options when creating the cluster connection
     #
     # @example Explicitly create options object and initialize PasswordAuthenticator internally
-    #   options = Cluster::ClusterOptions.new
+    #   options = Options::Cluster.new
     #   options.authenticate("Administrator", "password")
     #   Cluster.connect("couchbase://localhost", options)
     #
@@ -354,7 +354,7 @@ module Couchbase
             raise ArgumentError, "options must have authenticator configured"
           end
         else
-          raise ArgumentError, "unexpected second argument, have to be String or ClusterOptions"
+          raise ArgumentError, "unexpected second argument, have to be String or Options::Cluster"
         end
       end
 
@@ -447,16 +447,5 @@ module Couchbase
         end
       end
     end
-
-    # @api private
-    ClusterOptions = ::Couchbase::Options::Cluster
-    # @api private
-    DiagnosticsOptions = ::Couchbase::Options::Diagnostics
-    # @api private
-    AnalyticsOptions = ::Couchbase::Options::Analytics
-    # @api private
-    QueryOptions = ::Couchbase::Options::Query
-    # @api private
-    SearchOptions = ::Couchbase::Options::Search
   end
 end

data/lib/couchbase/collection.rb

@@ -660,48 +660,5 @@ module Couchbase
         end
       end
     end
-
-    # @api private
-    # TODO: deprecate in 3.1
-    GetOptions = ::Couchbase::Options::Get
-    # @api private
-    # TODO: deprecate in 3.1
-    GetAndLockOptions = ::Couchbase::Options::GetAndLock
-    # @api private
-    # TODO: deprecate in 3.1
-    GetAndTouchOptions = ::Couchbase::Options::GetAndTouch
-    # @api private
-    # TODO: deprecate in 3.1
-    LookupInOptions = ::Couchbase::Options::LookupIn
-    # @api private
-    # TODO: deprecate in 3.1
-    MutateInOptions = ::Couchbase::Options::MutateIn
-    # @api private
-    # TODO: deprecate in 3.1
-    UnlockOptions = ::Couchbase::Options::Unlock
-    # @api private
-    # TODO: deprecate in 3.1
-    TouchOptions = ::Couchbase::Options::Touch
-    # @api private
-    # TODO: deprecate in 3.1
-    ReplaceOptions = ::Couchbase::Options::Replace
-    # @api private
-    # TODO: deprecate in 3.1
-    UpsertOptions = ::Couchbase::Options::Upsert
-    # @api private
-    # TODO: deprecate in 3.1
-    InsertOptions = ::Couchbase::Options::Insert
-    # @api private
-    # TODO: deprecate in 3.1
-    RemoveOptions = ::Couchbase::Options::Remove
-    # @api private
-    # TODO: deprecate in 3.1
-    ExistsOptions = ::Couchbase::Options::Exists
-    # @api private
-    # TODO: deprecate in 3.1
-    GetAnyReplicaOptions = ::Couchbase::Options::GetAnyReplica
-    # @api private
-    # TODO: deprecate in 3.1
-    GetAllReplicasOptions = ::Couchbase::Options::GetAllReplicas
   end
 end

data/lib/couchbase/collection_options.rb

@@ -80,7 +80,7 @@ module Couchbase
 
       # @deprecated Use {#expiry_time}
       # @return [Integer] the expiration if fetched and present
-      def expiry # rubocop:disable Style/TrivialAccessors will be removed in next major release
+      def expiry # rubocop:disable Style/TrivialAccessors -- will be removed in next major release
         @expiry
       end
 
@@ -211,7 +211,7 @@ module Couchbase
 
       # @api private
       #
-      # @see MutateInOptions#create_as_deleted
+      # @see Options::MutateIn#create_as_deleted
       #
       # @return [Boolean] true if the document is a tombstone (created in deleted state)
       def deleted?
@@ -273,7 +273,7 @@ module Couchbase
 
       # @api private
       #
-      # @see MutateInOptions#create_as_deleted
+      # @see Options::MutateIn#create_as_deleted
       #
       # @return [Boolean] true if the document is a tombstone (created in deleted state)
       def deleted?

data/lib/couchbase/datastructures/couchbase_queue.rb

@@ -112,7 +112,7 @@ module Couchbase
                                          LookupInSpec.get("[-1]"),
                                        ], @options.lookup_in_options)
         obj = result.exists?(0) ? result.content(0) : nil
-        options = Collection::MutateInOptions.new
+        options = Options::MutateIn.new
         options.cas = result.cas
         @collection.mutate_in(@id, [
                                 MutateInSpec.remove("[-1]"),

data/lib/couchbase/datastructures/couchbase_set.rb

@@ -109,7 +109,7 @@ module Couchbase
         idx = result.content.index(obj)
         return false unless idx
 
-        options = Collection::MutateInOptions.new
+        options = Options::MutateIn.new
         options.cas = result.cas
         @collection.mutate_in(@id, [
                                 MutateInSpec.remove("[#{idx}]"),

data/lib/couchbase/deprecations.rb

@@ -0,0 +1,61 @@
+# frozen_string_literal: true
+
+#  Copyright 2020-2025 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.
+
+module Couchbase
+  module Deprecations
+    def self.deprecate_constants(removed_in_version, parent, constants)
+      deprecator = Module.new do
+        define_method(:const_missing) do |old_name|
+          return super unless constants.key?(old_name)
+
+          new_name = constants[old_name]
+
+          warn "NOTE: #{name}::#{old_name} is deprecated; use Couchbase::#{new_name} instead. " \
+               "It will be removed in version #{removed_in_version}."
+          Couchbase.const_get(new_name)
+        end
+      end
+      parent.singleton_class.prepend(deprecator)
+    end
+  end
+
+  Deprecations.deprecate_constants("3.6.0", Cluster,
+                                   AnalyticsOptions: "Options::Analytics",
+                                   ClusterOptions: "Options::Cluster",
+                                   DiagnosticsOptions: "Options::Diagnostics",
+                                   QueryOptions: "Options::Query",
+                                   SearchOptions: "Options::Search")
+
+  Deprecations.deprecate_constants("3.6.0", Bucket,
+                                   PingOptions: "Options::Ping",
+                                   ViewOptions: "Options::View")
+
+  Deprecations.deprecate_constants("3.6.0", Collection,
+                                   ExistsOptions: "Options::Exists",
+                                   GetAllReplicasOptions: "Options::GetAllReplicas",
+                                   GetAndLockOptions: "Options::GetAndLock",
+                                   GetAndTouchOptions: "Options::GetAndTouch",
+                                   GetAnyReplicaOptions: "Options::GetAnyReplica",
+                                   GetOptions: "Options::Get",
+                                   InsertOptions: "Options::Insert",
+                                   LookupInOptions: "Options::LookupIn",
+                                   MutateInOptions: "Options::MutateIn",
+                                   RemoveOptions: "Options::Remove",
+                                   ReplaceOptions: "Options::Replace",
+                                   TouchOptions: "Options::Touch",
+                                   UnlockOptions: "Options::Unlock",
+                                   UpsertOptions: "Options::Upsert")
+end

data/lib/couchbase/fork_hooks.rb

@@ -0,0 +1,32 @@
+# frozen_string_literal: true
+
+#  Copyright 2020-2025 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.
+
+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)
+      end
+      pid
+    end
+  end
+end
+
+Process.singleton_class.prepend(Couchbase::ForkHooks)

data/lib/couchbase/logger.rb

@@ -46,7 +46,7 @@ module Couchbase
 
   # Return logger associated with the library
   def self.logger
-    @logger # rubocop:disable ThreadSafety/InstanceVariableInClassMethod
+    @logger # rubocop:disable ThreadSafety/ClassInstanceVariable
   end
 
   # Associate logger with the library
@@ -67,8 +67,8 @@ module Couchbase
   #
   # @since 3.4.0
   def self.set_logger(logger, adapter_class: nil, verbose: false, level: :info)
-    @logger = logger # rubocop:disable ThreadSafety/InstanceVariableInClassMethod
-    if @logger.nil? # rubocop:disable ThreadSafety/InstanceVariableInClassMethod
+    @logger = logger # rubocop:disable ThreadSafety/ClassInstanceVariable
+    if @logger.nil? # rubocop:disable ThreadSafety/ClassInstanceVariable
       Backend.install_logger_shim(nil)
       return
     end

data/lib/couchbase/management/analytics_index_manager.rb

@@ -513,7 +513,7 @@ module Couchbase
           end
         end
 
-        # rubocop:disable Naming/MethodName constructor shortcuts
+        # rubocop:disable Naming/MethodName -- constructor shortcuts
         module_function
 
         # Construct {CreateDataverse} options for {AnalyticsIndexManager#create_dataverse}

data/lib/couchbase/management/bucket_manager.rb

@@ -137,7 +137,7 @@ module Couchbase
           end
         end
 
-        # rubocop:disable Naming/MethodName constructor shortcuts
+        # rubocop:disable Naming/MethodName -- constructor shortcuts
         module_function
 
         # Construct {CreateBucket} options for {BucketManager#create_bucket}

data/lib/couchbase/management/collection_manager.rb

@@ -149,7 +149,7 @@ module Couchbase
           DEFAULT = DropCollection.new.freeze
         end
 
-        # rubocop:disable Naming/MethodName constructor shortcuts
+        # rubocop:disable Naming/MethodName -- constructor shortcuts
         module_function
 
         # Construct {GetAllScopes} options for {CollectionManager#get_all_scopes}

data/lib/couchbase/management/query_index_manager.rb

@@ -339,7 +339,7 @@ module Couchbase
           end
         end
 
-        # rubocop:disable Naming/MethodName constructor shortcuts
+        # rubocop:disable Naming/MethodName -- constructor shortcuts
         module_function
 
         # Construct {GetAllIndexes} options for {QueryIndexManager#get_all_indexes}

data/lib/couchbase/options.rb

@@ -237,10 +237,14 @@ module Couchbase
     # Options for {Collection#get_all_replicas}
     class GetAllReplicas < Base
       attr_accessor :transcoder # @return [JsonTranscoder, #decode(String, Integer)]
+      attr_accessor :read_preference # @return [Symbol]
 
       # Creates an instance of options for {Collection#get_all_replicas}
       #
       # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding
+      # @param [Symbol] read_preference decides how the replica nodes will be selected.
+      #  +:no_preference+:: no preference and will select any available replica. This is the default
+      #  +:selected_server_group+:: restrict to nodes in {Cluster#preferred_server_group}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
       # @param [Proc, nil] retry_strategy the custom retry strategy, if set
@@ -249,12 +253,14 @@ module Couchbase
       #
       # @yieldparam [GetAllReplicas] self
       def initialize(transcoder: JsonTranscoder.new,
+                     read_preference: :no_preference,
                      timeout: nil,
                      retry_strategy: nil,
                      client_context: nil,
                      parent_span: nil)
         super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span)
         @transcoder = transcoder
+        @read_preference = read_preference
         yield self if block_given?
       end
 
@@ -262,6 +268,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          read_preference: @read_preference,
         }
       end
 
@@ -272,10 +279,14 @@ module Couchbase
     # Options for {Collection#get_any_replica}
     class GetAnyReplica < Base
       attr_accessor :transcoder # @return [JsonTranscoder, #decode(String, Integer)]
+      attr_accessor :read_preference # @return [Symbol]
 
       # Creates an instance of options for {Collection#get_any_replica}
       #
       # @param [JsonTranscoder, #decode(String, Integer)] transcoder used for decoding
+      # @param [Symbol] read_preference decides how the replica nodes will be selected.
+      #  +:no_preference+:: no preference and will select any available replica. This is the default
+      #  +:selected_server_group+:: restrict to nodes in {Cluster#preferred_server_group}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
       # @param [Proc, nil] retry_strategy the custom retry strategy, if set
@@ -284,12 +295,14 @@ module Couchbase
       #
       # @yieldparam [GetAnyReplica] self
       def initialize(transcoder: JsonTranscoder.new,
+                     read_preference: :no_preference,
                      timeout: nil,
                      retry_strategy: nil,
                      client_context: nil,
                      parent_span: nil)
         super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span)
         @transcoder = transcoder
+        @read_preference = read_preference
         yield self if block_given?
       end
 
@@ -297,6 +310,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          read_preference: @read_preference,
         }
       end
 
@@ -1032,10 +1046,14 @@ module Couchbase
     # Options for {Collection#lookup_in_any_replica}
     class LookupInAnyReplica < Base
       attr_accessor :transcoder # @return [JsonTranscoder, #decode(String)]
+      attr_accessor :read_preference # @return [Symbol]
 
       # Creates an instance of options for {Collection#lookup_in_any_replica}
       #
       # @param [JsonTranscoder, #decode(String)] transcoder used for encoding
+      # @param [Symbol] read_preference decides how the replica nodes will be selected.
+      #  +:no_preference+:: no preference and will select any available replica. This is the default
+      #  +:selected_server_group+:: restrict to nodes in {Cluster#preferred_server_group}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
       # @param [Proc, nil] retry_strategy the custom retry strategy, if set
@@ -1044,12 +1062,14 @@ module Couchbase
       #
       # @yieldparam [LookupIn] self
       def initialize(transcoder: JsonTranscoder.new,
+                     read_preference: :no_preference,
                      timeout: nil,
                      retry_strategy: nil,
                      client_context: nil,
                      parent_span: nil)
         super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span)
         @transcoder = transcoder
+        @read_preference = read_preference
         yield self if block_given?
       end
 
@@ -1057,6 +1077,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          read_preference: @read_preference,
         }
       end
 
@@ -1071,10 +1092,14 @@ module Couchbase
     # Options for {Collection#lookup_in_all_replicas}
     class LookupInAllReplicas < Base
       attr_accessor :transcoder # @return [JsonTranscoder, #decode(String)]
+      attr_accessor :read_preference # @return [Symbol]
 
       # Creates an instance of options for {Collection#lookup_in_all_replicas}
       #
       # @param [JsonTranscoder, #decode(String)] transcoder used for encoding
+      # @param [Symbol] read_preference decides how the replica nodes will be selected.
+      #  +:no_preference+:: no preference and will select any available replica. This is the default
+      #  +:selected_server_group+:: restrict to nodes in {Cluster#preferred_server_group}
       #
       # @param [Integer, #in_milliseconds, nil] timeout
       # @param [Proc, nil] retry_strategy the custom retry strategy, if set
@@ -1083,12 +1108,14 @@ module Couchbase
       #
       # @yieldparam [LookupInAllReplicas] self
       def initialize(transcoder: JsonTranscoder.new,
+                     read_preference: :no_preference,
                      timeout: nil,
                      retry_strategy: nil,
                      client_context: nil,
                      parent_span: nil)
         super(timeout: timeout, retry_strategy: retry_strategy, client_context: client_context, parent_span: parent_span)
         @transcoder = transcoder
+        @read_preference = read_preference
         yield self if block_given?
       end
 
@@ -1096,6 +1123,7 @@ module Couchbase
       def to_backend
         {
           timeout: Utils::Time.extract_duration(@timeout),
+          read_preference: @read_preference,
         }
       end
 
@@ -1646,6 +1674,8 @@ module Couchbase
     class Cluster
       attr_accessor :authenticator # @return [PasswordAuthenticator, CertificateAuthenticator]
 
+      attr_accessor :preferred_server_group # @return [String]
+
       attr_accessor :enable_metrics # @return [Boolean]
       attr_accessor :metrics_emit_interval # @return [nil, Integer, #in_milliseconds]
       attr_accessor :enable_tracing # @return [Boolean]
@@ -1679,6 +1709,7 @@ module Couchbase
       # Creates an instance of options for {Couchbase::Cluster.connect}
       #
       # @param [PasswordAuthenticator, CertificateAuthenticator] authenticator
+      # @param [String] preferred_server_group the server group to use for replica APIs e.g. {Collection#get_all_replicas}
       # @param [nil, Integer, #in_milliseconds] key_value_timeout default timeout for Key/Value operations, e.g. {Collection#get}
       # @param [nil, Integer, #in_milliseconds] view_timeout default timeout for View query
       # @param [nil, Integer, #in_milliseconds] query_timeout default timeout for N1QL query
@@ -1690,6 +1721,7 @@ module Couchbase
       #
       # @yieldparam [Cluster] self
       def initialize(authenticator: nil,
+                     preferred_server_group: nil,
                      enable_metrics: nil,
                      metrics_emit_interval: nil,
                      enable_tracing: nil,
@@ -1719,6 +1751,7 @@ module Couchbase
                      config_idle_redial_timeout: nil,
                      idle_http_connection_timeout: nil)
         @authenticator = authenticator
+        @preferred_server_group = preferred_server_group
         @enable_metrics = enable_metrics
         @metrics_emit_interval = metrics_emit_interval
         @enable_tracing = enable_tracing
@@ -1765,6 +1798,7 @@ module Couchbase
       def to_backend
         {
           enable_metrics: @enable_metrics,
+          preferred_server_group: @preferred_server_group,
           metrics_emit_interval: Utils::Time.extract_duration(@metrics_emit_interval),
           enable_tracing: @enable_tracing,
           orphaned_emit_interval: Utils::Time.extract_duration(@orphaned_emit_interval),
@@ -2358,7 +2392,7 @@ module Couchbase
 
       # @param [:and, :or, nil] vector_query_combination
       #
-      # @yieldparam [VectorSearchOptions] self
+      # @yieldparam [Options::VectorSearch] self
       def initialize(vector_query_combination: nil)
         @vector_query_combination = vector_query_combination
 
@@ -2502,7 +2536,7 @@ module Couchbase
     # TODO: deprecate in 3.1
     CommonOptions = ::Couchbase::Options::Base
 
-    # rubocop:disable Naming/MethodName constructor shortcuts
+    # rubocop:disable Naming/MethodName -- constructor shortcuts
     module_function
 
     # Construct {Get} options for {Collection#get}
@@ -2841,6 +2875,20 @@ module Couchbase
       Scan.new(**args)
     end
 
+    # Construct {LookupInAnyReplica} options for {Collection#lookup_in_any_replica}
+    #
+    # @return [LookupInAnyReplica]
+    def LookupInAnyReplica(**args)
+      LookupInAnyReplica.new(**args)
+    end
+
+    # Construct {LookupInAllReplics} options for {Collection#lookup_in_all_replicas}
+    #
+    # @return [LookupInAllReplicas]
+    def LookupInAllReplicas(**args)
+      LookupInAllReplicas.new(**args)
+    end
+
     # rubocop:enable Naming/MethodName
   end
 end

data/lib/couchbase/protostellar/request_generator/query.rb

@@ -81,7 +81,7 @@ module Couchbase
             **proto_opts
           )
 
-          create_query_request(proto_req, :query, options, idempotent: options.readonly && true)
+          create_query_request(proto_req, :query, options, idempotent: options.readonly)
         end
 
         private

data/lib/couchbase/utils/time.rb

@@ -58,7 +58,7 @@ module Couchbase
       # 3. Otherwise invoke #to_i on the argument and interpret it as a number of milliseconds
       def extract_duration(number_or_duration)
         return unless number_or_duration
-        return number_or_duration if number_or_duration.class == Integer # rubocop:disable Style/ClassEqualityComparison avoid overrides of #is_a?, #kind_of?
+        return number_or_duration if number_or_duration.class == Integer # rubocop:disable Style/ClassEqualityComparison -- avoid overrides of #is_a?, #kind_of?
 
         if number_or_duration.respond_to?(:in_milliseconds)
           number_or_duration.in_milliseconds

data/lib/couchbase/version.rb

@@ -21,5 +21,5 @@ module Couchbase
   #   $ ruby -rcouchbase -e 'pp Couchbase::VERSION'
   #   {:sdk=>"3.4.0", :ruby_abi=>"3.1.0", :revision=>"416fe68e6029ec8a4c40611cf6e6b30d3b90d20f"}
   VERSION = {} unless defined?(VERSION) # rubocop:disable Style/MutableConstant
-  VERSION.update(:sdk => "3.5.4")
+  VERSION.update(:sdk => "3.5.6")
 end

data/lib/couchbase.rb

@@ -16,8 +16,10 @@
 
 require "couchbase/version"
 require "couchbase/libcouchbase"
+require "couchbase/fork_hooks"
 require "couchbase/logger"
 require "couchbase/cluster"
+require "couchbase/deprecations"
 
 require "couchbase/railtie" if defined?(Rails)