identity_cache 1.1.0 → 1.2.0

data/lib/identity_cache/cache_fetcher.rb

@@ -1,8 +1,53 @@
 # frozen_string_literal: true
+
+require "securerandom"
+
 module IdentityCache
   class CacheFetcher
     attr_accessor :cache_backend
 
+    EMPTY_HASH = {}.freeze
+
+    class FillLock
+      FILL_LOCKED = :fill_locked
+      FAILED_CLIENT_ID = "fill_failed"
+
+      class << self
+        def from_cache(marker, client_id, data_version)
+          raise ArgumentError unless marker == FILL_LOCKED
+
+          new(client_id: client_id, data_version: data_version)
+        end
+
+        def cache_value?(cache_value)
+          cache_value.is_a?(Array) && cache_value.length == 3 && cache_value.first == FILL_LOCKED
+        end
+      end
+
+      attr_reader :client_id, :data_version
+
+      def initialize(client_id:, data_version:)
+        @client_id = client_id
+        @data_version = data_version
+      end
+
+      def cache_value
+        [FILL_LOCKED, client_id, data_version]
+      end
+
+      def mark_failed
+        @client_id = FAILED_CLIENT_ID
+      end
+
+      def fill_failed?
+        @client_id == FAILED_CLIENT_ID
+      end
+
+      def ==(other)
+        self.class == other.class && client_id == other.client_id && data_version == other.data_version
+      end
+    end
+
     def initialize(cache_backend)
       @cache_backend = cache_backend
     end
@@ -25,27 +70,204 @@ module IdentityCache
       results
     end
 
-    def fetch(key)
-      result = nil
-      yielded = false
-      @cache_backend.cas(key) do |value|
-        yielded = true
-        unless IdentityCache::DELETED == value
-          result = value
-          break
+    def fetch(key, fill_lock_duration: nil, lock_wait_tries: 2, &block)
+      if fill_lock_duration && IdentityCache.should_fill_cache?
+        fetch_with_fill_lock(key, fill_lock_duration, lock_wait_tries, &block)
+      else
+        fetch_without_fill_lock(key, &block)
+      end
+    end
+
+    private
+
+    def fetch_without_fill_lock(key)
+      data = nil
+      upsert(key) do |value|
+        value = nil if value == IdentityCache::DELETED || FillLock.cache_value?(value)
+        unless value.nil?
+          return value
         end
-        result = yield
+
+        data = yield
         break unless IdentityCache.should_fill_cache?
-        result
+
+        data
+      end
+      data
+    end
+
+    def fetch_with_fill_lock(key, fill_lock_duration, lock_wait_tries, &block)
+      raise ArgumentError, "fill_lock_duration must be greater than 0.0" unless fill_lock_duration > 0.0
+      raise ArgumentError, "lock_wait_tries must be greater than 0" unless lock_wait_tries > 0
+
+      lock = nil
+      using_fallback_key = false
+      expiration_options = EMPTY_HASH
+      (lock_wait_tries + 2).times do # +2 is for first attempt and retry with fallback key
+        result = fetch_or_take_lock(key, old_lock: lock, **expiration_options)
+        case result
+        when FillLock
+          lock = result
+          if lock.client_id == client_id # have lock
+            data = begin
+              yield
+            rescue
+              mark_fill_failure_on_lock(key, expiration_options)
+              raise
+            end
+
+            if !fill_with_lock(key, data, lock, expiration_options) && !using_fallback_key
+              # fallback to storing data in the fallback key so it is available to clients waiting on the lock
+              expiration_options = fallback_key_expiration_options(fill_lock_duration)
+              @cache_backend.write(lock_fill_fallback_key(key, lock), data, expiration_options)
+            end
+            return data
+          else
+            raise LockWaitTimeout if lock_wait_tries <= 0
+
+            lock_wait_tries -= 1
+
+            # If fill failed in the other client, then it might be failing fast
+            # so avoid waiting the typical amount of time for a lock wait. The
+            # semian gem can be used to handle failing fast when the database is slow.
+            if lock.fill_failed?
+              return fetch_without_fill_lock(key, &block)
+            end
+
+            # lock wait
+            sleep(fill_lock_duration)
+            # loop around to retry fetch_or_take_lock
+          end
+        when IdentityCache::DELETED # interrupted by cache invalidation
+          if using_fallback_key
+            raise "unexpected cache invalidation of versioned fallback key"
+          elsif lock
+            # Cache invalidated during lock wait, use a versioned fallback key
+            # to avoid further cache invalidation interruptions.
+            using_fallback_key = true
+            key = lock_fill_fallback_key(key, lock)
+            expiration_options = fallback_key_expiration_options(fill_lock_duration)
+            # loop around to retry with fallback key
+          else
+            # Cache invalidation prevented lock from being taken or read, so we don't
+            # have a data version to use to build a shared fallback key. In the future
+            # we could add the data version to the cache invalidation value so a fallback
+            # key could be used here. For now, we assume that a cache invalidation occuring
+            # just after the cache wasn't filled is more likely a sign of a key that is
+            # written more than read (which this cache isn't a good fit for), rather than
+            # a thundering herd or reads.
+            return yield
+          end
+        when nil # Errors talking to memcached
+          return yield
+        else # hit
+          return result
+        end
+      end
+      raise "unexpected number of loop iterations"
+    end
+
+    def mark_fill_failure_on_lock(key, expiration_options)
+      @cache_backend.cas(key, expiration_options) do |value|
+        break unless FillLock.cache_value?(value)
+
+        lock = FillLock.from_cache(*value)
+        break if lock.client_id != client_id
+
+        lock.mark_failed
+        lock.cache_value
+      end
+    end
+
+    def upsert(key, expiration_options = EMPTY_HASH)
+      yielded = false
+      upserted = @cache_backend.cas(key, expiration_options) do |value|
+        yielded = true
+        yield value
       end
       unless yielded
-        result = yield
-        add(key, result)
+        data = yield nil
+        upserted = add(key, data, expiration_options)
       end
-      result
+      upserted
     end
 
-    private
+    def fetch_or_take_lock(key, old_lock:, **expiration_options)
+      new_lock = nil
+      upserted = upsert(key, expiration_options) do |value|
+        if value.nil? || value == IdentityCache::DELETED
+          if old_lock # cache invalidated
+            return value
+          else
+            new_lock = FillLock.new(client_id: client_id, data_version: SecureRandom.uuid)
+          end
+        elsif FillLock.cache_value?(value)
+          fetched_lock = FillLock.from_cache(*value)
+          if old_lock == fetched_lock
+            # preserve data version since there hasn't been any cache invalidations
+            new_lock = FillLock.new(client_id: client_id, data_version: old_lock.data_version)
+          elsif old_lock && fetched_lock.data_version != old_lock.data_version
+            # Cache was invalidated, then another lock was taken during a lock wait.
+            # Treat it as any other cache invalidation, where the caller will switch
+            # to the fallback key.
+            return IdentityCache::DELETED
+          else
+            return fetched_lock
+          end
+        else # hit
+          return value
+        end
+        new_lock.cache_value # take lock
+      end
+
+      return new_lock if upserted
+
+      value = @cache_backend.read(key)
+      if FillLock.cache_value?(value)
+        FillLock.from_cache(*value)
+      else
+        value
+      end
+    end
+
+    def fill_with_lock(key, data, my_lock, expiration_options)
+      upserted = upsert(key, expiration_options) do |value|
+        return false if value.nil? || value == IdentityCache::DELETED
+        return true unless FillLock.cache_value?(value) # already filled
+
+        current_lock = FillLock.from_cache(*value)
+        if current_lock.data_version != my_lock.data_version
+          return false # invalidated then relocked
+        end
+
+        data
+      end
+
+      upserted
+    end
+
+    def lock_fill_fallback_key(key, lock)
+      "lock_fill:#{lock.data_version}:#{key}"
+    end
+
+    def fallback_key_expiration_options(fill_lock_duration)
+      # Override the default TTL for the fallback key lock since it won't be used for very long.
+      expires_in = fill_lock_duration * 2
+
+      # memcached uses integer number of seconds for TTL so round up to avoid having
+      # the cache store round down with `to_i`
+      expires_in = expires_in.ceil
+
+      # memcached TTL only gets part of the first second (https://github.com/memcached/memcached/issues/307),
+      # so increase TTL by 1 to compensate
+      expires_in += 1
+
+      { expires_in: expires_in }
+    end
+
+    def client_id
+      @client_id ||= SecureRandom.uuid
+    end
 
     def cas_multi(keys)
       result = nil
@@ -70,6 +292,7 @@ module IdentityCache
 
         break if updates.empty?
         break unless IdentityCache.should_fill_cache?
+
         updates
       end
       result
@@ -81,8 +304,10 @@ module IdentityCache
       result.each { |k, v| add(k, v) }
     end
 
-    def add(key, value)
-      @cache_backend.write(key, value, unless_exist: true) if IdentityCache.should_fill_cache?
+    def add(key, value, expiration_options = EMPTY_HASH)
+      return false unless IdentityCache.should_fill_cache?
+
+      @cache_backend.write(key, value, { unless_exist: true, **expiration_options })
     end
   end
 end

data/lib/identity_cache/cache_hash.rb

@@ -1,9 +1,10 @@
 # frozen_string_literal: true
+
 # Use CityHash for fast hashing if it is available; use Digest::MD5 otherwise
 begin
-  require 'cityhash'
+  require "cityhash"
 rescue LoadError
-  unless RUBY_PLATFORM == 'java'
+  unless RUBY_PLATFORM == "java"
     warn(<<-NOTICE)
       ** Notice: CityHash was not loaded. **
 
@@ -15,20 +16,20 @@ rescue LoadError
     NOTICE
   end
 
-  require 'digest/md5'
+  require "digest/md5"
 end
 
 module IdentityCache
   module CacheHash
     if defined?(CityHash)
 
-      def memcache_hash(key) #:nodoc:
+      def memcache_hash(key) # :nodoc:
         CityHash.hash64(key)
       end
     else
 
-      def memcache_hash(key) #:nodoc:
-        a = Digest::MD5.digest(key).unpack('LL')
+      def memcache_hash(key) # :nodoc:
+        a = Digest::MD5.digest(key).unpack("LL")
         (a[0] << 32) | a[1]
       end
     end

data/lib/identity_cache/cache_invalidation.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module CacheInvalidation
     CACHE_KEY_NAMES = [:ids_variable_name, :id_variable_name, :records_variable_name]

data/lib/identity_cache/cache_key_generation.rb

@@ -1,33 +1,36 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module CacheKeyGeneration
     extend ActiveSupport::Concern
     DEFAULT_NAMESPACE = "IDC:#{CACHE_VERSION}:"
 
-    def self.schema_to_string(columns)
-      columns.sort_by(&:name).map { |c| "#{c.name}:#{c.type}" }.join(',')
-    end
+    class << self
+      def schema_to_string(columns)
+        columns.sort_by(&:name).map { |c| "#{c.name}:#{c.type}" }.join(",")
+      end
 
-    def self.denormalized_schema_string(klass)
-      schema_to_string(klass.columns).tap do |schema_string|
-        klass.all_cached_associations.sort.each do |name, association|
-          klass.send(:check_association_scope, name)
-          association.validate if association.embedded?
-          case association
-          when Cached::Recursive::Association
-            schema_string << ",#{name}:(#{denormalized_schema_hash(association.reflection.klass)})"
-          when Cached::Reference::HasMany
-            schema_string << ",#{name}:ids"
-          when Cached::Reference::HasOne
-            schema_string << ",#{name}:id"
+      def denormalized_schema_string(klass)
+        schema_to_string(klass.columns).tap do |schema_string|
+          klass.all_cached_associations.sort.each do |name, association|
+            klass.send(:check_association_scope, name)
+            association.validate if association.embedded?
+            case association
+            when Cached::Recursive::Association
+              schema_string << ",#{name}:(#{denormalized_schema_hash(association.reflection.klass)})"
+            when Cached::Reference::HasMany
+              schema_string << ",#{name}:ids"
+            when Cached::Reference::HasOne
+              schema_string << ",#{name}:id"
+            end
           end
         end
       end
-    end
 
-    def self.denormalized_schema_hash(klass)
-      schema_string = denormalized_schema_string(klass)
-      IdentityCache.memcache_hash(schema_string)
+      def denormalized_schema_hash(klass)
+        schema_string = denormalized_schema_string(klass)
+        IdentityCache.memcache_hash(schema_string)
+      end
     end
 
     module ClassMethods

data/lib/identity_cache/cache_key_loader.rb

@@ -25,12 +25,12 @@ module IdentityCache
       # @param cache_fetcher [_CacheFetcher]
       # @param db_key Reference to what to load from the database.
       # @return The database value corresponding to the database key.
-      def load(cache_fetcher, db_key)
+      def load(cache_fetcher, db_key, cache_fetcher_options = {})
         cache_key = cache_fetcher.cache_key(db_key)
 
         db_value = nil
 
-        cache_value = IdentityCache.fetch(cache_key) do
+        cache_value = IdentityCache.fetch(cache_key, cache_fetcher_options) do
           db_value = cache_fetcher.load_one_from_db(db_key)
           cache_fetcher.cache_encode(db_value)
         end

data/lib/identity_cache/cached/association.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
     class Association # :nodoc:
@@ -50,10 +51,7 @@ module IdentityCache
       end
 
       def inverse_name
-        @inverse_name ||= begin
-          reflection.inverse_of&.name ||
-          reflection.active_record.name.underscore
-        end
+        @inverse_name ||= reflection.inverse_of&.name || reflection.active_record.name.underscore
       end
 
       def validate

data/lib/identity_cache/cached/attribute.rb

@@ -87,11 +87,11 @@ module IdentityCache
 
       def cache_key_prefix
         @cache_key_prefix ||= begin
-          unique_indicator = unique ? '' : 's'
+          unique_indicator = unique ? "" : "s"
           "attr#{unique_indicator}" \
             ":#{model.base_class.name}" \
             ":#{attribute}" \
-            ":#{key_fields.join('/')}:"
+            ":#{key_fields.join("/")}:"
         end
       end
 
@@ -116,7 +116,7 @@ module IdentityCache
       end
 
       def fetch_method_suffix
-        "#{alias_name}_by_#{key_fields.join('_and_')}"
+        "#{alias_name}_by_#{key_fields.join("_and_")}"
       end
     end
   end

data/lib/identity_cache/cached/attribute_by_multi.rb

@@ -24,7 +24,7 @@ module IdentityCache
       end
 
       def unhashed_values_cache_key_string(key_values)
-        key_values.map { |v| v.try!(:to_s).inspect }.join('/')
+        key_values.map { |v| v.try!(:to_s).inspect }.join("/")
       end
 
       def load_from_db_where_conditions(key_values)

data/lib/identity_cache/cached/belongs_to.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
     class BelongsTo < Association # :nodoc:
@@ -42,6 +43,7 @@ module IdentityCache
           records.each do |owner_record|
             associated_id = owner_record.send(reflection.foreign_key)
             next unless associated_id && !owner_record.instance_variable_defined?(records_variable_name)
+
             foreign_type_fetcher = Object.const_get(
               owner_record.send(reflection.foreign_type)
             ).cached_model.cached_primary_index
@@ -55,6 +57,7 @@ module IdentityCache
             records.each do |owner_record|
               associated_id = owner_record.send(reflection.foreign_key)
               next unless associated_id && !owner_record.instance_variable_defined?(records_variable_name)
+
               foreign_type_fetcher = Object.const_get(
                 owner_record.send(reflection.foreign_type)
               ).cached_model.cached_primary_index

data/lib/identity_cache/cached/embedded_fetching.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
     module EmbeddedFetching
@@ -22,6 +23,7 @@ module IdentityCache
           cached_associations.each_value do |cached_association|
             records.each do |record|
               next unless (cached_record = cached_records_by_id[record.id])
+
               cached_value = cached_association.read(cached_record)
               cached_association.write(record, cached_value)
             end

data/lib/identity_cache/cached/primary_index.rb

@@ -9,11 +9,12 @@ module IdentityCache
         @model = model
       end
 
-      def fetch(id)
+      def fetch(id, cache_fetcher_options)
         id = cast_id(id)
         return unless id
+
         record = if model.should_use_cache?
-          object = CacheKeyLoader.load(self, id)
+          object = CacheKeyLoader.load(self, id, cache_fetcher_options)
           if object && object.id != id
             IdentityCache.logger.error(
               <<~MSG.squish

data/lib/identity_cache/cached/recursive/association.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
     module Recursive
@@ -77,6 +78,7 @@ module IdentityCache
 
         def set_inverse(record, association_target)
           return if association_target.nil?
+
           associated_class = reflection.klass
           inverse_cached_association = associated_class.cached_belongs_tos[inverse_name]
           return unless inverse_cached_association

data/lib/identity_cache/cached/recursive/has_many.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
     module Recursive

data/lib/identity_cache/cached/recursive/has_one.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
     module Recursive

data/lib/identity_cache/cached/reference/association.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
     module Reference

data/lib/identity_cache/cached/reference/has_many.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
     module Reference

data/lib/identity_cache/cached/reference/has_one.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
     module Reference

data/lib/identity_cache/cached.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Cached
   end

data/lib/identity_cache/configuration_dsl.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module ConfigurationDSL
     extend ActiveSupport::Concern

data/lib/identity_cache/encoder.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   module Encoder
     DEHYDRATE_EVENT = "dehydration.identity_cache"
@@ -66,7 +67,7 @@ module IdentityCache
         end
       end
 
-      def record_from_coder(coder, klass) #:nodoc:
+      def record_from_coder(coder, klass) # :nodoc:
         record = klass.instantiate(coder[:attributes].dup)
 
         if coder.key?(:associations)

data/lib/identity_cache/expiry_hook.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   class ExpiryHook
     def initialize(cached_association)

data/lib/identity_cache/fallback_fetcher.rb

@@ -1,4 +1,5 @@
 # frozen_string_literal: true
+
 module IdentityCache
   class FallbackFetcher
     attr_accessor :cache_backend
@@ -32,7 +33,11 @@ module IdentityCache
       results
     end
 
-    def fetch(key)
+    def fetch(key, **cache_fetcher_options)
+      unless cache_fetcher_options.empty?
+        raise ArgumentError, "unsupported cache_fetcher options: #{cache_fetcher_options.keys.join(", ")}"
+      end
+
       result = @cache_backend.read(key)
       if result.nil?
         result = yield

data/lib/identity_cache/mem_cache_store_cas.rb

@@ -1,5 +1,6 @@
 # frozen_string_literal: true
-require 'dalli/cas/client'
+
+require "dalli/cas/client" unless Dalli::VERSION > "3"
 
 module IdentityCache
   module MemCacheStoreCAS
@@ -11,7 +12,7 @@ module IdentityCache
         instrument(:cas, key, options) do
           @data.with do |connection|
             connection.cas(key, options[:expires_in].to_i, options) do |raw_value|
-              entry = deserialize_entry(raw_value)
+              entry = deserialize_entry(raw_value, raw: options[:raw])
               value = yield entry.value
               entry = ActiveSupport::Cache::Entry.new(value, **options)
               options[:raw] ? entry.value.to_s : entry
@@ -29,11 +30,11 @@ module IdentityCache
       keys = keys_to_names.keys
       rescue_error_with(false) do
         instrument(:cas_multi, keys, options) do
-          raw_values = @data.get_multi_cas(keys)
+          raw_values = @data.with { |c| c.get_multi_cas(keys) }
 
           values = {}
           raw_values.each do |key, raw_value|
-            entry = deserialize_entry(raw_value.first)
+            entry = deserialize_entry(raw_value.first, raw: options[:raw])
             values[keys_to_names[key]] = entry.value unless entry.expired?
           end
 
@@ -44,10 +45,19 @@ module IdentityCache
             cas_id = raw_values[key].last
             entry = ActiveSupport::Cache::Entry.new(value, **options)
             payload = options[:raw] ? entry.value.to_s : entry
-            @data.replace_cas(key, payload, cas_id, options[:expires_in].to_i, options)
+            @data.with { |c| c.replace_cas(key, payload, cas_id, options[:expires_in].to_i, options) }
           end
         end
       end
     end
+
+    if ActiveSupport::Cache::MemCacheStore.instance_method(:deserialize_entry).arity == 1
+
+      private
+
+      def deserialize_entry(payload, raw: nil)
+        super(payload)
+      end
+    end
   end
 end