couchbase 3.4.3-arm64-darwin-20 → 3.4.5-arm64-darwin-20

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7781858dae225372665d58fecb6eccadbd09828de8324398143a6233ac2b8a26
-  data.tar.gz: 5f9886de965d9fc967e7c241cff4cffd284002e491e8438b42a054dbcacf7571
+  metadata.gz: 57331d93037221ed8fbe9284f153ea87233e09a777c2640490720502fa774706
+  data.tar.gz: e9efa936c5c41ed691f9814ad9a9e32df4d27f3e2ff1c87b7e8aa6a68de399c8
 SHA512:
-  metadata.gz: da37e980f2852accdaa22c27e214b8a1e9cc6edb5fd690a9c57c5b8db3daddb180b40e34fb4acdd25df5b76292f6a5b3fb158edad4d6ce5f27ea2877c08e90fd
-  data.tar.gz: 4c2e1d4aa7ae3f60dacd18e2edcf299ceca355c6f4b2a84264bf928df09e418a0484868a93f7166c89ad53d0b048637ccde0e4e33d608351f69102c11198cb93
+  metadata.gz: 38ad5e1953b01fec6f2019fd523a19dce4aefb58312f649164d36b7cfdcee9e6fa177e0183afbc92cc6d8a237392a8db8d9fdae059bf162c9cfd6ee36d0ff774
+  data.tar.gz: aec1ea54457a8483a993e7551e37e79c49f090e483c265738c4db7c8f3d4263cb1c845308c349ca4c13dd54e13d3be002d98a54a4ff3d32988281cb6385905d5

data/README.md

@@ -2,7 +2,7 @@
 
 [![license](https://img.shields.io/github/license/couchbase/couchbase-ruby-client?color=brightgreen)](https://opensource.org/licenses/Apache-2.0)
 [![gem](https://img.shields.io/gem/v/couchbase?color=brightgreen)](https://rubygems.org/gems/couchbase)
-[![commits](https://img.shields.io/github/commits-since/couchbase/couchbase-ruby-client/latest?color=brightgreen)](https://github.com/couchbase/couchbase-ruby-client/commits/master)
+[![commits](https://img.shields.io/github/commits-since/couchbase/couchbase-ruby-client/latest?color=brightgreen)](https://github.com/couchbase/couchbase-ruby-client/commits/main)
 [![linters](https://img.shields.io/github/actions/workflow/status/couchbase/couchbase-ruby-client/linters.yml?branch=main&label=linters)](https://github.com/couchbase/couchbase-ruby-client/actions?query=workflow%3Alinters)
 
 This repository contains the third generation of the official Couchbase SDK for Ruby (aka. SDKv3)
@@ -23,7 +23,7 @@ The library has been tested with MRI 3.0, 3.1 and 3.2. Supported platforms are L
 Add this line to your application's Gemfile:
 
 ```ruby
-gem "couchbase", "3.4.3"
+gem "couchbase", "3.4.5"
 ```
 
 And then execute:

data/lib/couchbase/cluster.rb

@@ -124,7 +124,7 @@ module Couchbase
               metrics.warning_count = resp[:meta][:metrics][:warning_count]
             end
           end
-          res[:warnings] = resp[:warnings].map { |warn| QueryWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
+          meta.warnings = resp[:warnings].map { |warn| QueryWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
         end
         res.instance_variable_set(:@rows, resp[:rows])
       end

data/lib/couchbase/collection.rb

@@ -15,6 +15,7 @@
 require "couchbase/errors"
 require "couchbase/collection_options"
 require "couchbase/binary_collection"
+require "couchbase/key_value_scan"
 
 module Couchbase
   # Provides access to all collection APIs
@@ -481,11 +482,68 @@ module Couchbase
             f.index = field[:index]
             f.path = field[:path]
             f.value = field[:value]
+            f.error = field[:error]
           end
         end
       end
     end
 
+    # Performs lookups to document fragments. Reads from the active node and all available replicas and returns the
+    # first result found
+    #
+    # @param [String] id the document id which is used to uniquely identify it.
+    # @param [Array<LookupInSpec>] specs the list of specifications which describe the types of the lookups to perform
+    # @param [Options::LookupInAnyReplica] options request customization
+    #
+    # @return [LookupInReplicaResult]
+    #
+    # @raise [Error::DocumentIrretrievable]
+    # @raise [Error::Timeout]
+    # @raise [Error::CouchbaseError]
+    # @raise [Error::FeatureNotAvailable]
+    def lookup_in_any_replica(id, specs, options = Options::LookupInAnyReplica::DEFAULT)
+      resp = @backend.document_lookup_in_any_replica(
+        bucket_name, @scope_name, @name, id,
+        specs.map do |s|
+          {
+            opcode: s.type,
+            xattr: s.xattr?,
+            path: s.path,
+          }
+        end, options.to_backend
+      )
+      extract_lookup_in_replica_result(resp, options)
+    end
+
+    # Performs lookups to document fragments. Reads from the active node and all available replicas and returns all of
+    # the results
+    #
+    # @param [String] id the document id which is used to uniquely identify it.
+    # @param [Array<LookupInSpec>] specs the list of specifications which describe the types of the lookups to perform
+    # @param [Options::LookupInAllReplicas] options request customization
+    #
+    # @return [Array<LookupInReplicaResult>]
+    #
+    # @raise [Error::DocumentNotFound]
+    # @raise [Error::Timeout]
+    # @raise [Error::CouchbaseError]
+    # @raise [Error::FeatureNotAvailable]
+    def lookup_in_all_replicas(id, specs, options = Options::LookupInAllReplicas::DEFAULT)
+      resp = @backend.document_lookup_in_all_replicas(
+        bucket_name, @scope_name, @name, id,
+        specs.map do |s|
+          {
+            opcode: s.type,
+            xattr: s.xattr?,
+            path: s.path,
+          }
+        end, options.to_backend
+      )
+      resp.map do |entry|
+        extract_lookup_in_replica_result(entry, options)
+      end
+    end
+
     # Performs mutations to document fragments
     #
     # @param [String] id the document id which is used to uniquely identify it.
@@ -535,6 +593,38 @@ module Couchbase
       end
     end
 
+    # Performs a key-value scan operation on the collection
+    #
+    # @api uncommitted
+    #
+    # @param [RangeScan, PrefixScan, SamplingScan] scan_type the type of the scan
+    # @param [Options::Scan] options request customization
+    #
+    # @example Get a sample of up to 5 documents from the collection and store their IDs in an array
+    #   result = collection.scan(SamplingScan.new(5), Options::Scan.new(ids_only: true))
+    #   ids = result.map { |item| item.id }
+    #
+    # @example Get all documents whose ID starts with 'customer_1' and output their content
+    #   result = collection.scan(PrefixScan.new("customer_1"))
+    #   result.each { |item| puts item.content }
+    #
+    # @example Get all documents with ID between 'customer_1' and 'customer_2', excluding 'customer_2' and output their content
+    #   result = collection.scan(RangeScan.new(
+    #     from: ScanTerm.new("customer_1"),
+    #     to: ScanTerm.new("customer_2", exclusive: true)
+    #   ))
+    #   result.each { |item| puts item.content }
+    #
+    # @return [ScanResults]
+    def scan(scan_type, options = Options::Scan::DEFAULT)
+      ScanResults.new(
+        core_scan_result: @backend.document_scan_create(
+          @bucket_name, @scope_name, @name, scan_type.to_backend, options.to_backend
+        ),
+        transcoder: options.transcoder
+      )
+    end
+
     private
 
     def extract_mutation_token(resp)
@@ -548,6 +638,24 @@ module Couchbase
       end
     end
 
+    def extract_lookup_in_replica_result(resp, options)
+      LookupInReplicaResult.new do |res|
+        res.transcoder = options.transcoder
+        res.cas = resp[:cas]
+        res.deleted = resp[:deleted]
+        res.is_replica = resp[:is_replica]
+        res.encoded = resp[:fields].map do |field|
+          SubDocumentField.new do |f|
+            f.exists = field[:exists]
+            f.index = field[:index]
+            f.path = field[:path]
+            f.value = field[:value]
+            f.error = field[:error]
+          end
+        end
+      end
+    end
+
     # @api private
     # TODO: deprecate in 3.1
     GetOptions = ::Couchbase::Options::Get

data/lib/couchbase/collection_options.rb

@@ -15,6 +15,9 @@
 require "rubygems/deprecate"
 
 require "couchbase/json_transcoder"
+require "couchbase/raw_string_transcoder"
+require "couchbase/raw_json_transcoder"
+require "couchbase/raw_binary_transcoder"
 require "couchbase/subdoc"
 require "couchbase/mutation_state"
 
@@ -164,7 +167,8 @@ module Couchbase
       # @return [Object] the decoded
       def content(path_or_index, transcoder = self.transcoder)
         field = get_field_at_index(path_or_index)
-        raise Error::PathNotFound, "Path is not found: #{path_or_index}" unless field.exists
+
+        raise field.error unless field.error.nil?
 
         transcoder.decode(field.value, :json)
       end
@@ -186,6 +190,8 @@ module Couchbase
           end
         return false unless field
 
+        raise field.error unless field.error.nil? || field.error.is_a?(Error::PathNotFound)
+
         field.exists
       end
 
@@ -227,6 +233,18 @@ module Couchbase
       end
     end
 
+    class LookupInReplicaResult < LookupInResult
+      # @return [Boolean] true if the document was read from a replica node
+      attr_accessor :is_replica
+      alias replica? is_replica
+
+      # @yieldparam [LookupInReplicaResult] self
+      def initialize
+        super
+        yield self if block_given?
+      end
+    end
+
     class MutateInResult < MutationResult
       # Decodes the content at the given index
       #
@@ -291,10 +309,91 @@ module Couchbase
       # @return [String] path
       attr_accessor :path
 
+      # @return [CouchbaseError] error
+      attr_accessor :error
+
       # @yieldparam [SubDocumentField] self
       def initialize
         yield self if block_given?
       end
     end
+
+    class ScanResult
+      # @return [String] identifier of the document
+      attr_accessor :id
+
+      # @return [Boolean] whether only ids are returned from this scan
+      attr_accessor :id_only
+
+      # @return [Integer, nil] holds the CAS value of the fetched document
+      attr_accessor :cas
+
+      # @return [Integer, nil] the expiration if fetched and present
+      attr_accessor :expiry
+
+      # @return [JsonTranscoder, RawBinaryTranscoder, RawJsonTranscoder, RawStringTranscoder, #decode] The default
+      #   transcoder which should be used
+      attr_accessor :transcoder
+
+      def initialize(id:, id_only:, cas: nil, expiry: nil, encoded: nil, flags: nil, transcoder: JsonTranscoder.new)
+        @id = id
+        @id_only = id_only
+        @cas = cas
+        @expiry = expiry
+        @encoded = encoded
+        @flags = flags
+        @transcoder = transcoder
+
+        yield self if block_given?
+      end
+
+      # Decodes the content of the document using given (or default transcoder)
+      #
+      # @param [JsonTranscoder, RawJsonTranscoder, RawBinaryTranscoder, RawStringTranscoder] transcoder custom transcoder
+      #
+      # @return [Object, nil]
+      def content(transcoder = self.transcoder)
+        return nil if @encoded.nil?
+
+        transcoder ? transcoder.decode(@encoded, @flags) : @encoded
+      end
+    end
+
+    class ScanResults
+      include Enumerable
+
+      def initialize(core_scan_result:, transcoder:)
+        @core_scan_result = core_scan_result
+        @transcoder = transcoder
+      end
+
+      def each
+        return enum_for(:each) unless block_given?
+
+        loop do
+          resp = @core_scan_result.next_item
+
+          break if resp.nil?
+
+          if resp[:id_only]
+            yield ScanResult.new(
+              id: resp[:id],
+              id_only: resp[:id_only],
+              transcoder: @transcoder
+            )
+          else
+            yield ScanResult.new(
+              id: resp[:id],
+              id_only: resp[:id_only],
+              cas: resp[:cas],
+              expiry: resp[:expiry],
+              encoded: resp[:encoded],
+              flags: resp[:flags],
+              transcoder: @transcoder
+            )
+          end
+        end
+      end
+    end
   end
 end

data/lib/couchbase/errors.rb

@@ -183,6 +183,11 @@ module Couchbase
     class DurableWriteReCommitInProgress < CouchbaseError
     end
 
+    # Happens when consistency requirements are specified but the partition uuid of the requirements do not align
+    # with the server
+    class MutationTokenOutdated < CouchbaseError
+    end
+
     # Subdocument exception thrown when a path does not exist in the document. The exact meaning of path existence
     # depends on the operation and inputs.
     class PathNotFound < CouchbaseError

data/lib/couchbase/key_value_scan.rb

@@ -0,0 +1,125 @@
+#  Copyright 2023. 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
+  # A scan term used to specify the bounds of a range scan
+  class ScanTerm
+    attr_accessor :term # @return [ScanTerm]
+    attr_accessor :exclusive # @return [Boolean]
+
+    # Creates an instance of a ScanTerm
+    #
+    # @api uncommitted
+    #
+    # @param [String] term the key pattern of this term
+    # @param [Boolean] exclusive specifies if this term is excluded while scanning, the bounds are included by default
+    def initialize(term, exclusive: false)
+      @term = term
+      @exclusive = exclusive
+    end
+
+    # @api private
+    def to_backend
+      {
+        term: @term,
+        exclusive: @exclusive,
+      }
+    end
+  end
+
+  # A range scan performs a scan on a range of keys
+  class RangeScan
+    attr_accessor :from # @return [ScanTerm, nil]
+    attr_accessor :to # @return [ScanTerm, nil]
+
+    # Creates an instance of a RangeScan scan type
+    #
+    # @api uncommitted
+    #
+    # @param [ScanTerm, String, nil] from the lower bound of the range, if set
+    # @param [ScanTerm, String, nil] to the upper bound of the range, if set
+    def initialize(from: nil, to: nil)
+      @from =
+        if from.nil? || from.instance_of?(ScanTerm)
+          from
+        else
+          ScanTerm(from)
+        end
+      @to =
+        if to.nil? || to.instance_of?(ScanTerm)
+          to
+        else
+          ScanTerm(to)
+        end
+    end
+
+    # @api private
+    def to_backend
+      {
+        scan_type: :range,
+        from: @from&.to_backend,
+        to: @to&.to_backend,
+      }
+    end
+  end
+
+  # A prefix scan performs a scan that includes all documents whose keys start with the given prefix
+  class PrefixScan
+    attr_accessor :prefix # @return [String]
+
+    # Creates an instance of a PrefixScan scan type
+    #
+    # @api uncommitted
+    #
+    # @param [String, nil] prefix the prefix all document keys should start with
+    def initialize(prefix)
+      @prefix = prefix
+    end
+
+    # @api private
+    def to_backend
+      {
+        scan_type: :prefix,
+        prefix: @prefix,
+      }
+    end
+  end
+
+  # A sampling scan performs a scan that randomly selects documents up to a configured limit
+  class SamplingScan
+    attr_accessor :limit # @return [Integer]
+    attr_accessor :seed # @return [Integer, nil]
+
+    # Creates an instance of a SamplingScan scan type
+    #
+    # @api uncommitted
+    #
+    # @param [Integer] limit the maximum number of documents the sampling scan can return
+    # @param [Integer, nil] seed the seed used for the random number generator that selects the documents. If not set,
+    #   a seed is generated at random
+    def initialize(limit, seed = nil)
+      @limit = limit
+      @seed = seed
+    end
+
+    # @api private
+    def to_backend
+      {
+        scan_type: :sampling,
+        limit: @limit,
+        seed: @seed,
+      }
+    end
+  end
+end

data/lib/couchbase/management/bucket_manager.rb

@@ -211,12 +211,15 @@ module Couchbase
             num_replicas: settings.num_replicas,
             replica_indexes: settings.replica_indexes,
             bucket_type: settings.bucket_type,
-            ejection_policy: settings.ejection_policy,
+            eviction_policy: settings.eviction_policy,
             max_expiry: settings.max_expiry,
             compression_mode: settings.compression_mode,
             minimum_durability_level: settings.minimum_durability_level,
             conflict_resolution_type: settings.conflict_resolution_type,
             storage_backend: settings.storage_backend,
+            history_retention_collection_default: settings.history_retention_collection_default,
+            history_retention_duration: settings.history_retention_duration,
+            history_retention_bytes: settings.history_retention_bytes,
           }, options.to_backend
         )
       end
@@ -239,11 +242,14 @@ module Couchbase
             num_replicas: settings.num_replicas,
             replica_indexes: settings.replica_indexes,
             bucket_type: settings.bucket_type,
-            ejection_policy: settings.ejection_policy,
+            eviction_policy: settings.eviction_policy,
             max_expiry: settings.max_expiry,
             compression_mode: settings.compression_mode,
             minimum_durability_level: settings.minimum_durability_level,
             storage_backend: settings.storage_backend,
+            history_retention_collection_default: settings.history_retention_collection_default,
+            history_retention_bytes: settings.history_retention_bytes,
+            history_retention_duration: settings.history_retention_duration,
           }, options.to_backend
         )
       end
@@ -334,6 +340,9 @@ module Couchbase
           bucket.minimum_durability_level = entry[:minimum_durability_level]
           bucket.compression_mode = entry[:compression_mode]
           bucket.instance_variable_set(:@healthy, entry[:nodes].all? { |node| node[:status] == "healthy" })
+          bucket.history_retention_collection_default = entry[:history_retention_collection_default]
+          bucket.history_retention_bytes = entry[:history_retention_bytes]
+          bucket.history_retention_duration = entry[:history_retention_duration]
         end
       end
     end
@@ -394,6 +403,17 @@ module Couchbase
       # @return [nil, :none, :majority, :majority_and_persist_to_active, :persist_to_majority] the minimum durability level
       attr_accessor :minimum_durability_level
 
+      # @return [Boolean, nil] whether to enable history retention on collections  by default
+      attr_accessor :history_retention_collection_default
+
+      # @return [Integer, nil] the maximum size, in bytes, of the change history that is written to disk for all
+      # collections in this bucket
+      attr_accessor :history_retention_bytes
+
+      # @return [Integer, nil] the maximum duration, in seconds, to be covered by the change history that is written to disk for all
+      # collections in this bucket
+      attr_accessor :history_retention_duration
+
       # @api private
       # @return [Boolean] false if status of the bucket is not healthy
       def healthy?
@@ -416,19 +436,6 @@ module Couchbase
 
       # @yieldparam [BucketSettings] self
       def initialize
-        @bucket_type = :couchbase
-        @name = nil
-        @minimum_durability_level = nil
-        @healthy = true
-        @flush_enabled = false
-        @ram_quota_mb = 100
-        @num_replicas = 1
-        @replica_indexes = false
-        @max_expiry = 0
-        @compression_mode = :passive
-        @conflict_resolution_type = :sequence_number
-        @eviction_policy = :value_only
-        @storage_backend = nil
         yield self if block_given?
       end
     end

data/lib/couchbase/management/collection_manager.rb

@@ -38,6 +38,8 @@ module Couchbase
             super
             yield self if block_given?
           end
+
+          DEFAULT = GetAllScopes.new.freeze
         end
 
         # Options for {CollectionManager#create_scope}
@@ -57,6 +59,8 @@ module Couchbase
             super
             yield self if block_given?
           end
+
+          DEFAULT = CreateScope.new.freeze
         end
 
         # Options for {CollectionManager#drop_scope}
@@ -76,6 +80,8 @@ module Couchbase
             super
             yield self if block_given?
           end
+
+          DEFAULT = DropScope.new.freeze
         end
 
         # Options for {CollectionManager#create_collection}
@@ -95,6 +101,29 @@ module Couchbase
             super
             yield self if block_given?
           end
+
+          DEFAULT = CreateCollection.new.freeze
+        end
+
+        # Options for {CollectionManager#update_collection}
+        class UpdateCollection < ::Couchbase::Options::Base
+          # Creates an instance of options for {CollectionManager#update_collection}
+          #
+          # @param [Integer, #in_milliseconds, nil] timeout the time in milliseconds allowed for the operation to complete
+          # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+          # @param [Hash, nil] client_context the client context data, if set
+          # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+          #
+          # @yieldparam [UpdateCollection] self
+          def initialize(timeout: nil,
+                         retry_strategy: nil,
+                         client_context: nil,
+                         parent_span: nil)
+            super
+            yield self if block_given?
+          end
+
+          DEFAULT = UpdateCollection.new.freeze
         end
 
         # Options for {CollectionManager#drop_collection}
@@ -114,6 +143,8 @@ module Couchbase
             super
             yield self if block_given?
           end
+
+          DEFAULT = DropCollection.new.freeze
         end
 
         # rubocop:disable Naming/MethodName constructor shortcuts
@@ -184,6 +215,8 @@ module Couchbase
               CollectionSpec.new do |collection|
                 collection.name = c[:name]
                 collection.scope_name = s[:name]
+                collection.max_expiry = c[:max_expiry]
+                collection.history = c[:history]
               end
             end
           end
@@ -232,29 +265,88 @@ module Couchbase
       end
 
       # Creates a new collection
+      # @overload create_collection(scope_name, collection_name, settings = CreateCollectionSettings::DEFAULT,
+      #  options = Options::Collection::CreateCollection::DEFAULT)
+      #   @param [String] scope_name the name of the scope the collection will be created in
+      #   @param [String] collection_name the name of the collection to be created
+      #   @param [CreateCollectionSettings] settings settings for the new collection
+      #   @param [Options::Collection::CreateCollection] options
       #
-      # @param [CollectionSpec] collection specification of the collection
-      # @param [Options::Collection::CreateCollection] options
+      # @overload create_collection(collection, options = Options::Collection::CreateCollection)
+      #   @param [CollectionSpec] collection specification of the collection
+      #   @param [Options::Collection::CreateCollection] options
+      #
+      #   @deprecated Use +#create_collection(scope_name, collection_name, settings, options)+ instead
       #
       # @return void
       #
       # @raise [ArgumentError]
-      # @raise [Error::CollectionExist]
+      # @raise [Error::CollectionExists]
+      # @raise [Error::ScopeNotFound]
+      def create_collection(*args)
+        if args[0].is_a?(CollectionSpec)
+          collection = args[0]
+          options = args[1] || Options::Collection::CreateCollection::DEFAULT
+          settings = CreateCollectionSettings.new(max_expiry: collection.max_expiry, history: collection.history)
+
+          warn "Calling create_collection with a CollectionSpec object has been deprecated, supply scope name, " \
+               "collection name and optionally a CreateCollectionSettings instance"
+
+          @backend.collection_create(@bucket_name, collection.scope_name, collection.name, settings.to_backend, options.to_backend)
+        else
+          scope_name = args[0]
+          collection_name = args[1]
+          settings = args[2] || CreateCollectionSettings::DEFAULT
+          options = args[3] || Options::Collection::CreateCollection::DEFAULT
+          @backend.collection_create(@bucket_name, scope_name, collection_name, settings.to_backend, options.to_backend)
+        end
+      end
+
+      # Updates the settings of an existing collection
+      #
+      # @param [String] scope_name the name of the scope the collection is in
+      # @param [String] collection_name the name of the collection to be updated
+      # @param [UpdateCollectionSettings] settings the settings that should be updated
+      #
+      # @raise [ArgumentError]
+      # @raise [Error::CollectionNotFound]
       # @raise [Error::ScopeNotFound]
-      def create_collection(collection, options = Options::Collection::CreateCollection.new)
-        @backend.collection_create(@bucket_name, collection.scope_name, collection.name, collection.max_expiry, options.to_backend)
+      def update_collection(scope_name, collection_name, settings = UpdateCollectionSettings::DEFAULT,
+                            options = Options::Collection::UpdateCollection::DEFAULT)
+        @backend.collection_update(@bucket_name, scope_name, collection_name, settings.to_backend, options.to_backend)
       end
 
       # Removes a collection
+      # @overload drop_collection(scope_name, collection_name, settings = CreateCollectionSettings::DEFAULT,
+      #   options = Options::Collection::CreateCollection::DEFAULT)
+      #   @param [String] scope_name the name of the scope the collection is in
+      #   @param [String] collection_name the name of the collection to be removed
       #
-      # @param [CollectionSpec] collection specification of the collection
-      # @param [Options::Collection::DropCollection] options
+      # @overload drop_collection(collection, options = Options::Collection::CreateCollection)
+      #   @param [CollectionSpec] collection specification of the collection
+      #   @param [Options::Collection::CreateCollection] options
+      #
+      #   @deprecated Use +#drop_collection(scope_name, collection_name, options)+ instead
       #
       # @return void
       #
+      # @raise [ArgumentError]
       # @raise [Error::CollectionNotFound]
-      def drop_collection(collection, options = Options::Collection::DropCollection.new)
-        @backend.collection_drop(@bucket_name, collection.scope_name, collection.name, options.to_backend)
+      # @raise [Error::ScopeNotFound]
+      def drop_collection(*args)
+        if args[0].is_a?(CollectionSpec)
+          collection = args[0]
+          options = args[1] || Options::Collection::CreateCollection::DEFAULT
+
+          warn "Calling drop_collection with a CollectionSpec object has been deprecated, supply scope name and collection name"
+
+          @backend.collection_drop(@bucket_name, collection.scope_name, collection.name, options.to_backend)
+        else
+          scope_name = args[0]
+          collection_name = args[1]
+          options = args[2] || Options::Collection::CreateCollection::DEFAULT
+          @backend.collection_drop(@bucket_name, scope_name, collection_name, options.to_backend)
+        end
       end
 
       # @deprecated use {CollectionManager#get_all_scopes} instead
@@ -289,6 +381,60 @@ module Couchbase
       DropCollectionOptions = ::Couchbase::Management::Options::Collection::DropCollection
     end
 
+    class CreateCollectionSettings
+      # @return [Integer, nil] time in seconds of the maximum expiration time for new documents in the collection
+      # (set to +nil+ to disable it)
+      attr_accessor :max_expiry
+
+      # @return [Boolean, nil] whether history retention override should be enabled in the collection (set to +nil+ to
+      # default to the bucket-level setting)
+      attr_accessor :history
+
+      def initialize(max_expiry: nil, history: nil)
+        @max_expiry = max_expiry
+        @history = history
+
+        yield self if block_given?
+      end
+
+      # @api private
+      def to_backend
+        {
+          max_expiry: @max_expiry,
+          history: @history,
+        }
+      end
+
+      DEFAULT = CreateCollectionSettings.new.freeze
+    end
+
+    class UpdateCollectionSettings
+      # @return [Integer, nil] time in seconds of the maximum expiration time for new documents in the collection
+      # (set to +nil+ to disable it)
+      attr_accessor :max_expiry
+
+      # @return [Boolean, nil] whether history retention override should be enabled in the collection (set to +nil+ to
+      # default to the bucket-level setting)
+      attr_accessor :history
+
+      def initialize(max_expiry: nil, history: nil)
+        @max_expiry = max_expiry
+        @history = history
+
+        yield self if block_given?
+      end
+
+      # @api private
+      def to_backend
+        {
+          max_expiry: @max_expiry,
+          history: @history,
+        }
+      end
+
+      DEFAULT = UpdateCollectionSettings.new.freeze
+    end
+
     class ScopeSpec
       # @return [String] name of the scope
       attr_accessor :name
@@ -312,6 +458,9 @@ module Couchbase
       # @return [Integer] time in seconds of the expiration for new documents in the collection (set to +nil+ to disable it)
       attr_accessor :max_expiry
 
+      # @return [Boolean, nil] whether history retention is enabled for this collection
+      attr_accessor :history
+
       # @yieldparam [CollectionSpec] self
       def initialize
         yield self if block_given?

data/lib/couchbase/options.rb

@@ -1026,6 +1026,151 @@ module Couchbase
       DEFAULT = LookupIn.new.freeze
     end
 
+    # Options for {Collection#lookup_in_any_replica}
+    class LookupInAnyReplica < Base
+      attr_accessor :transcoder # @return [JsonTranscoder, #decode(String)]
+
+      # Creates an instance of options for {Collection#lookup_in_any_replica}
+      #
+      # @param [JsonTranscoder, #decode(String)] transcoder used for encoding
+      #
+      # @param [Integer, #in_milliseconds, nil] timeout
+      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Hash, nil] client_context the client context data, if set
+      # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+      #
+      # @yieldparam [LookupIn] self
+      def initialize(transcoder: JsonTranscoder.new,
+                     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
+        yield self if block_given?
+      end
+
+      # @api private
+      def to_backend
+        {
+          timeout: Utils::Time.extract_duration(@timeout),
+        }
+      end
+
+      # @api private
+      # @return [Boolean]
+      attr_accessor :access_deleted
+
+      # @api private
+      DEFAULT = LookupInAnyReplica.new.freeze
+    end
+
+    # Options for {Collection#lookup_in_all_replicas}
+    class LookupInAllReplicas < Base
+      attr_accessor :transcoder # @return [JsonTranscoder, #decode(String)]
+
+      # Creates an instance of options for {Collection#lookup_in_all_replicas}
+      #
+      # @param [JsonTranscoder, #decode(String)] transcoder used for encoding
+      #
+      # @param [Integer, #in_milliseconds, nil] timeout
+      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Hash, nil] client_context the client context data, if set
+      # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+      #
+      # @yieldparam [LookupInAllReplicas] self
+      def initialize(transcoder: JsonTranscoder.new,
+                     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
+        yield self if block_given?
+      end
+
+      # @api private
+      def to_backend
+        {
+          timeout: Utils::Time.extract_duration(@timeout),
+        }
+      end
+
+      # @api private
+      DEFAULT = LookupInAllReplicas.new.freeze
+    end
+
+    # Options for {Collection#scan}
+    class Scan < Base
+      attr_accessor :ids_only # @return [Boolean]
+      attr_accessor :transcoder # @return [JsonTranscoder, #decode(String)]
+      attr_accessor :mutation_state # @return [MutationState, nil]
+      attr_accessor :batch_byte_limit # @return [Integer, nil]
+      attr_accessor :batch_item_limit # @return [Integer, nil]
+      attr_accessor :concurrency # @return [Integer, nil]
+
+      # Creates an instance of options for {Collection#scan}
+      #
+      # @param [Boolean] ids_only if set to true, the content of the documents is not included in the results
+      # @param [JsonTranscoder, #decode(String)] transcoder used for decoding
+      # @param [MutationState, nil] mutation_state sets the mutation tokens this scan should be consistent with
+      # @param [Integer, nil] batch_byte_limit allows to limit the maximum amount of bytes that are sent from the server
+      #   to the client on each partition batch, defaults to 15,000
+      # @param [Integer, nil] batch_item_limit allows to limit the maximum amount of items that are sent from the server
+      #   to the client on each partition batch, defaults to 50
+      # @param [Integer, nil] concurrency specifies the maximum number of partitions that can be scanned concurrently,
+      #   defaults to 1
+      #
+      # @param [Integer, #in_milliseconds, nil] timeout
+      # @param [Proc, nil] retry_strategy the custom retry strategy, if set
+      # @param [Hash, nil] client_context the client context data, if set
+      # @param [Span, nil] parent_span if set holds the parent span, that should be used for this request
+      #
+      # @yieldparam [LookupIn] self
+      def initialize(ids_only: false,
+                     transcoder: JsonTranscoder.new,
+                     mutation_state: nil,
+                     batch_byte_limit: nil,
+                     batch_item_limit: nil,
+                     concurrency: nil,
+                     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)
+        @ids_only = ids_only
+        @transcoder = transcoder
+        @mutation_state = mutation_state
+        @batch_byte_limit = batch_byte_limit
+        @batch_item_limit = batch_item_limit
+        @concurrency = concurrency
+        yield self if block_given?
+      end
+
+      # Sets the mutation tokens this query should be consistent with
+      #
+      # @note overrides consistency level set by {#scan_consistency=}
+      #
+      # @param [MutationState] mutation_state the mutation state containing the mutation tokens
+      def consistent_with(mutation_state)
+        @mutation_state = mutation_state
+      end
+
+      # @api private
+      def to_backend
+        {
+          timeout: Utils::Time.extract_duration(@timeout),
+          ids_only: @ids_only,
+          mutation_state: @mutation_state.to_a,
+          batch_byte_limit: @batch_byte_limit,
+          batch_item_limit: @batch_item_limit,
+          concurrency: @concurrency,
+        }
+      end
+
+      DEFAULT = Scan.new.freeze
+    end
+
     # Options for {BinaryCollection#append}
     class Append < Base
       attr_accessor :cas # @return [Integer]
@@ -1849,6 +1994,7 @@ module Couchbase
       attr_accessor :profile # @return [Symbol]
       attr_accessor :flex_index # @return [Boolean]
       attr_accessor :preserve_expiry # @return [Boolean]
+      attr_accessor :use_replica # @return [Boolean, nil]
       attr_accessor :scope_qualifier # @return [String]
       attr_accessor :transcoder # @return [JsonTranscoder, #decode(String)]
 
@@ -1894,6 +2040,8 @@ module Couchbase
       # @param [Boolean, nil] flex_index Tells the query engine to use a flex index (utilizing the search service)
       # @param [Boolean, nil] preserve_expiry Tells the query engine to preserve expiration values set on any documents
       #   modified by this query.
+      # @param [Boolean, nil] use_replica Specifies that the query engine should use replica nodes for KV fetches if
+      #   the active node is down. If not provided, the server default will be used
       # @param [String, nil] scope_qualifier Associate scope qualifier (also known as +query_context+) with the query.
       #   The qualifier must be in form +{bucket_name}.{scope_name}+ or +default:{bucket_name}.{scope_name}+.
       # @param [JsonTranscoder] transcoder to decode rows
@@ -1925,6 +2073,7 @@ module Couchbase
                      profile: :off,
                      flex_index: nil,
                      preserve_expiry: nil,
+                     use_replica: nil,
                      scope_qualifier: nil,
                      scan_consistency: :not_bounded,
                      mutation_state: nil,
@@ -1950,6 +2099,7 @@ module Couchbase
         @profile = profile
         @flex_index = flex_index
         @preserve_expiry = preserve_expiry
+        @use_replica = use_replica
         @scope_qualifier = scope_qualifier
         @scan_consistency = scan_consistency
         @mutation_state = mutation_state
@@ -2043,6 +2193,7 @@ module Couchbase
           readonly: @readonly,
           flex_index: @flex_index,
           preserve_expiry: @preserve_expiry,
+          use_replica: @use_replica,
           scan_wait: Utils::Time.extract_duration(@scan_wait),
           scan_cap: @scan_cap,
           pipeline_batch: @pipeline_batch,

data/lib/couchbase/scope.rb

@@ -79,7 +79,7 @@ module Couchbase
               metrics.warning_count = resp[:meta][:metrics][:warning_count]
             end
           end
-          res[:warnings] = resp[:warnings].map { |warn| Cluster::QueryWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
+          meta.warnings = resp[:warnings].map { |warn| Cluster::QueryWarning.new(warn[:code], warn[:message]) } if resp[:warnings]
         end
         res.instance_variable_set(:@rows, resp[:rows])
       end

data/lib/couchbase/utils/time.rb

@@ -48,8 +48,21 @@ module Couchbase
         end
       end
 
+      # This method converts its argument to milliseconds
+      #
+      # 1. Integer values are interpreted as a number of milliseconds
+      # 2. If the argument is a Duration-like object and responds to #in_milliseconds,
+      #    then use it and convert result to Integer
+      # 3. Otherwise invoke #to_i on the argument and interpret it as a number of milliseconds
       def extract_duration(number_or_duration)
-        number_or_duration.respond_to?(:in_milliseconds) ? number_or_duration.public_send(:in_milliseconds) : 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?
+
+        if number_or_duration.respond_to?(:in_milliseconds)
+          number_or_duration.public_send(:in_milliseconds)
+        else
+          number_or_duration
+        end.to_i
       end
     end
   end

data/lib/couchbase/version.rb

@@ -19,5 +19,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.4.3".freeze)
+  VERSION.update(:sdk => "3.4.5".freeze)
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: couchbase
 version: !ruby/object:Gem::Version
-  version: 3.4.3
+  version: 3.4.5
 platform: arm64-darwin-20
 authors:
 - Sergey Avseyev
 autorequire:
 bindir: exe
 cert_chain: []
-date: 2023-05-17 00:00:00.000000000 Z
+date: 2023-10-10 00:00:00.000000000 Z
 dependencies: []
 description: Modern SDK for Couchbase Server
 email:
@@ -41,6 +41,7 @@ files:
 - lib/couchbase/diagnostics.rb
 - lib/couchbase/errors.rb
 - lib/couchbase/json_transcoder.rb
+- lib/couchbase/key_value_scan.rb
 - lib/couchbase/libcouchbase.bundle
 - lib/couchbase/logger.rb
 - lib/couchbase/management.rb
@@ -77,9 +78,9 @@ metadata:
   homepage_uri: https://docs.couchbase.com/ruby-sdk/current/hello-world/start-using-sdk.html
   bug_tracker_uri: https://couchbase.com/issues/browse/RCBC
   mailing_list_uri: https://forums.couchbase.com/c/ruby-sdk
-  source_code_uri: https://github.com/couchbase/couchbase-ruby-client/tree/3.4.3
-  changelog_uri: https://github.com/couchbase/couchbase-ruby-client/releases/tag/3.4.3
-  documentation_uri: https://docs.couchbase.com/sdk-api/couchbase-ruby-client-3.4.3/index.html
+  source_code_uri: https://github.com/couchbase/couchbase-ruby-client/tree/3.4.5
+  changelog_uri: https://github.com/couchbase/couchbase-ruby-client/releases/tag/3.4.5
+  documentation_uri: https://docs.couchbase.com/sdk-api/couchbase-ruby-client-3.4.5/index.html
   github_repo: ssh://github.com/couchbase/couchbase-ruby-client
   rubygems_mfa_required: 'true'
 post_install_message: