couchbase 3.5.0-x86_64-darwin-20

data/lib/couchbase/subdoc.rb

@@ -0,0 +1,290 @@
+#  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.
+#  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
+  class LookupInSpec
+    # Fetches the content from a field (if present) at the given path
+    #
+    # @param [String, Symbol] path the path identifying where to get the value. When path is a symbol, the library will try to expand it as
+    #   macro.
+    # @return [LookupInSpec]
+    def self.get(path)
+      case path
+      when Symbol
+        new(:get, expand_macro(path))
+      when ""
+        new(:get_doc, "")
+      else
+        new(:get, path)
+      end
+    end
+
+    # Checks if a value at the given path exists in the document
+    #
+    # @param [String] path the path to check if the field exists
+    # @return [LookupInSpec]
+    def self.exists(path)
+      new(:exists, path)
+    end
+
+    # Counts the number of values at a given path in the document
+    #
+    # @param [String] path the path identifying where to count the values
+    # @return [LookupInSpec]
+    def self.count(path)
+      new(:count, path)
+    end
+
+    def xattr
+      @xattr = true
+      self
+    end
+
+    def xattr?
+      @xattr
+    end
+
+    attr_reader :type
+    attr_reader :path
+
+    # @api private
+    #
+    # @param [Symbol] macro
+    # @raise [Error::XattrUnknownMacro] if the macro cannot be expanded
+    def self.expand_macro(macro)
+      case macro
+      when :document
+        "$document"
+      when :expiry_time, :expiration_time
+        "$document.exptime"
+      when :cas
+        "$document.CAS"
+      when :seq_no, :sequence_number
+        "$document.seqno"
+      when :last_modified
+        "$document.last_modified"
+      when :is_deleted
+        "$document.deleted"
+      when :value_size_bytes
+        "$document.value_bytes"
+      when :rev_id, :revision_id
+        "$document.revid"
+      else
+        raise Error::XattrUnknownMacro, "unknown macro #{macro}"
+      end
+    end
+
+    private_class_method :expand_macro
+
+    private
+
+    # @param [:get_doc, :get, :exists, :count] type of the lookup
+    # @param [String] path
+    def initialize(type, path)
+      @xattr = false
+      @type = type
+      @path = path
+    end
+  end
+
+  class MutateInSpec
+    # Creates a command with the intention of replacing an existing value in a JSON document.
+    #
+    # If the path is empty (""), then the value will be used for the document's full body. Will
+    # error if the last element of the path does not exist.
+    #
+    # @param [String] path the path identifying where to replace the value.
+    # @param [Object, Symbol] value the value to replace with.
+    #   When symbol specified and it is matches to known macro, it will be expanded
+    #
+    # @return [MutateInSpec]
+    def self.replace(path, value)
+      new(path.empty? ? :set_doc : :replace, path, value)
+    end
+
+    # Creates a command with the intention of inserting a new value in a JSON object.
+    #
+    # Will error if the last element of the path already exists.
+    #
+    # @param [String] path the path identifying where to insert the value.
+    # @param [Object, Symbol] value the value to insert.
+    #   When symbol specified and it is matches to known macro, it will be expanded
+    #
+    # @return [MutateInSpec]
+    def self.insert(path, value)
+      new(:dict_add, path, value)
+    end
+
+    # Creates a command with the intention of removing an existing value in a JSON object.
+    #
+    # Will error if the path does not exist.
+    #
+    # @param path the path identifying what to remove.
+    #
+    # @return [MutateInSpec]
+    def self.remove(path)
+      new(path.empty? ? :remove_doc : :remove, path, nil)
+    end
+
+    # Creates a command with the intention of upserting a value in a JSON object.
+    #
+    # That is, the value will be replaced if the path already exists, or inserted if not.
+    #
+    # @param [String] path the path identifying where to upsert the value.
+    # @param [Object, Symbol] value the value to upsert.
+    #   When symbol specified and it is matches to known macro, it will be expanded
+    #
+    # @return [MutateInSpec]
+    def self.upsert(path, value)
+      new(:dict_upsert, path, value)
+    end
+
+    # Creates a command with the intention of appending a value to an existing JSON array.
+    #
+    # Will error if the last element of the path does not exist or is not an array.
+    #
+    # @param [String] path the path identifying an array to which to append the value.
+    # @param [Array] values the value(s) to append.
+    #
+    # @return [MutateInSpec]
+    def self.array_append(path, values)
+      new(:array_push_last, path, values)
+    end
+
+    # Creates a command with the intention of prepending a value to an existing JSON array.
+    #
+    # Will error if the last element of the path does not exist or is not an array.
+    #
+    # @param [String] path the path identifying an array to which to append the value.
+    # @param [Array] values the value(s) to prepend.
+    #
+    # @return [MutateInSpec]
+    def self.array_prepend(path, values)
+      new(:array_push_first, path, values)
+    end
+
+    # Creates a command with the intention of inserting a value into an existing JSON array.
+    #
+    # Will error if the last element of the path does not exist or is not an array.
+    #
+    # @param [String] path the path identifying an array to which to append the value, and an index.  E.g. "foo.bar[3]"
+    # @param [Array] values the value(s) to insert.
+    #
+    # @return [MutateInSpec]
+    def self.array_insert(path, values)
+      new(:array_insert, path, values)
+    end
+
+    # Creates a command with the intent of inserting a value into an existing JSON array, but only if the value
+    # is not already contained in the array (by way of string comparison).
+    #
+    # Will error if the last element of the path does not exist or is not an array.
+    #
+    # @param [String] path the path identifying an array to which to append the value, and an index.  E.g. "foo.bar[3]"
+    # @param [Object, Symbol] value the value to insert.
+    #
+    # @return [MutateInSpec]
+    def self.array_add_unique(path, value)
+      new(:array_add_unique, path, value)
+    end
+
+    # Creates a command with the intent of incrementing a numerical field in a JSON object.
+    #
+    # If the field does not exist, then it is created and takes the value of +delta+
+    #
+    # @param [String] path the path identifying a numerical field to adjust or create
+    # @param [Integer] delta the value to increment the field by
+    #
+    # @return [MutateInSpec]
+    def self.increment(path, delta)
+      new(:counter, path, delta.abs)
+    end
+
+    # Creates a command with the intent of decrementing a numerical field in a JSON object.
+    #
+    # If the field does not exist, then it is created and takes the value of +delta+ * -1
+    #
+    # @param [String] path the path identifying a numerical field to adjust or create
+    # @param [Integer] delta the value to decrement the field by
+    #
+    # @return [MutateInSpec]
+    def self.decrement(path, delta)
+      new(:counter, path, -1 * delta.abs)
+    end
+
+    def xattr
+      @xattr = true
+      self
+    end
+
+    def create_path
+      @create_path = true
+      self
+    end
+
+    def xattr?
+      @xattr
+    end
+
+    def create_path?
+      @create_path
+    end
+
+    def expand_macros?
+      @expand_macros
+    end
+
+    CAS = "${Mutation.CAS}".freeze
+    SEQ_NO = "${Mutation.seqno}".freeze
+    VALUE_CRC32C = "${Mutation.value_crc32c}".freeze
+
+    attr_reader :type
+    attr_reader :path
+    attr_reader :param
+
+    private
+
+    def initialize(type, path, param)
+      @create_path = false
+      @param = nil
+      @xattr = false
+      @type = type
+      @path = path
+      @param =
+        case param
+        when :cas
+          CAS
+        when :seq_no, :sequence_number
+          SEQ_NO
+        when :value_crc32c, :value_crc
+          VALUE_CRC32C
+        else
+          param
+        end
+      @expand_macros = [CAS, SEQ_NO, VALUE_CRC32C].include?(@param)
+      @xattr = true if @expand_macros
+      return if @param.nil?
+
+      @param =
+        case type
+        when :counter
+          @param.to_i
+        when :array_push_first, :array_push_last, :array_insert
+          @param.map { |entry| JSON.generate(entry) }.join(",")
+        else
+          JSON.generate(@param)
+        end
+    end
+  end
+end

data/lib/couchbase/transcoder_flags.rb

@@ -0,0 +1,62 @@
+#  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
+  # @api private
+  class TranscoderFlags
+    FORMAT_MAP = {
+      reserved: 0,
+      private: 1,
+      json: 2,
+      binary: 3,
+      string: 4,
+    }.freeze
+    INV_FORMAT_MAP = FORMAT_MAP.invert.freeze
+
+    COMPRESSION_MAP = {none: 0}.freeze
+    INV_COMPRESSION_MAP = COMPRESSION_MAP.invert
+
+    attr_reader :format
+    attr_reader :compression
+    attr_reader :lower_bits
+
+    def initialize(format:, compression: :none, lower_bits: 0)
+      @format = format
+      @compression = compression
+      @lower_bits = lower_bits
+    end
+
+    def self.decode(flags)
+      return TranscoderFlags.new(format: flags) if flags.is_a?(Symbol)
+
+      common_flags = flags >> 24
+      lower_bits = flags & 0x00ffff
+
+      return TranscoderFlags.new(format: nil, lower_bits: lower_bits) if common_flags.zero?
+
+      compression_bits = common_flags >> 5
+      format_bits = common_flags & 0x0f
+      TranscoderFlags.new(
+        format: INV_FORMAT_MAP[format_bits],
+        compression: INV_COMPRESSION_MAP[compression_bits],
+        lower_bits: lower_bits
+      )
+    end
+
+    def encode
+      common_flags = (COMPRESSION_MAP[@compression] << 5) | FORMAT_MAP[@format]
+      (common_flags << 24) | @lower_bits
+    end
+  end
+end

data/lib/couchbase/utils/generic_logger_adapter.rb

@@ -0,0 +1,38 @@
+#   Copyright 2021 Couchbase, Inc.
+#  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 "time"
+
+module Couchbase
+  module Utils
+    class GenericLoggerAdapter
+      DATETIME_FORMAT = "%Y-%m-%dT%H:%M:%S.%6N".freeze
+
+      def initialize(logger, verbose: false)
+        @logger = logger
+        @verbose = verbose
+      end
+
+      def log(level, thread_id, seconds, nanoseconds, payload, filename, line, function)
+        return unless @logger.respond_to?(level)
+
+        progname = "cxxcbc##{thread_id}"
+        payload += " at #{filename}:#{line} #{function}" if @verbose && filename
+        @logger.send(level,
+                     "[#{::Time.at(seconds, nanoseconds, :nanosecond).strftime(DATETIME_FORMAT)} #{progname}]  #{level} -- #{payload}")
+      end
+    end
+  end
+end

data/lib/couchbase/utils/stdlib_logger_adapter.rb

@@ -0,0 +1,65 @@
+#   Copyright 2021 Couchbase, Inc.
+#  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"
+require "time"
+
+module Couchbase
+  module Utils
+    class StdlibLoggerAdapter
+      def initialize(logger, verbose: false)
+        raise ArgumentError, "logger argument must be or derive from stdlib Logger class" unless logger.is_a?(::Logger)
+
+        @logger = logger
+        @verbose = verbose
+      end
+
+      def log(level, thread_id, seconds, nanoseconds, payload, filename, line, function)
+        logdev = @logger.instance_variable_get(:@logdev)
+        return unless logdev
+
+        severity = map_spdlog_level(level)
+        return unless severity
+
+        progname = "cxxcbc##{thread_id}"
+        payload += " at #{filename}:#{line} #{function}" if @verbose && filename
+        logdev.write(
+          @logger.send(:format_message, @logger.send(:format_severity, severity), ::Time.at(seconds, nanoseconds, :nanosecond), progname,
+                       payload)
+        )
+      end
+
+      private
+
+      def map_spdlog_level(level)
+        case level
+        when :trace, :debug
+          ::Logger::Severity::DEBUG
+        when :info
+          ::Logger::Severity::INFO
+        when :warn
+          ::Logger::Severity::WARN
+        when :error
+          ::Logger::Severity::ERROR
+        when :critical
+          ::Logger::Severity::FATAL
+        else # rubocop:disable Style/EmptyElse
+          # covers :off
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/couchbase/utils/time.rb

@@ -0,0 +1,69 @@
+#  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.
+#  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 "time"
+
+module Couchbase
+  module Utils
+    # Various Time utilities
+    module Time
+      RELATIVE_EXPIRY_CUTOFF_SECONDS = 30 * 24 * 60 * 60
+      WORKAROUND_EXPIRY_CUTOFF_SECONDS = 50 * 365 * 24 * 60 * 60
+
+      module_function
+
+      # @param [Integer, #in_seconds, Time, nil] time_or_duration expiration time to associate with the document
+      def extract_expiry_time(time_or_duration)
+        if time_or_duration.respond_to?(:in_seconds) # Duration
+          [:duration, time_or_duration.in_seconds]
+        elsif time_or_duration.respond_to?(:tv_sec) # Time
+          [:time_point, time_or_duration.tv_sec]
+        elsif time_or_duration.is_a?(Integer)
+          if time_or_duration < RELATIVE_EXPIRY_CUTOFF_SECONDS
+            # looks like valid relative duration as specified in protocol (less than 30 days)
+            [:duration, time_or_duration]
+          elsif time_or_duration > WORKAROUND_EXPIRY_CUTOFF_SECONDS
+            effective_expiry = ::Time.at(time_or_duration).utc
+            warn "The specified expiry duration #{time_or_duration} is longer than 50 years. For bug-compatibility " \
+                 "with previous versions of SDK 3.0.x, the number of seconds in the duration will be interpreted as " \
+                 "the epoch second when the document should expire (#{effective_expiry}). Stuffing an epoch second " \
+                 "into a Duration is deprecated and will no longer work in SDK 3.1. Consider using Time instance instead."
+            [:time_point, time_or_duration]
+          else
+            [:time_point, ::Time.now.tv_sec + time_or_duration]
+          end
+        else
+          [:duration, time_or_duration]
+        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)
+        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
+end

data/lib/couchbase/utils.rb

@@ -0,0 +1,21 @@
+#  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.
+#  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 for internal tools, extensions and utilities
+  module Utils
+  end
+end
+
+require "couchbase/utils/time"

data/lib/couchbase/version.rb

@@ -0,0 +1,23 @@
+#  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.
+#  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
+  # Version of the library and all bundled dependencies
+  #
+  # @example Display version (+Couchbase::BUILD_INFO+ contains more details)
+  #   $ 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.0".freeze)
+end

data/lib/couchbase/view_options.rb

@@ -0,0 +1,65 @@
+#  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.
+#  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 "json"
+
+module Couchbase
+  class Bucket
+    class ViewRow
+      # @return [String]
+      attr_accessor :id
+
+      # @return [#to_json]
+      attr_accessor :key
+
+      # @return [#to_json]
+      attr_accessor :value
+
+      # @yieldparam [ViewRow] self
+      def initialize
+        yield self if block_given?
+      end
+    end
+
+    class ViewMetaData
+      # @return [Integer]
+      attr_accessor :total_rows
+
+      # @api private
+      attr_writer :debug_info
+
+      def debug
+        JSON.parse(@debug_info)
+      end
+
+      # @yieldparam [ViewMetaData] self
+      def initialize
+        yield self if block_given?
+      end
+    end
+
+    class ViewResult
+      # @return [ViewMetaData] returns object representing additional metadata associated with this query
+      attr_accessor :meta_data
+
+      # @return [Array<ViewRow>]
+      attr_accessor :rows
+
+      # @yieldparam [ViewResult] self
+      def initialize
+        yield self if block_given?
+      end
+    end
+  end
+end

data/lib/couchbase.rb

@@ -0,0 +1,28 @@
+#  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.
+#  You may obtain a copy of the License at
+#
+#      http://www.apache.org/licenses/LICENSE-2.0
+#
+#  Unless required by applicable law or agreed to in writing, software
+#  distributed under the License is distributed on an "AS IS" BASIS,
+#  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+#  See the License for the specific language governing permissions and
+#  limitations under the License.
+
+require "couchbase/version"
+require "couchbase/libcouchbase"
+require "couchbase/logger"
+require "couchbase/cluster"
+
+require "couchbase/railtie" if defined?(Rails)
+
+# @!macro uncommitted
+#   @couchbase.stability
+#     Uncommitted: This API may change in the future.
+#
+# @!macro volatile
+#   @couchbase.stability
+#     Volatile: This API is subject to change at any time.

data/lib/rails/generators/couchbase/config/config_generator.rb

@@ -0,0 +1,27 @@
+#  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.
+#  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 Generators
+    class ConfigGenerator < Rails::Generators::Base
+      desc "Creates a Couchbase configuration file at config/couchbase.yml"
+
+      source_root File.expand_path(File.join("..", "templates"), __FILE__)
+
+      def create_config_file
+        template "couchbase.yml", File.join("config", "couchbase.yml")
+      end
+    end
+  end
+end