couchbase 1.3.15 → 3.3.0

data/lib/active_support/cache/couchbase_store.rb

@@ -1,428 +1,337 @@
-# Author:: Couchbase <info@couchbase.com>
-# Copyright:: 2011, 2012 Couchbase, Inc.
-# License:: Apache License, Version 2.0
+#  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
+#  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.
+#      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'
-require 'securerandom'
-require 'active_support/core_ext/array/extract_options'
-require 'active_support/cache'
-require 'monitor'
+require "couchbase"
+require "digest/sha2"
+require "active_support/cache"
 
 module ActiveSupport
   module Cache
-    # This class implements Cache interface for Rails. To use it just
-    # put following line in your config/application.rb file:
+    # A cache store implementation which stores data in Couchbase: https://couchbase.com
+    #
+    # * Local cache. Hot in-memory primary cache within block/middleware scope.
+    # * +read_multi+ and +write_multi+ support.
+    # * +delete_matched+ support using N1QL queries.
+    # * +clear+ for erasing whole collection (optionally can flush the bucket).
     #
-    #   config.cache_store = :couchbase_store
+    # To use this store, add the select it in application config
     #
-    # You can also pass additional connection options there
+    #     config.cache_store = :couchbase_store, {
+    #       connection_string: "couchbase://localhost",
+    #       username: "app_cache_user",
+    #       password: "s3cret",
+    #       bucket: "app_cache"
+    #     }
     #
-    #   cache_options = {
-    #     :bucket => 'protected',
-    #     :username => 'protected',
-    #     :password => 'secret',
-    #     :expires_in => 30.seconds
-    #   }
-    #   config.cache_store = :couchbase_store, cache_options
+    # @see https://guides.rubyonrails.org/caching_with_rails.html#cache-stores
     class CouchbaseStore < Store
+      MAX_KEY_BYTESIZE = 250
+      DEFAULT_ERROR_HANDLER = lambda do |method:, returning:, exception:, logger: CouchbaseStore.logger|
+        logger&.error { "CouchbaseStore: #{method} failed, returned #{returning.inspect}: #{exception.class}: #{exception.message}" }
+      end
 
-      # Creates a new CouchbaseStore object, with the given options. For
-      # more info see {{Couchbase::Bucket#initialize}}
-      #
-      #   ActiveSupport::Cache::CouchbaseStore.new(:bucket => "cache")
-      #
-      # If no options are specified, then CouchbaseStore will connect to
-      # localhost port 8091 (default Couchbase Server port) and will use
-      # bucket named "default" which is always open for unauthorized access
-      # (if exists).
-      def initialize(*args)
-        args = [*(args.flatten)]
-        options = args.extract_options! || {}
-        @raise_errors = !options[:quiet] = !options.delete(:raise_errors)
-        options[:default_ttl] ||= options.delete(:expires_in)
-        options[:default_format] ||= :marshal
-        options[:key_prefix] ||= options.delete(:namespace)
-        @key_prefix = options[:key_prefix]
-        options[:connection_pool] ||= options.delete(:connection_pool)
-        args.push(options)
-
-        if options[:connection_pool]
-          if RUBY_VERSION.to_f < 1.9
-            warn "connection_pool gem doesn't support ruby < 1.9"
-          else
-            @data = ::Couchbase::ConnectionPool.new(options[:connection_pool], *args)
-          end
-        end
-        unless @data
-          @data = ::Couchbase::Bucket.new(*args)
-          @data.extend(Threadsafe)
-        end
+      # Advertise cache versioning support.
+      def self.supports_cache_versioning?
+        true
       end
 
-      # Fetches data from the cache, using the given key.
-      #
-      # @since 1.2.0.dp5
-      #
-      # If there is data in the cache with the given key, then that data is
-      # returned. If there is no such data in the cache (a cache miss),
-      # then nil will be returned. However, if a block has been passed, that
-      # block will be run in the event of a cache miss. The return value of
-      # the block will be written to the cache under the given cache key,
-      # and that return value will be returned.
-      #
-      # @param [String] name name for the key
-      # @param [Hash] options
-      # @option options [true, false] :force if this option is +true+ it
-      #   will force cache miss.
-      # @option options [Fixnum] :expires_in the expiration time on the
-      #   cache in seconds. Values larger than 30*24*60*60 seconds (30 days)
-      #   are interpreted as absolute times (from the epoch).
-      # @option options [true, false] :unless_exists if this option is +true+
-      #   it will write value only if the key doesn't exist in the database
-      #   (it accepts +:unless_exist+ too).
-      #
-      # @return [Object]
-      def fetch(name, options = nil)
-        options ||= {}
-        name = expanded_key(name)
-
-        if block_given?
-          unless options[:force]
-            entry = instrument(:read, name, options) do |payload|
-              payload[:super_operation] = :fetch if payload
-              read_entry(name, options)
-            end
-          end
+      prepend Strategy::LocalCache
 
-          if !entry.nil?
-            instrument(:fetch_hit, name, options) { |payload| }
-            entry
-          else
-            result = instrument(:generate, name, options) do |payload|
-              yield
-            end
-            write(name, result, options)
-            result
+      def initialize(options = nil)
+        super
+        @error_handler = @options.delete(:error_handler) { DEFAULT_ERROR_HANDLER }
+        @couchbase_options = {}
+        @couchbase_options[:connection_string] =
+          @options.delete(:connection_string) do
+            raise ArgumentError, "Missing connection string for Couchbase cache store. Use :connection_string in the store options"
           end
-        else
-          read(name, options)
-        end
+        @couchbase_options[:username] =
+          @options.delete(:username) do
+            raise ArgumentError, "Missing username for Couchbase cache store. Use :username in the store options"
+          end
+        @couchbase_options[:password] =
+          @options.delete(:password) do
+            raise ArgumentError, "Missing password for Couchbase cache store. Use :password in the store options"
+          end
+        @couchbase_options[:bucket] =
+          @options.delete(:bucket) { raise ArgumentError, "Missing bucket for Couchbase cache store. Use :bucket in the store options" }
+        @couchbase_options[:scope] = @options.delete(:scope) if @options.key?(:scope)
+        @couchbase_options[:collection] = @options.delete(:collection) if @options.key?(:collection)
+        @last_mutation_token = nil
       end
 
-      # Writes the value to the cache, with the key
-      #
-      # @since 1.2.0.dp5
-      #
-      # @param [String] name name for the key
-      # @param [Object] value value of the key
-      # @param [Hash] options
-      # @option options [Fixnum] :expires_in the expiration time on the
-      #   cache in seconds. Values larger than 30*24*60*60 seconds (30 days)
-      #   are interpreted as absolute times (from the epoch).
-      #
-      # @return [Fixnum, false] false in case of failure and CAS value
-      #   otherwise (it could be used as true value)
-      def write(name, value, options = nil)
-        options ||= {}
-        name = expanded_key name
-        if options.delete(:raw)
-          options[:format] = :plain
-          value = value.to_s
-          value.force_encoding(Encoding::BINARY) if defined?(Encoding)
-        end
-
-        instrument(:write, name, options) do |payload|
-          write_entry(name, value, options)
-        end
+      def collection
+        @collection ||= build_collection
       end
 
-      # Fetches data from the cache, using the given key.
-      #
-      # @since 1.2.0.dp5
-      #
-      # If there is data in the cache with the given key, then that data is
-      # returned.  Otherwise, nil is returned.
-      #
-      # @param [String] name name for the key
-      # @param [Hash] options
-      # @option options [Fixnum] :expires_in the expiration time on the
-      #   cache in seconds. Values larger than 30*24*60*60 seconds (30 days)
-      #   are interpreted as absolute times (from the epoch).
-      # @option options [true, false] :raw do not marshal the value if this
-      #   option is +true+
-      #
-      # @return [Object]
-      def read(name, options = nil)
-        options ||= {}
-        name = expanded_key name
-        if options.delete(:raw)
-          options[:format] = :plain
-        end
+      def cluster
+        @cluster ||= build_cluster
+      end
 
-        instrument(:read, name, options) do |payload|
-          entry = read_entry(name, options)
-          payload[:hit] = !!entry if payload
-          entry
-        end
+      def inspect
+        "#<#{self.class} options=#{options.inspect} collection=#{@collection.inspect}>"
       end
 
-      # Read multiple values at once from the cache.
-      #
-      # @since 1.2.0.dp5
+      # Deletes all entries with keys matching the regular expression.
       #
-      # Options can be passed in the last argument.
+      # The +matcher+ must be valid pattern for N1QL +REGEXP_MATCHES+ function. More info at
+      # https://docs.couchbase.com/server/current/n1ql/n1ql-language-reference/patternmatchingfun.html#section_regex_matches
       #
-      # Returns a hash mapping the names provided to the values found.
+      # Because the operation performed on query engine, and it might take time to propagate changes
+      # from key/value engine to the indexer. Therefore the keys, that were created a moment ago
+      # might not be deleted.
       #
-      # @return [Hash] key-value pairs
-      def read_multi(*names)
-        options = names.extract_options!
-        names = names.flatten.map{|name| expanded_key(name)}
-        options[:assemble_hash] = true
-        if options.delete(:raw)
-          options[:format] = :plain
-        end
-        instrument(:read_multi, names, options) do
-          @data.get(names, options)
+      # Also this method assumes, that primary index created on the target bucket
+      def delete_matched(matcher, _options = nil)
+        pattern =
+          case matcher
+          when Regexp
+            matcher.inspect[1..-2]
+          when String
+            matcher.tr("?", ".").gsub("*", ".*")
+          else
+            raise NotImplementedError, "Unable to convert #{matcher.inspect} to Regexp pattern"
+          end
+        operation_options = ::Couchbase::Options::Query(named_parameters: {"pattern" => pattern}, metrics: true)
+        operation_options.consistent_with(::Couchbase::MutationState.new(@last_mutation_token)) if @last_mutation_token
+        begin
+          result = cluster.query("DELETE FROM #{scope_qualifier} cache WHERE REGEXP_MATCHES(META(cache).id, $pattern)", operation_options)
+          result.meta_data.metrics.mutation_count
+        rescue ::Couchbase::Error::ParsingFailure, ::Couchbase::Error::ServiceNotAvailable
+          raise NotImplementedError, "The server does not support delete_matched operation"
         end
-      rescue ::Couchbase::Error::Base => e
-        logger.error("#{e.class}: #{e.message}") if logger
-        raise if @raise_errors
-        false
       end
 
-      # Return true if the cache contains an entry for the given key.
-      #
-      # @since 1.2.0.dp5
+      # Increments an integer value in the cache.
       #
-      # @return [true, false]
-      def exists?(name, options = nil)
-        options ||= {}
-        name = expanded_key name
-
-        instrument(:exists?, name) do
-          !read_entry(name, options).nil?
+      # Note that it uses binary collection interface, therefore will fail if the value is not
+      # represented as ASCII-encoded number using +:raw+.
+      def increment(name, amount = 1, expires_in: nil, initial: nil, **options)
+        instrument :increment, name, amount: amount do
+          failsafe :increment do
+            key = normalize_key(name, options)
+            res = collection.binary.increment(
+              key, ::Couchbase::Options::Increment(delta: amount, expiry: expires_in, initial: initial)
+            )
+            @last_mutation_token = res.mutation_token
+            res.content
+          end
         end
       end
-      alias :exist? :exists?
 
-      # Deletes an entry in the cache.
+      # Decrements an integer value in the cache.
       #
-      # @since 1.2.0.dp5
+      # Note that it uses binary collection interface, therefore will fail if the value is not
+      # represented as ASCII-encoded number using +:raw+.
       #
-      # @return [true, false] true if an entry is deleted
-      def delete(name, options = nil)
-        options ||= {}
-        name = expanded_key name
-
-        instrument(:delete, name) do
-          delete_entry(name, options)
+      # Note that the counter represented by non-negative number on the server, and it will not
+      # cycle to maximum integer when decrementing zero.
+      def decrement(name, amount = 1, expires_in: nil, initial: nil, **_options)
+        instrument :decrement, name, amount: amount do
+          failsafe :decrement do
+            key = normalize_key(name, options)
+            res = collection.binary.decrement(
+              key, ::Couchbase::Options::Decrement(delta: amount, expiry: expires_in, initial: initial)
+            )
+            @last_mutation_token = res.mutation_token
+            res.content
+          end
         end
       end
 
-      # Increment an integer value in the cache.
-      #
-      # @since 1.2.0.dp5
-      #
-      # @param [String] name name for the key
-      # @param [Fixnum] amount (1) the delta value
-      # @param [Hash] options
-      # @option options [Fixnum] :expires_in the expiration time on the
-      #   cache in seconds. Values larger than 30*24*60*60 seconds (30 days)
-      #   are interpreted as absolute times (from the epoch).
-      # @option options [Fixnum] :initial (1) this option allows to initialize
-      #   the value if the key is missing in the cache
+      # Clears the entire cache. Be careful with this method since it could
+      # affect other processes if shared cache is being used.
       #
-      # @return [Fixnum] new value
-      def increment(name, amount = 1, options = nil)
-        options ||= {}
-        name = expanded_key name
-
-        if ttl = options.delete(:expires_in)
-          options[:ttl] ||= ttl
-        end
-        options[:create] = true
-        instrument(:increment, name, options) do |payload|
-          payload[:amount] = amount if payload
-          @data.incr(name, amount, options)
+      # When +use_flush+ option set to +true+ it will flush the bucket. Otherwise, it uses N1QL query
+      # and relies on default index.
+      def clear(use_flush: false, **_options)
+        failsafe(:clear) do
+          if use_flush
+            cluster.buckets.flush_bucket(@couchbase_options[:bucket_name])
+          else
+            operation_options = ::Couchbase::Options::Query.new
+            operation_options.consistent_with(::Couchbase::MutationState.new(@last_mutation_token)) if @last_mutation_token
+            cluster.query("DELETE FROM #{scope_qualifier}", operation_options)
+          end
         end
-      rescue ::Couchbase::Error::Base => e
-        logger.error("#{e.class}: #{e.message}") if logger
-        raise if @raise_errors
-        false
       end
 
-      # Decrement an integer value in the cache.
-      #
-      # @since 1.2.0.dp5
-      #
-      # @param [String] name name for the key
-      # @param [Fixnum] amount (1) the delta value
-      # @param [Hash] options
-      # @option options [Fixnum] :expires_in the expiration time on the
-      #   cache in seconds. Values larger than 30*24*60*60 seconds (30 days)
-      #   are interpreted as absolute times (from the epoch).
-      # @option options [Fixnum] :initial this option allows to initialize
-      #   the value if the key is missing in the cache
-      #
-      # @return [Fixnum] new value
-      def decrement(name, amount = 1, options = nil)
-        options ||= {}
-        name = expanded_key name
+      private
 
-        if ttl = options.delete(:expires_in)
-          options[:ttl] ||= ttl
-        end
-        options[:create] = true
-        instrument(:decrement, name, options) do |payload|
-          payload[:amount] = amount if payload
-          @data.decr(name, amount, options)
+      def deserialize_entry(payload, raw: false, **)
+        if payload && raw
+          Entry.new(payload, compress: false)
+        else
+          super(payload)
         end
-      rescue ::Couchbase::Error::Base => e
-        logger.error("#{e.class}: #{e.message}") if logger
-        raise if @raise_errors
-        false
-      end
-
-      # Get the statistics from the memcached servers.
-      #
-      # @since 1.2.0.dp5
-      #
-      # @return [Hash]
-      def stats(*arg)
-        @data.stats(*arg)
       end
 
-      protected
-
-      # Read an entry from the cache.
-      def read_entry(key, options) # :nodoc:
-        @data.get(key, options)
-      rescue ::Couchbase::Error::Base => e
-        logger.error("#{e.class}: #{e.message}") if logger
-        raise if @raise_errors
-        nil
+      def serialize_entry(entry, raw: false, **options)
+        if raw
+          entry.value.to_s
+        else
+          super(entry, **options)
+        end
       end
 
-      # Write an entry to the cache.
-      def write_entry(key, value, options) # :nodoc:
-        method = if options[:unless_exists] || options[:unless_exist]
-                   :add
-                 else
-                   :set
-                 end
-        if ttl = options.delete(:expires_in)
-          options[:ttl] ||= ttl
+      def serialize_entries(entries, **options)
+        entries.transform_values do |entry|
+          serialize_entry(entry, **options)
         end
-        @data.send(method, key, value, options)
-      rescue ::Couchbase::Error::Base => e
-        logger.error("#{e.class}: #{e.message}") if logger
-        raise if @raise_errors
-        false
       end
 
-      # Delete an entry from the cache.
-      def delete_entry(key, options) # :nodoc:
-        @data.delete(key, options)
-      rescue ::Couchbase::Error::Base => e
-        logger.error("#{e.class}: #{e.message}") if logger
-        raise if @raise_errors
-        false
+      # Reads an entry from the cache
+      def read_entry(key, **options)
+        deserialize_entry(read_serialized_entry(key, **options), **options)
       end
 
-      private
-
-      # Expand key to be a consistent string value. Invoke +cache_key+ if
-      # object responds to +cache_key+. Otherwise, to_param method will be
-      # called. If the key is a Hash, then keys will be sorted alphabetically.
-      def expanded_key(key) # :nodoc:
-        return validate_key(key.cache_key.to_s) if key.respond_to?(:cache_key)
+      def read_serialized_entry(key, **)
+        failsafe(:read_entry, returning: nil) do
+          res = collection.get(key, ::Couchbase::Options::Get(transcoder: nil))
+          res.content
+        end
+      end
 
-        case key
-        when Array
-          if key.size > 1
-            key = key.collect{|element| expanded_key(element)}
-          else
-            key = key.first
+      # Reads multiple entries from the cache implementation. Subclasses MAY
+      # implement this method.
+      def read_multi_entries(names, **options)
+        return {} if names.empty?
+
+        keys = names.map { |name| normalize_key(name, options) }
+        return_value = {}
+        failsafe(:read_multi_entries, returning: return_value) do
+          results = collection.get_multi(keys, ::Couchbase::Options::GetMulti(transcoder: nil))
+          results.each_with_index do |result, index|
+            next unless result.success?
+
+            entry = deserialize_entry(result.content, raw: options[:raw])
+            unless entry.nil? || entry.expired? || entry.mismatched?(normalize_version(names[index], options))
+              return_value[names[index]] = entry.value
+            end
           end
-        when Hash
-          key = key.sort_by { |k,_| k.to_s }.collect{|k,v| "#{k}=#{v}"}
+          return_value
         end
+      end
 
-        validate_key(key.respond_to?(:to_param) ? key.to_param : key)
+      # Writes an entry to the cache
+      def write_entry(key, entry, raw: false, **options)
+        write_serialized_entry(key, serialize_entry(entry, raw: raw, **options), raw: raw, **options)
       end
 
-      def validate_key(key)
-        if key_with_prefix(key).length > 250
-          key = "#{key[0, max_length_before_prefix]}:md5:#{Digest::MD5.hexdigest(key)}"
+      def write_serialized_entry(key, payload, expires_in: nil, race_condition_ttl: nil, raw: false, **)
+        if race_condition_ttl && expires_in && expires_in.positive? && !raw
+          # Add few minutes to expiry in the future to support race condition TTLs on read
+          expires_in += 5.minutes
+        end
+        failsafe(:write_entry, returning: false) do
+          res = collection.upsert(key, payload, ::Couchbase::Options::Upsert(transcoder: nil, expiry: expires_in))
+          @last_mutation_token = res.mutation_token
+          true
         end
-        return key
       end
 
-      def key_with_prefix(key)
-        (ns = @key_prefix) ? "#{ns}#{key}" : key
-      end
+      def write_multi_entries(entries, **options)
+        return 0 if entries.empty?
 
-      def max_length_before_prefix
-        @max_length_before_prefix ||= 212 - (@key_prefix || '').size
-      end
+        return super if local_cache
 
-      module Threadsafe
-        def self.extended(obj)
-          obj.init_threadsafe
+        expires_in = options[:expires_in]
+        if options[:race_condition_ttl] && expires_in && expires_in.positive?
+          # Add few minutes to expiry in the future to support race condition TTLs on read
+          expires_in += 5.minutes
         end
+        operation_options = ::Couchbase::Options::UpsertMulti(transcoder: nil, expiry: expires_in)
+        failsafe(:write_multi_entries, returning: nil) do
+          successful = collection.upsert_multi(serialize_entries(entries, **options), operation_options).select(&:success?)
+          return 0 if successful.empty?
 
-        def get(*)
-          @lock.synchronize do
-            super
-          end
+          @last_mutation_token = successful.max_by { |r| r.mutation_token.sequence_number }
+          successful.count
         end
+      end
 
-        def send(*)
-          @lock.synchronize do
-            super
-          end
+      # Deletes an entry from the cache implementation. Subclasses must
+      # implement this method.
+      def delete_entry(key, **_options)
+        failsafe(:delete_entry, returning: false) do
+          res = collection.remove(key)
+          @last_mutation_token = res.mutation_token
+          true
         end
+      end
 
-        def delete(*)
-          @lock.synchronize do
-            super
-          end
-        end
+      # Deletes multiple entries in the cache. Returns the number of entries deleted.
+      def delete_multi_entries(entries, **_options)
+        return if entries.empty?
 
-        def incr(*)
-          @lock.synchronize do
-            super
-          end
+        failsafe(:delete_multi_entries, returning: nil) do
+          successful = collection.remove_multi(entries).select(&:success?)
+          return 0 if successful.empty?
+
+          @last_mutation_token = successful.max_by { |r| r.mutation_token.sequence_number }
+          successful.count
         end
+      end
 
-        def decr(*)
-          @lock.synchronize do
-            super
-          end
+      def failsafe(method, returning: nil)
+        yield
+      rescue ::Couchbase::Error::CouchbaseError => e
+        ActiveSupport.error_reporter&.report(e, handled: true, severity: :warning)
+        @error_handler&.call(method: method, exception: e, returning: returning)
+        returning
+      end
+
+      # Truncate keys that exceed 250 characters
+      def normalize_key(key, options)
+        truncate_key super&.b
+      end
+
+      def truncate_key(key)
+        if key && key.bytesize > MAX_KEY_BYTESIZE
+          suffix = ":sha2:#{::Digest::SHA2.hexdigest(key)}"
+          truncate_at = MAX_KEY_BYTESIZE - suffix.bytesize
+          "#{key.byteslice(0, truncate_at)}#{suffix}"
+        else
+          key
         end
+      end
 
-        def stats(*)
-          @lock.synchronize do
-            super
-          end
+      # Connects to the Couchbase cluster
+      def build_cluster
+        ::Couchbase::Cluster.connect(
+          @couchbase_options[:connection_string],
+          ::Couchbase::Options::Cluster(authenticator: ::Couchbase::PasswordAuthenticator.new(
+            @couchbase_options[:username], @couchbase_options[:password]
+          ))
+        )
+      end
+
+      # Connects to the Couchbase cluster, opens specified bucket and returns collection object.
+      def build_collection
+        bucket = cluster.bucket(@couchbase_options[:bucket])
+        if @couchbase_options[:scope] && @couchbase_options[:collection]
+          bucket.scope(@couchbase_options[:scope]).collection(@couchbase_options[:collection])
+        else
+          bucket.default_collection
         end
+      end
 
-        def init_threadsafe
-          @lock = Monitor.new
+      def scope_qualifier
+        if @couchbase_options[:scope] && @couchbase_options[:collection]
+          "`#{@couchbase_options[:bucket]}`.#{@couchbase_options[:scope]}.#{@couchbase_options[:collection]}"
+        else
+          "`#{@couchbase_options[:bucket]}`"
         end
       end
     end