couchbase 3.0.0.alpha.5-x86_64-linux → 3.5.0-x86_64-linux

data/lib/couchbase/errors.rb

@@ -1,4 +1,4 @@
-#    Copyright 2020 Couchbase, Inc.
+#  Copyright 2020-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.
@@ -12,213 +12,365 @@
 #  See the License for the specific language governing permissions and
 #  limitations under the License.
 
+require "json"
+
 module Couchbase
+  # This namespace contains all error types that the library might raise.
   module Error
-    # Common exceptions
+    class CouchbaseError < StandardError
+      # @return [Hash] attributes associated with the error
+      attr_reader :context
 
-    class RequestCanceled < StandardError
+      def initialize(msg = nil, context = nil)
+        @context = context unless context.nil?
+        super(msg)
+      end
+
+      def to_s
+        defined?(@context) ? "#{super}, context=#{JSON.generate(@context)}" : super
+      end
     end
 
     class InvalidArgument < ArgumentError
+      # @return [Hash] attributes associated with the error
+      attr_reader :context
+
+      def initialize(msg = nil, context = nil)
+        @context = context unless context.nil?
+        super(msg)
+      end
+
+      def to_s
+        defined?(@context) ? "#{super}, context=#{JSON.generate(@context)}" : super
+      end
     end
 
-    class ServiceNotAvailable < StandardError
+    # Common exceptions
+
+    class RequestCanceled < CouchbaseError
     end
 
-    class InternalServerFailure < StandardError
+    class ServiceNotAvailable < CouchbaseError
     end
 
-    class AuthenticationFailure < StandardError
+    # Indicates an operation failed because there has been an internal error in the server.
+    class InternalServerFailure < CouchbaseError
     end
 
-    class TemporaryFailure < StandardError
+    # Every exception that has to do with authentication problems should either instantiate or subclass from this type.
+    class AuthenticationFailure < CouchbaseError
     end
 
-    class ParsingFailure < StandardError
+    # Indicates that the user has insufficient permissions to perform the operation
+    #
+    # @!macro uncommitted
+    class PermissionDenied < CouchbaseError
     end
 
-    class CasMismatch < StandardError
+    class TemporaryFailure < CouchbaseError
     end
 
-    class BucketNotFound < StandardError
+    # Indicates an operation failed because parsing of the input returned with an error.
+    class ParsingFailure < CouchbaseError
     end
 
-    class CollectionNotFound < StandardError
+    # Indicates an optimistic locking failure.
+    #
+    # The operation failed because the specified compare and swap (CAS) value differs from the document's actual CAS
+    # value. This means the document was modified since the original CAS value was acquired.
+    #
+    # The application should usually respond by fetching a fresh version of the document and repeating the failed
+    # operation.
+    class CasMismatch < CouchbaseError
     end
 
-    class ScopeNotFound < StandardError
+    class BucketNotFound < CouchbaseError
     end
 
-    class IndexNotFound < StandardError
+    class CollectionNotFound < CouchbaseError
     end
 
-    class IndexExists < StandardError
+    class ScopeNotFound < CouchbaseError
     end
 
-    class EncodingFailure < StandardError
+    class IndexNotFound < CouchbaseError
     end
 
-    class DecodingFailure < StandardError
+    class IndexExists < CouchbaseError
     end
 
-    class UnsupportedOperation < StandardError
+    # Raised when provided content could not be successfully encoded.
+    class EncodingFailure < CouchbaseError
     end
 
-    class AmbiguousTimeout < StandardError
+    # Raised when provided content could not be successfully decoded.
+    class DecodingFailure < CouchbaseError
     end
 
-    class UnambiguousTimeout < StandardError
+    class UnsupportedOperation < CouchbaseError
     end
 
-    class FeatureNotAvailable < StandardError
+    # The {Timeout} signals that an operation timed out before it could be completed.
+    #
+    # It is important to understand that the timeout itself is always just the effect an underlying cause, never the
+    # issue itself. The root cause might not even be on the application side, also the network and server need to be
+    # taken into account.
+    #
+    # Right now the SDK can throw two different implementations of this class:
+    #
+    # {AmbiguousTimeout}::
+    #   The operation might have caused a side effect on the server and should not be retried without
+    #   actions and checks.
+    #
+    # {UnambiguousTimeout}::
+    #   The operation has not caused a side effect on the server and is safe to retry. This is always the case for
+    #   idempotent operations. For non-idempotent operations it depends on the state the operation was in at the time of
+    #   cancellation.
+    class Timeout < CouchbaseError
+    end
+
+    # This is a special case of the timeout exception, signaling that the timeout happened with an ambiguous cause.
+    class AmbiguousTimeout < Timeout
+    end
+
+    # This is a special case of the timeout exception, signaling that the timeout happened with no ambiguous cause.
+    class UnambiguousTimeout < Timeout
+    end
+
+    # Exception which states that the feature is not available.
+    class FeatureNotAvailable < CouchbaseError
     end
 
     # KeyValue exceptions
 
-    class DocumentNotFound < StandardError
+    # Indicates an operation failed because the key does not exist.
+    class DocumentNotFound < CouchbaseError
     end
 
-    class DocumentIrretrievable < StandardError
+    # Indicates an operation completed but no successful document was retrievable.
+    class DocumentIrretrievable < CouchbaseError
     end
 
-    class DocumentLocked < StandardError
+    # Thrown when the server reports a temporary failure that is very likely to be lock-related (like an already locked
+    # key or a bad cas used for unlock).
+    #
+    # See https://issues.couchbase.com/browse/MB-13087 for an explanation of why this is only _likely_ to be
+    # lock-related.
+    class DocumentLocked < CouchbaseError
     end
 
-    class ValueTooLarge < StandardError
+    # Thrown when the server reports that the document is not locked when an unlocking operation is being performed.
+    class DocumentNotLocked < CouchbaseError
     end
 
-    class DocumentExists < StandardError
+    # Thrown when the request is too big for some reason.
+    class ValueTooLarge < CouchbaseError
     end
 
-    class DurabilityLevelNotAvailable < StandardError
+    # Indicates an operation failed because the key already exists.
+    class DocumentExists < CouchbaseError
     end
 
-    class DurabilityImpossible < StandardError
+    # This exception is raised when a durability level has been requested that is not available on the server.
+    class DurabilityLevelNotAvailable < CouchbaseError
     end
 
-    class DurabilityAmbiguous < StandardError
+    # The given durability requirements are currently impossible to achieve, as not enough configured replicas are
+    # currently available.
+    class DurabilityImpossible < CouchbaseError
     end
 
-    class DurableWriteInProgress < StandardError
+    # The synchronous replication durability work can return an ambiguous error (or we timeout waiting for the response,
+    # which is effectively the same).  Here we know the change is on a majority of replicas, or it's on none.
+    class DurabilityAmbiguous < CouchbaseError
     end
 
-    class DurableWriteReCommitInProgress < StandardError
+    # Returned if an attempt is made to mutate a key which already has a durable write pending.
+    class DurableWriteInProgress < CouchbaseError
     end
 
-    class PathNotFound < StandardError
+    # The requested key has a SyncWrite which is being re-committed.
+    class DurableWriteReCommitInProgress < CouchbaseError
     end
 
-    class PathMismatch < StandardError
+    # Happens when consistency requirements are specified but the partition uuid of the requirements do not align
+    # with the server
+    class MutationTokenOutdated < CouchbaseError
     end
 
-    class PathInvalid < StandardError
+    # 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
     end
 
-    class PathTooDeep < StandardError
+    # Subdocument exception thrown when the path structure conflicts with the document structure (for example, if a
+    # path mentions foo.bar[0].baz, but foo.bar is actually a JSON object).
+    class PathMismatch < CouchbaseError
     end
 
-    class PathTooBig < StandardError
+    # Subdocument exception thrown when path has a syntax error, or path syntax is incorrect for the operation (for
+    # example, if operation requires an array index).
+    class PathInvalid < CouchbaseError
     end
 
-    class ValueTooDeep < StandardError
+    # Subdocument exception thrown when path is too deep to parse. Depth of a path is determined by how many components
+    # (or levels) it contains.
+    #
+    # The current limitation is there to ensure a single parse does not consume too much memory (overloading the
+    # server). This error is similar to other TooDeep errors, which all relate to various validation stages to ensure
+    # the server does not consume too much memory when parsing a single document.
+    class PathTooDeep < CouchbaseError
     end
 
-    class ValueInvalid < StandardError
+    class PathTooBig < CouchbaseError
     end
 
-    class DocumentNotJson < StandardError
+    # Subdocument exception thrown when proposed value would make the document too deep to parse.
+    #
+    # The current limitation is there to ensure a single parse does not consume too much memory (overloading the
+    # server). This error is similar to other TooDeep errors, which all relate to various validation stages to ensure
+    # the server does not consume too much memory when parsing a single document.
+    class ValueTooDeep < CouchbaseError
     end
 
-    class NumberTooBig < StandardError
+    # Subdocument exception thrown when the provided value cannot be inserted at the given path.
+    #
+    # It is actually thrown when the delta in an counter operation is valid, but applying that delta would
+    # result in an out-of-range number (server interprets numbers as 64-bit integers).
+    class ValueInvalid < CouchbaseError
     end
 
-    class DeltaInvalid < StandardError
+    # Subdocument exception thrown when the targeted enclosing document itself is not JSON.
+    class DocumentNotJson < CouchbaseError
     end
 
-    class PathExists < StandardError
+    # Subdocument exception thrown when existing number value in document is too big.
+    #
+    # The value is interpreted as 64 bit on the server side.
+    class NumberTooBig < CouchbaseError
     end
 
-    class XattrUnknownMacro < StandardError
+    # Subdocument exception thrown when the delta in an arithmetic operation (eg counter) is invalid. In this SDK, this
+    # is equivalent to saying that the delta is zero.
+    #
+    # Note that the server also returns the corresponding error code when the delta value itself is too big, or not a
+    # number, but since the SDK enforces deltas to be of type long, these cases shouldn't come up.
+    class DeltaInvalid < CouchbaseError
     end
 
-    class XattrInvalidKeyCombo < StandardError
+    # Subdocument exception thrown when a path already exists and it shouldn't
+    class PathExists < CouchbaseError
     end
 
-    class XattrUnknownVirtualAttribute < StandardError
+    # Subdocument exception thrown when a macro has been requested which is not recognised by the server.
+    class XattrUnknownMacro < CouchbaseError
     end
 
-    class XattrCannotModifyVirtualAttribute < StandardError
+    # Subdocument exception thrown when more than one xattr key has been requested.
+    class XattrInvalidKeyCombo < CouchbaseError
     end
 
-    # Query exceptions
+    # Subdocument exception thrown when a virtual attribute has been requested which is not recognised by the server.
+    class XattrUnknownVirtualAttribute < CouchbaseError
+    end
 
-    class PlanningFailure < StandardError
+    # Subdocument exception thrown when the virtual attribute cannot be modified.
+    class XattrCannotModifyVirtualAttribute < CouchbaseError
     end
 
-    class IndexFailure < StandardError
+    # Query exceptions
+
+    # Indicates an operation failed because there has been an issue with the query planner.
+    class PlanningFailure < CouchbaseError
     end
 
-    class PreparedStatementFailure < StandardError
+    # Indicates an operation failed because there has been an issue with the query planner or similar.
+    class IndexFailure < CouchbaseError
     end
 
+    # Indicates an operation failed because there has been an issue with query prepared statements.
+    class PreparedStatementFailure < CouchbaseError
+    end
 
     # Analytics exceptions
 
-    class CompilationFailure < StandardError
+    # The analytics query failed to compile.
+    class CompilationFailure < CouchbaseError
+    end
+
+    # Indicates the analytics server job queue is full
+    class JobQueueFull < CouchbaseError
+    end
+
+    # The queried dataset is not found on the server.
+    class DatasetNotFound < CouchbaseError
     end
 
-    class JobQueueFull < StandardError
+    class DatasetExists < CouchbaseError
     end
 
-    class DatasetNotFound < StandardError
+    class DataverseExists < CouchbaseError
     end
 
-    class DatasetExists < StandardError
+    class DataverseNotFound < CouchbaseError
     end
 
-    class DataverseExists < StandardError
+    class LinkNotFound < CouchbaseError
     end
 
-    class DataverseNotFound < StandardError
+    class LinkExists < CouchbaseError
     end
 
-    class LinkNotFound < StandardError
+    # Search exceptions
+
+    class IndexNotReady < CouchbaseError
+    end
+
+    class ConsistencyMismatch < CouchbaseError
     end
 
     # View exceptions
 
-    class DesignDocumentNotFound < StandardError
+    class DesignDocumentNotFound < CouchbaseError
     end
 
-    class ViewNotFound < StandardError
+    # The queried view is not found on the server
+    class ViewNotFound < CouchbaseError
     end
 
     # Management exceptions
 
-    class CollectionExists < StandardError
+    class CollectionExists < CouchbaseError
     end
 
-    class ScopeExists < StandardError
+    class ScopeExists < CouchbaseError
     end
 
-    class UserExists < StandardError
+    class UserExists < CouchbaseError
     end
 
-    class BucketExists < StandardError
+    class BucketExists < CouchbaseError
     end
 
-    class BucketNotFlushable < StandardError
+    class BucketNotFlushable < CouchbaseError
     end
 
-    class GroupNotFound < StandardError
+    class GroupNotFound < CouchbaseError
     end
 
-    class UserNotFound < StandardError
+    class UserNotFound < CouchbaseError
     end
 
     # Library-specific exceptions
 
-    class BackendError < StandardError
+    class BackendError < CouchbaseError
+    end
+
+    # Environment name string cannot be determined
+    class NoEnvironment < CouchbaseError
+    end
+
+    class ClusterClosed < CouchbaseError
     end
   end
 end

data/lib/couchbase/json_transcoder.rb

@@ -1,4 +1,4 @@
-#    Copyright 2020 Couchbase, Inc.
+#  Copyright 2020-2021 Couchbase, Inc.
 #
 #  Licensed under the Apache License, Version 2.0 (the "License");
 #  you may not use this file except in compliance with the License.
@@ -14,19 +14,26 @@
 
 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 [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
+    # @return [Object] decoded document
     def decode(blob, flags)
-      JSON.parse(blob) unless blob.nil?
+      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
 end

data/lib/couchbase/key_value_scan.rb

@@ -0,0 +1,117 @@
+#  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
+    #
+    # @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
+    #
+    # @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
+    #
+    # @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
+    #
+    # @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/libcouchbase.rb

@@ -0,0 +1,6 @@
+        begin
+          require_relative "#{RUBY_VERSION[/(\d+\.\d+)/]}/libcouchbase"
+        rescue LoadError
+          raise LoadError, "unable to load couchbase extension for Ruby #{RUBY_VERSION}. Only available for 3.0, 3.1, 3.2, 3.3. " \
+            "Try to install couchbase from sources with 'gem install --platform ruby couchbase'"
+        end

data/lib/couchbase/logger.rb

@@ -0,0 +1,85 @@
+#  Copyright 2020-Present 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 "logger"
+
+module Couchbase
+  # Set log level
+  #
+  # @note The level might be also be set with environment variable +COUCHBASE_BACKEND_LOG_LEVEL+
+  #
+  # @param [Symbol] level new log level.
+  #
+  #   Allowed levels (in order of decreasing verbosity):
+  #   * +:trace+
+  #   * +:debug+
+  #   * +:info+ (default)
+  #   * +:warn+
+  #   * +:error+
+  #   * +:critical+
+  #   * +:off+
+  #
+  # @return [void]
+  def self.log_level=(level)
+    Backend.set_log_level(level)
+  end
+
+  # Get current log level
+  #
+  # @return [Symbol] current log level
+  def self.log_level
+    Backend.get_log_level
+  end
+
+  # Return logger associated with the library
+  def self.logger
+    @logger # rubocop:disable ThreadSafety/InstanceVariableInClassMethod
+  end
+
+  # Associate logger with the library
+  #
+  # The log messages, that are generated by extension might come with out of order timestamps, in order to reduce number
+  # of switches between Ruby and Native code.
+  #
+  # @param [Logger] logger an object implementing logging interface, e.g. stdlib Logger, or something that responds to
+  #   "level"-methods like +#debug+, +#error+, etc.
+  # @param [Class] adapter_class custom implementation of the logger adapter interface between extension and ruby code.
+  #   See {Utils::StdlibLoggerAdapter} and {Utils::GenericLoggerAdapter}
+  # @param [Boolean] verbose if true, the message will also include source code location, where the message was
+  #   generated (if available)
+  # @param [Symbol] level log level, see {::log_level=} for allowed values
+  #
+  # @example Specify custom logger and limit core messages to debug level
+  #   Couchbase.set_logger(Logger.new(STDERR), level: :debug)
+  #
+  # @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
+      Backend.install_logger_shim(nil)
+      return
+    end
+    shim =
+      if adapter_class
+        adapter_class
+      elsif logger.is_a?(::Logger)
+        require "couchbase/utils/stdlib_logger_adapter"
+        Utils::StdlibLoggerAdapter
+      else
+        require "couchbase/utils/generic_logger_adapter"
+        Utils::GenericLoggerAdapter
+      end
+    Backend.install_logger_shim(shim.new(logger, verbose: verbose), level)
+  end
+end