couchbase 3.4.2 → 3.4.4

data/ext/revisions.rb

@@ -1,3 +1,3 @@
-cmake_flags << "-DEXT_GIT_REVISION=527358f7c022f5fa6c93cb4d0f95118db597cc08"
-cmake_flags << "-DCOUCHBASE_CXX_CLIENT_GIT_REVISION=98af5a9a2169c9bba284d3cb1e839b6f5e54c3b8"
-cmake_flags << "-DCOUCHBASE_CXX_CLIENT_GIT_DESCRIBE=1.0.0-dp.4-22-g98af5a9"
+cmake_flags << "-DEXT_GIT_REVISION=167d2e58559c91239675f1e7f7ffa2f6176f0512"
+cmake_flags << "-DCOUCHBASE_CXX_CLIENT_GIT_REVISION=43cf66a592d1f8112141a73e5a563d7187ee0ee6"
+cmake_flags << "-DCOUCHBASE_CXX_CLIENT_GIT_DESCRIBE=1.0.0-dp.8-0-g43cf66a"

data/lib/couchbase/authenticator.rb

@@ -28,7 +28,6 @@ module Couchbase
     def initialize(username, password)
       @username = username
       @password = password
-      @allowed_sasl_mechanisms = DEFAULT_SASL_MECHANISMS
     end
 
     # Creates a LDAP compatible password authenticator which is INSECURE if not used with TLS.

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
@@ -386,8 +386,6 @@ module Couchbase
         raise ArgumentError, "missing connection_string" unless connection_string
         raise ArgumentError, "missing username" unless credentials[:username]
         raise ArgumentError, "missing password" unless credentials[:password]
-
-        open_options[:allowed_sasl_mechanisms] = PasswordAuthenticator::DEFAULT_SASL_MECHANISMS
       else
         options = args.shift
         case options
@@ -396,8 +394,6 @@ module Couchbase
           credentials[:password] = args.shift
           raise ArgumentError, "missing username" unless credentials[:username]
           raise ArgumentError, "missing password" unless credentials[:password]
-
-          open_options[:allowed_sasl_mechanisms] = PasswordAuthenticator::DEFAULT_SASL_MECHANISMS
         when Options::Cluster
           open_options = options&.to_backend || {}
           authenticator = options&.authenticator

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,6 +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 field.error unless field.error.nil?
         raise Error::PathNotFound, "Path is not found: #{path_or_index}" unless field.exists
 
         transcoder.decode(field.value, :json)
@@ -186,6 +191,8 @@ module Couchbase
           end
         return false unless field
 
+        raise field.error unless field.error.nil?
+
         field.exists
       end
 
@@ -227,6 +234,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 +310,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/config_profiles.rb

@@ -15,7 +15,7 @@
 module Couchbase
   module ConfigProfiles
     class Profiles
-      attr :profiles
+      attr_reader :profiles
 
       def initialize
         @profiles = {}

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/json_transcoder.rb

@@ -14,18 +14,25 @@
 
 require "json"
 
+require "couchbase/transcoder_flags"
+
 module Couchbase
   class JsonTranscoder
     # @param [Object] document
     # @return [Array<String, Integer>] pair of encoded document and flags
     def encode(document)
-      [JSON.generate(document), (0x02 << 24) | 0x06]
+      raise Error::EncodingFailure, "The JsonTranscoder does not support binary data" if document.is_a?(String) && !document.valid_encoding?
+
+      [JSON.generate(document), TranscoderFlags.new(format: :json, lower_bits: 6).encode]
     end
 
-    # @param [String, nil] blob string of bytes, containing encoded representation of the document
-    # @param [Integer, :json] _flags bit field, describing how the data encoded
-    # @return Object decoded document
-    def decode(blob, _flags)
+    # @param [String] blob string of bytes, containing encoded representation of the document
+    # @param [Integer, :json] flags bit field, describing how the data encoded
+    # @return [Object] decoded document
+    def decode(blob, flags)
+      format = TranscoderFlags.decode(flags).format
+      raise Error::DecodingFailure, "Unable to decode #{format} with the JsonTranscoder" unless format == :json || format.nil?
+
       JSON.parse(blob) unless blob&.empty?
     end
   end

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/collection_query_index_manager.rb

@@ -14,6 +14,7 @@
 
 require "couchbase/management/query_index_manager"
 require "couchbase/utils/time"
+require "couchbase/errors"
 
 module Couchbase
   module Management
@@ -37,8 +38,18 @@ module Couchbase
       #
       # @return [Array<QueryIndex>]
       #
-      # @raise [ArgumentError]
+      # @raise [Error::InvalidArgument]
       def get_all_indexes(options = Options::Query::GetAllIndexes.new)
+        unless options.scope_name.nil?
+          raise Error::InvalidArgument,
+                "Scope name cannot be set in the options when using the Query Index manager at the collection level"
+        end
+
+        unless options.collection_name.nil?
+          raise Error::InvalidArgument,
+                "Collection name cannot be set in the options when using the Query Index manager at the collection level"
+        end
+
         res = @backend.collection_query_index_get_all(@bucket_name, @scope_name, @collection_name, options.to_backend)
         res[:indexes].map do |idx|
           QueryIndex.new do |index|
@@ -64,15 +75,17 @@ module Couchbase
       #
       # @return void
       #
-      # @raise [ArgumentError]
+      # @raise [Error::InvalidArgument]
       # @raise [Error::IndexExists]
       def create_index(index_name, fields, options = Options::Query::CreateIndex.new)
         unless options.scope_name.nil?
-          raise ArgumentError, "Scope name cannot be set in the options when using the Query Index manager at the collection level"
+          raise Error::InvalidArgument,
+                "Scope name cannot be set in the options when using the Query Index manager at the collection level"
         end
 
         unless options.collection_name.nil?
-          raise ArgumentError, "Collection name cannot be set in the options when using the Query Index manager at the collection level"
+          raise Error::InvalidArgument,
+                "Collection name cannot be set in the options when using the Query Index manager at the collection level"
         end
 
         @backend.collection_query_index_create(@bucket_name, @scope_name, @collection_name, index_name, fields, options.to_backend)
@@ -84,15 +97,17 @@ module Couchbase
       #
       # @return void
       #
-      # @raise [ArgumentError]
+      # @raise [Error::InvalidArgument]
       # @raise [Error::IndexExists]
       def create_primary_index(options = Options::Query::CreatePrimaryIndex.new)
         unless options.scope_name.nil?
-          raise ArgumentError, "Scope name cannot be set in the options when using the Query Index manager at the collection level"
+          raise Error::InvalidArgument,
+                "Scope name cannot be set in the options when using the Query Index manager at the collection level"
         end
 
         unless options.collection_name.nil?
-          raise ArgumentError, "Collection name cannot be set in the options when using the Query Index manager at the collection level"
+          raise Error::InvalidArgument,
+                "Collection name cannot be set in the options when using the Query Index manager at the collection level"
         end
 
         @backend.collection_query_index_create_primary(@bucket_name, @scope_name, @collection_name, options.to_backend)
@@ -105,15 +120,17 @@ module Couchbase
       #
       # @return void
       #
-      # @raise [ArgumentError]
+      # @raise [Error::InvalidArgument]
       # @raise [Error::IndexNotFound]
       def drop_index(index_name, options = Options::Query::DropIndex.new)
         unless options.scope_name.nil?
-          raise ArgumentError, "Scope name cannot be set in the options when using the Query Index manager at the collection level"
+          raise Error::InvalidArgument,
+                "Scope name cannot be set in the options when using the Query Index manager at the collection level"
         end
 
         unless options.collection_name.nil?
-          raise ArgumentError, "Collection name cannot be set in the options when using the Query Index manager at the collection level"
+          raise Error::InvalidArgument,
+                "Collection name cannot be set in the options when using the Query Index manager at the collection level"
         end
 
         @backend.collection_query_index_drop(@bucket_name, @scope_name, @collection_name, index_name, options.to_backend)
@@ -125,15 +142,17 @@ module Couchbase
       #
       # @return void
       #
-      # @raise [ArgumentError]
+      # @raise [Error::InvalidArgument]
       # @raise [Error::IndexNotFound]
       def drop_primary_index(options = Options::Query::DropPrimaryIndex.new)
         unless options.scope_name.nil?
-          raise ArgumentError, "Scope name cannot be set in the options when using the Query Index manager at the collection level"
+          raise Error::InvalidArgument,
+                "Scope name cannot be set in the options when using the Query Index manager at the collection level"
         end
 
         unless options.collection_name.nil?
-          raise ArgumentError, "Collection name cannot be set in the options when using the Query Index manager at the collection level"
+          raise Error::InvalidArgument,
+                "Collection name cannot be set in the options when using the Query Index manager at the collection level"
         end
 
         @backend.collection_query_index_drop_primary(@bucket_name, @scope_name, @collection_name, options.to_backend)
@@ -145,8 +164,18 @@ module Couchbase
       #
       # @return void
       #
-      # @raise [ArgumentError]
+      # @raise [Error::InvalidArgument]
       def build_deferred_indexes(options = Options::Query::BuildDeferredIndexes.new)
+        unless options.scope_name.nil?
+          raise Error::InvalidArgument,
+                "Scope name cannot be set in the options when using the Query Index manager at the collection level"
+        end
+
+        unless options.collection_name.nil?
+          raise Error::InvalidArgument,
+                "Collection name cannot be set in the options when using the Query Index manager at the collection level"
+        end
+
         @backend.collection_query_index_build_deferred(@bucket_name, @scope_name, @collection_name, options.to_backend)
       end
 
@@ -156,9 +185,19 @@ module Couchbase
       # @param [Integer, #in_milliseconds] timeout the time in milliseconds allowed for the operation to complete
       # @param [Options::Query::WatchIndexes] options
       #
-      # @raise [ArgumentError]
+      # @raise [Error::InvalidArgument]
       # @raise [Error::IndexNotFound]
       def watch_indexes(index_names, timeout, options = Options::Query::WatchIndexes.new)
+        unless options.scope_name.nil?
+          raise Error::InvalidArgument,
+                "Scope name cannot be set in the options when using the Query Index manager at the collection level"
+        end
+
+        unless options.collection_name.nil?
+          raise Error::InvalidArgument,
+                "Collection name cannot be set in the options when using the Query Index manager at the collection level"
+        end
+
         index_names.append("#primary") if options.watch_primary
 
         interval_millis = 50