support_table_cache 1.1.5 → 1.1.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 9fe5a9190c32271b431faed20e0b6ddbeb195cd05c927cae94c03b5c7d20bc8a
-  data.tar.gz: 8f8bc59c1a0eb6240712e50fb34da28f45d071e1c6b59e28d647d8bcf7e17896
+  metadata.gz: 0e6656d6580218249c30dbfb1f21213b1f0cd17c43c7ec81bca00a376edd1a38
+  data.tar.gz: 63ead57c3891ca076810d70cd64b81073bed609468ac6b4e865d47cd2ee61031
 SHA512:
-  metadata.gz: c833468a94fed3f16efd45022c56cbf19c755d6f0e2f48a2d93b8b92c2d946bd46f246170a623f2edeade892aa017851d581794fc7505c4efd5c5bce3fdf29b9
-  data.tar.gz: d4307c2d653184fe890e8aa8af0c548ef340d817141fddcb69e8a083ffcd235fa7d0d124b98e6ece0dd99e5a8fc549db1a8a986acf571aada17cb6f0619c67e1
+  metadata.gz: 6dfa8b6ff0474608194dc1694ea452cdc51aaf6b05d528d6c86dcee927e08299d7d95bcacf3b7bf1f6a9e39971a0181b0290f4d3a72f5750d7f314ddf5354ef9
+  data.tar.gz: 94b88ef70a916052633d1c7e61d047fc70b1de9c2f111c247747a9e99ddeda47295c96f3214e264fd5975b09d8fb75170a941ee2f6dba27bdcda41f587c86fbf

data/CHANGELOG.md

@@ -4,6 +4,26 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 1.1.6
+
+### Fixed
+
+- Queries on relations with conditions that cannot be represented in the cache key (SQL string conditions, ranges, `not`, `or`, joins, `group`, `having`, `from`, `offset`, locking, or non-hash `find_by` arguments) now bypass the cache instead of silently ignoring those conditions and returning or caching the wrong record.
+- `create_with` values are no longer included in cache keys, so queries using `create_with` can now be cached correctly.
+- Queries inside an open transaction now bypass the cache so that uncommitted data can never be cached. Previously a rolled back transaction could permanently poison the cache with data that was never committed. Transactions created with `joinable: false` (such as Rails transactional test fixtures) still use the cache.
+- Cache invalidation now runs even when caching is disabled. Previously records changed inside a `disable` block (or while caching was disabled globally) left stale entries behind for when caching was re-enabled.
+- Cache key values are now cast through the attribute type, so equivalent values (e.g. `:one` and `"one"`, or `"5"` and `5`) produce the same cache key. Previously such entries could be written under keys that the invalidation callbacks could never delete. This also fixes cache keys for `false` attribute values, which were previously indistinguishable from `nil`.
+- `load_cache` no longer raises an error when caching is disabled and now honors `where` conditions on `cache_by` configurations instead of caching records that do not match them. It also refreshes existing cache entries instead of skipping them.
+- A `cache_by` configuration whose `where` clause does not match a query no longer prevents later configurations from matching, and no longer mutates the query attributes while matching.
+- Calling `cache_by` in a subclass no longer mutates the superclass's cache configuration.
+- Models that include `SupportTableCache` without calling `cache_by` no longer raise an error on `find_by`.
+- Calling `cache_belongs_to` more than once for the same association no longer causes infinite recursion when reading the association.
+- `SupportTableCache::MemoryCache` now synchronizes all access to the underlying hash (previously reads, deletes, and clears were unsynchronized), purges expired entries, and no longer serializes values twice on a cache miss. A `fetch` that races with a concurrent `delete` or `clear` no longer stores its stale value back in the cache.
+- The `where` clause on a `cache_by` configuration is now matched against query attributes using values cast through the attribute type, so equivalent values (e.g. `1` and `"1"`) match the same way they do when building cache keys.
+- A `find_by` that specifies a different value for an attribute than the relation it is chained onto (i.e. `where(name: "Two").find_by(name: "One")`) now bypasses the cache. Previously the `find_by` value replaced the relation's value in the cache key so a cached record excluded by the relation could be returned.
+- `fetch_by` and `fetch_by!` now raise an `ArgumentError` if a query cannot be matched to a cache key because it does not satisfy the `where` condition on a `cache_by` configuration or because it conflicts with the relation it is chained onto. Previously these queries silently fell back to the database, which defeats the purpose of the safety check. Queries on a model with a default scope matching a `cache_by` `where` condition no longer raise an error.
+- `SupportTableCache::FiberLocals` now stores state in the fiber's native local storage so that state cannot leak from fibers that are garbage collected while suspended inside a block.
+
 ## 1.1.5
 
 ### Fixed

data/README.md

@@ -89,6 +89,12 @@ You can also set a cache per class. For instance, you can set an in-memory cache
 
 Note that in-memory caches exist separately within each process and will not be cleared when records are changed in the database. The only way to refresh elements in an in-memory cache is to restart the process or set the `support_table_cache_ttl` value so that the entries will expire.
 
+It is a good idea to always set `support_table_cache_ttl`, even when using a shared cache store. Cache invalidation happens when a record's changes are committed, but a process reading the old row at the same moment can still write the stale value back to the cache just after it was invalidated. A TTL puts an upper bound on how long such a stale entry can survive.
+
+The global cache and disabled settings (`SupportTableCache.cache=` and `SupportTableCache.disable` without a block) are intended to be set during application initialization and are not synchronized for concurrent modification at runtime.
+
+Queries made inside an open database transaction always bypass the cache. This prevents uncommitted data from being cached (which would never be cleared if the transaction were rolled back). Transactions created with `joinable: false`, such as the ones wrapping Rails transactional test fixtures, do not bypass the cache.
+
 ### Disabling Caching
 
 You can disable the cache within a block either globally or only for a specific class. If the cache is disabled, then all queries will pass through to the database.
@@ -108,6 +114,10 @@ SupportTableCache.enable do
 end
 ```
 
+Cache entries are still cleared when records are changed while caching is disabled, so re-enabling the cache will not expose stale data.
+
+Note that the class-level `disable_cache` and `enable_cache` settings apply only to the class they are called on; they do not apply to subclasses in a single table inheritance hierarchy.
+
 ### Caching Belongs to Associations
 
 You can also cache belongs to associations to cacheable models.

data/VERSION

@@ -1 +1 @@
-1.1.5
+1.1.6

data/lib/support_table_cache/associations.rb

@@ -41,7 +41,9 @@ module SupportTableCache
             key = [reflection.class_name, {reflection.association_primary_key => foreign_key}]
             cache = reflection.klass.send(:current_support_table_cache)
             ttl = reflection.klass.send(:support_table_cache_ttl)
-            if cache
+            # Queries inside a transaction could see uncommitted data that would be invalid
+            # if the transaction is rolled back, so they cannot be cached.
+            if cache && !SupportTableCache.open_transaction?(reflection.klass)
               cache.fetch(key, expires_in: ttl) do
                 #{association_name}_without_cache
               end
@@ -50,7 +52,9 @@ module SupportTableCache
             end
           end
 
-          alias_method :#{association_name}_without_cache, :#{association_name}
+          unless method_defined?(:#{association_name}_without_cache) || private_method_defined?(:#{association_name}_without_cache)
+            alias_method :#{association_name}_without_cache, :#{association_name}
+          end
           alias_method :#{association_name}, :#{association_name}_with_cache
         RUBY
       end

data/lib/support_table_cache/fiber_locals.rb

@@ -1,51 +1,40 @@
 # frozen_string_literal: true
 
 module SupportTableCache
-  # Utility class for managing fiber-local variables. This implementation
-  # does not pollute the global namespace.
+  # Utility class for managing fiber-local variables. All values are stored in a single
+  # hash inside the fiber's native local storage (Thread.current[], which is fiber-local
+  # in Ruby) so the fiber-local namespace is not polluted with individual keys. Because
+  # the state lives on the fiber itself, it is garbage collected along with the fiber
+  # and cannot leak or be picked up by another fiber.
   class FiberLocals
     def initialize
-      @mutex = Mutex.new
-      @locals = {}
+      @locals_key = :"support_table_cache_locals_#{object_id}"
     end
 
     def [](key)
-      fiber_locals = nil
-      @mutex.synchronize do
-        fiber_locals = @locals[Fiber.current.object_id]
-      end
-      return nil if fiber_locals.nil?
-
-      fiber_locals[key]
+      locals = Thread.current[@locals_key]
+      locals[key] if locals
     end
 
     def with(key, value)
-      fiber_id = Fiber.current.object_id
-      fiber_locals = nil
-      previous_value = nil
-      inited_vars = false
-
-      begin
-        @mutex.synchronize do
-          fiber_locals = @locals[fiber_id]
-          if fiber_locals.nil?
-            fiber_locals = {}
-            @locals[fiber_id] = fiber_locals
-            inited_vars = true
-          end
-        end
+      locals = Thread.current[@locals_key]
+      if locals.nil?
+        locals = {}
+        Thread.current[@locals_key] = locals
+      end
 
-        previous_value = fiber_locals[key]
-        fiber_locals[key] = value
+      exists = locals.key?(key)
+      previous_value = locals[key]
+      locals[key] = value
 
+      begin
         yield
       ensure
-        if inited_vars
-          @mutex.synchronize do
-            @locals.delete(fiber_id)
-          end
+        if exists
+          locals[key] = previous_value
         else
-          fiber_locals[key] = previous_value
+          locals.delete(key)
+          Thread.current[@locals_key] = nil if locals.empty?
         end
       end
     end

data/lib/support_table_cache/find_by_override.rb

@@ -8,26 +8,18 @@ module SupportTableCache
       cache = current_support_table_cache
       return super unless cache
 
-      cache_key = nil
-      attributes = ((args.size == 1 && args.first.is_a?(Hash)) ? args.first.stringify_keys : {})
+      # Only queries by simple attribute equality can be matched against cache keys.
+      return super unless args.size == 1 && args.first.is_a?(Hash)
 
-      if respond_to?(:scope_attributes) && scope_attributes.present?
-        attributes = scope_attributes.stringify_keys.merge(attributes)
-      end
+      # If the class has any scope applied (a default scope or a scoping block), defer to
+      # the relation override, which checks whether the scoped query can be cached.
+      return super if all.values.present?
 
-      if attributes.present?
-        support_table_cache_by_attributes.each do |attribute_names, case_sensitive, where|
-          where&.each do |name, value|
-            if attributes.include?(name) && attributes[name] == value
-              attributes.delete(name)
-            else
-              return super
-            end
-          end
-          cache_key = SupportTableCache.cache_key(self, attributes, attribute_names, case_sensitive)
-          break if cache_key
-        end
-      end
+      # Queries inside a transaction could see uncommitted data that would be invalid
+      # if the transaction is rolled back, so they cannot be cached.
+      return super if SupportTableCache.open_transaction?(self)
+
+      cache_key = SupportTableCache.cache_key_for_query(self, args.first.stringify_keys)
 
       if cache_key
         cache.fetch(cache_key, expires_in: support_table_cache_ttl) { super }
@@ -42,9 +34,13 @@ module SupportTableCache
     # @return [ActiveRecord::Base, nil] The found record or nil if not found.
     # @raise [ArgumentError] if the query cannot use the cache.
     def fetch_by(attributes)
-      find_by_attribute_names = support_table_find_by_attribute_names(attributes)
-      unless support_table_cache_by_attributes.any? { |attribute_names, _ci, _where| attribute_names == find_by_attribute_names }
-        raise ArgumentError.new("#{name} does not cache queries by #{find_by_attribute_names.to_sentence}")
+      attributes = (attributes || {}).stringify_keys
+      query_attributes = support_table_query_attributes(attributes)
+      unless SupportTableCache.cacheable_query?(self, query_attributes)
+        raise ArgumentError.new("#{name} does not cache queries by #{(query_attributes || attributes).keys.sort.to_sentence}")
+      end
+      unless all.send(:support_table_cacheable_scope?)
+        raise ArgumentError.new("#{name} cannot use the support table cache on an uncacheable scope")
       end
       find_by(attributes)
     end
@@ -65,12 +61,12 @@ module SupportTableCache
 
     private
 
-    def support_table_find_by_attribute_names(attributes)
-      attributes ||= {}
-      if respond_to?(:scope_attributes) && scope_attributes.present?
-        attributes = scope_attributes.merge(attributes)
-      end
-      attributes.keys.map(&:to_s).sort
+    # The attributes a query on this class is filtering on, including any conditions from a
+    # default scope. Returns nil if the default scope conditions conflict with the passed in
+    # attributes. Note that the where clause is used rather than `scope_attributes` since that
+    # method also includes `create_with` values, which are not part of the query.
+    def support_table_query_attributes(attributes)
+      SupportTableCache.merge_query_attributes(self, all.where_values_hash.stringify_keys, attributes)
     end
   end
 end

data/lib/support_table_cache/memory_cache.rb

@@ -14,6 +14,10 @@ module SupportTableCache
     def initialize
       @cache = {}
       @mutex = Mutex.new
+      # Maps a cache key to the tokens of the fetches currently generating a value for it.
+      # Invalidating a key drops its tokens so that those fetches will not store the stale
+      # value they generated. Only keys with a fetch in flight are tracked.
+      @pending = {}
     end
 
     # Fetch a value from the cache. If the key is not found or has expired, yields to get a new value.
@@ -23,13 +27,49 @@ module SupportTableCache
     # @yield Block to execute to get a new value if the key is not cached.
     # @return [Object, nil] The cached value or the result of the block, or nil if no value is found.
     def fetch(key, expires_in: nil)
-      serialized_value, expire_at = @cache[key]
-      if serialized_value.nil? || (expire_at && expire_at < Process.clock_gettime(Process::CLOCK_MONOTONIC))
-        value = yield if block_given?
-        return nil if value.nil?
-        write(key, value, expires_in: expires_in)
-        serialized_value = Marshal.dump(value)
+      serialized_value = nil
+      token = nil
+      @mutex.synchronize do
+        cached_value, cached_expire_at = @cache[key]
+        if cached_expire_at && cached_expire_at < Process.clock_gettime(Process::CLOCK_MONOTONIC)
+          @cache.delete(key)
+        else
+          serialized_value = cached_value
+        end
+
+        if serialized_value.nil? && block_given?
+          token = Object.new
+          (@pending[key] ||= []) << token
+        end
+      end
+
+      if serialized_value.nil?
+        begin
+          value = yield if block_given?
+          return nil if value.nil?
+
+          serialized_value = Marshal.dump(value)
+          # The expiration is always recalculated from the expires_in argument so that replacing
+          # an expired entry without an expiration does not carry over the old expiration time.
+          expire_at = (Process.clock_gettime(Process::CLOCK_MONOTONIC) + expires_in if expires_in)
+
+          @mutex.synchronize do
+            # Only store the value if this key was not invalidated while the value was being
+            # generated. Otherwise a record deleted or overwritten by a concurrent update could
+            # be resurrected in the cache with stale data.
+            @cache[key] = [serialized_value, expire_at] if @pending[key]&.include?(token)
+          end
+        ensure
+          @mutex.synchronize do
+            tokens = @pending[key]
+            if tokens
+              tokens.delete(token)
+              @pending.delete(key) if tokens.empty?
+            end
+          end
+        end
       end
+
       Marshal.load(serialized_value)
     end
 
@@ -57,8 +97,13 @@ module SupportTableCache
       serialized_value = Marshal.dump(value)
 
       @mutex.synchronize do
+        # Discard any fetch generating a value for this key so that it cannot overwrite the
+        # newer value being written here.
+        @pending.delete(key)
         @cache[key] = [serialized_value, expire_at]
       end
+
+      nil
     end
 
     # Delete a value from the cache.
@@ -66,14 +111,22 @@ module SupportTableCache
     # @param key [Object] The cache key.
     # @return [void]
     def delete(key)
-      @cache.delete(key)
+      @mutex.synchronize do
+        @pending.delete(key)
+        @cache.delete(key)
+      end
+      nil
     end
 
     # Clear all values from the cache.
     #
     # @return [void]
     def clear
-      @cache.clear
+      @mutex.synchronize do
+        @pending.clear
+        @cache.clear
+      end
+      nil
     end
   end
 end

data/lib/support_table_cache/relation_override.rb

@@ -19,27 +19,22 @@ module SupportTableCache
 
       return super if select_values.present?
 
-      cache_key = nil
-      attributes = ((args.size == 1 && args.first.is_a?(Hash)) ? args.first.stringify_keys : {})
+      # Only queries by simple attribute equality can be matched against cache keys.
+      return super unless args.size == 1 && args.first.is_a?(Hash)
 
-      # Apply any attributes from the current relation chain
-      if scope_attributes.present?
-        attributes = scope_attributes.stringify_keys.merge(attributes)
-      end
+      return super unless support_table_cacheable_scope?
 
-      if attributes.present?
-        support_table_cache_by_attributes.each do |attribute_names, case_sensitive, where|
-          where&.each do |name, value|
-            if attributes.include?(name) && attributes[name] == value
-              attributes.delete(name)
-            else
-              return super
-            end
-          end
-          cache_key = SupportTableCache.cache_key(klass, attributes, attribute_names, case_sensitive)
-          break if cache_key
-        end
-      end
+      # Queries inside a transaction could see uncommitted data that would be invalid
+      # if the transaction is rolled back, so they cannot be cached.
+      return super if SupportTableCache.open_transaction?(klass)
+
+      # Apply any conditions from the current relation chain. This returns nil if the relation
+      # and the find_by arguments specify different values for the same attribute since both
+      # conditions have to be applied by the database in that case.
+      attributes = support_table_query_attributes(args.first)
+      return super if attributes.nil?
+
+      cache_key = SupportTableCache.cache_key_for_query(klass, attributes)
 
       if cache_key
         cache.fetch(cache_key, expires_in: support_table_cache_ttl) { super }
@@ -67,9 +62,16 @@ module SupportTableCache
     # @return [ActiveRecord::Base, nil] The found record or nil if not found.
     # @raise [ArgumentError] if the query cannot use the cache.
     def fetch_by(attributes)
-      find_by_attribute_names = support_table_find_by_attribute_names(attributes)
-      unless klass.support_table_cache_by_attributes.any? { |attribute_names, _ci| attribute_names == find_by_attribute_names }
-        raise ArgumentError.new("#{name} does not cache queries by #{find_by_attribute_names.to_sentence}")
+      attributes = (attributes || {}).stringify_keys
+      query_attributes = support_table_query_attributes(attributes)
+      unless SupportTableCache.cacheable_query?(klass, query_attributes)
+        raise ArgumentError.new("#{klass.name} does not cache queries by #{(query_attributes || attributes).keys.sort.to_sentence}")
+      end
+      unless support_table_cacheable_scope?
+        raise ArgumentError.new("#{klass.name} cannot cache queries on a relation with conditions that cannot be represented in the cache key")
+      end
+      if SupportTableCache.open_transaction?(klass)
+        raise ArgumentError.new("#{klass.name} cannot cache queries inside a transaction")
       end
       find_by(attributes)
     end
@@ -90,12 +92,30 @@ module SupportTableCache
 
     private
 
-    def support_table_find_by_attribute_names(attributes)
-      attributes ||= {}
-      if scope_attributes.present?
-        attributes = scope_attributes.merge(attributes)
-      end
-      attributes.keys.map(&:to_s).sort
+    # A relation can only be cached if all of its conditions are simple equality conditions
+    # on the model's own attributes that can be represented in a cache key. Anything else
+    # (SQL string conditions, ranges, OR clauses, joins, etc.) is not visible in
+    # where_values_hash and could silently change which record the query returns.
+    def support_table_cacheable_scope?
+      # WhereClause#predicates is not part of the public Rails API (its visibility has varied
+      # across Rails versions), but there is no public way to detect conditions that cannot
+      # be represented in where_values_hash. If the method is ever removed in a future Rails
+      # version, fail safe by bypassing the cache rather than raising. There is a spec
+      # asserting the method exists so an incompatible Rails upgrade fails explicitly.
+      return false unless where_clause.respond_to?(:predicates, true)
+      return false unless where_clause.send(:predicates).size == where_values_hash.size
+      return false if joins_values.present? || left_outer_joins_values.present?
+      return false if group_values.present? || !having_clause.empty?
+      return false if !from_clause.empty? || offset_value.present? || lock_value
+      return false if eager_loading?
+
+      true
+    end
+
+    # The attributes a query on this relation is filtering on. Returns nil if the relation
+    # conditions conflict with the passed in attributes.
+    def support_table_query_attributes(attributes)
+      SupportTableCache.merge_query_attributes(klass, where_values_hash.stringify_keys, (attributes || {}).stringify_keys)
     end
   end
 end

data/lib/support_table_cache.rb

@@ -28,6 +28,8 @@ module SupportTableCache
     # @api private
     class_attribute :support_table_cache_impl, instance_accessor: false
 
+    self.support_table_cache_by_attributes = []
+
     unless ActiveRecord::Relation.include?(RelationOverride)
       ActiveRecord::Relation.prepend(RelationOverride)
     end
@@ -68,13 +70,17 @@ module SupportTableCache
     # @return [void]
     def load_cache
       cache = current_support_table_cache
-      return super if cache.nil?
+      return if cache.nil?
 
       find_each do |record|
-        support_table_cache_by_attributes.each do |attribute_names, case_sensitive|
+        support_table_cache_by_attributes.each do |attribute_names, case_sensitive, where|
+          next unless where.nil? || where.all? { |name, value| record[name] == type_for_attribute(name).cast(value) }
+
           attributes = record.attributes.slice(*attribute_names)
           cache_key = SupportTableCache.cache_key(self, attributes, attribute_names, case_sensitive)
-          cache.fetch(cache_key, expires_in: support_table_cache_ttl) { record }
+          next if cache_key.nil?
+
+          cache.write(cache_key, record, expires_in: support_table_cache_ttl)
         end
       end
     end
@@ -120,9 +126,10 @@ module SupportTableCache
         where = where.stringify_keys
       end
 
-      self.support_table_cache_by_attributes ||= []
-      support_table_cache_by_attributes.delete_if { |data| data.first == attributes }
-      self.support_table_cache_by_attributes += [[attributes, case_sensitive, where]]
+      # Build a new array rather than mutating the existing one since the class attribute
+      # value can be shared with the superclass.
+      existing = (support_table_cache_by_attributes || []).reject { |data| data.first == attributes }
+      self.support_table_cache_by_attributes = existing + [[attributes, case_sensitive, where]]
     end
 
     private
@@ -138,6 +145,13 @@ module SupportTableCache
 
     def current_support_table_cache
       return nil if support_table_cache_disabled?
+      support_table_cache_for_invalidation
+    end
+
+    # The cache used when removing entries. Invalidation must ignore the disabled flag;
+    # otherwise records changed while caching is disabled would leave stale entries behind
+    # for when caching is re-enabled.
+    def support_table_cache_for_invalidation
       SupportTableCache.testing_cache || support_table_cache_impl || SupportTableCache.cache
     end
   end
@@ -241,7 +255,11 @@ module SupportTableCache
 
       sorted_attributes = {}
       sorted_names.each do |attribute_name|
-        value = (attributes[attribute_name] || attributes[attribute_name.to_sym])
+        value = (attributes.key?(attribute_name) ? attributes[attribute_name] : attributes[attribute_name.to_sym])
+        # Cast the value through the attribute type so that equivalent values (e.g. a symbol
+        # and a string, or "5" and 5) always produce the same cache key. Otherwise entries
+        # could be written under keys that the invalidation callbacks can never delete.
+        value = klass.type_for_attribute(attribute_name).cast(value)
         if !case_sensitive && (value.is_a?(String) || value.is_a?(Symbol))
           value = value.to_s.downcase
         end
@@ -251,6 +269,92 @@ module SupportTableCache
       [klass.name, sorted_attributes]
     end
 
+    # Find the cache key for a query on a set of attributes by matching the attributes
+    # against the cacheable attribute configuration for a class. Returns nil if the
+    # query cannot be cached.
+    #
+    # @param klass [Class] The class that is being queried.
+    # @param attributes [Hash] The query attributes with stringified keys.
+    # @return [Array(String, Hash), nil] The cache key or nil if the query is not cacheable.
+    # @api private
+    def cache_key_for_query(klass, attributes)
+      return nil if attributes.blank?
+
+      Array(klass.support_table_cache_by_attributes).each do |attribute_names, case_sensitive, where|
+        # Cast both sides through the attribute type so that equivalent values (e.g. 1 and "1")
+        # match the where clause the same way they are matched when building cache keys.
+        where_matched = where.nil? || where.all? do |name, value|
+          type = klass.type_for_attribute(name)
+          attributes.include?(name) && type.cast(attributes[name]) == type.cast(value)
+        end
+        next unless where_matched
+
+        key_attributes = (where ? attributes.except(*where.keys) : attributes)
+        key = cache_key(klass, key_attributes, attribute_names, case_sensitive)
+        return key if key
+      end
+
+      nil
+    end
+
+    # Return true if a query on a set of attributes can be looked up in the cache.
+    #
+    # @param klass [Class] The class that is being queried.
+    # @param attributes [Hash, nil] The query attributes with stringified keys.
+    # @return [Boolean]
+    # @api private
+    def cacheable_query?(klass, attributes)
+      return false if attributes.nil?
+
+      !cache_key_for_query(klass, attributes).nil?
+    end
+
+    # Merge the conditions from a relation's where clause with the attributes passed to a
+    # finder method. A cache key can only represent a single value per attribute, so if both
+    # specify a different value for the same attribute the query cannot be cached; the
+    # database has to apply both conditions.
+    #
+    # @param klass [Class] The class that is being queried.
+    # @param scope_conditions [Hash] The relation's where conditions with stringified keys.
+    # @param attributes [Hash] The finder attributes with stringified keys.
+    # @return [Hash, nil] The merged attributes or nil if the conditions conflict.
+    # @api private
+    def merge_query_attributes(klass, scope_conditions, attributes)
+      return attributes if scope_conditions.blank?
+
+      conflict = scope_conditions.any? do |name, value|
+        next false unless attributes.include?(name)
+
+        type = klass.type_for_attribute(name)
+        type.cast(value) != type.cast(attributes[name])
+      end
+      return nil if conflict
+
+      scope_conditions.merge(attributes)
+    end
+
+    # Return true if there is an open transaction on the class' connection. Queries should
+    # not be cached inside a transaction since they could return uncommitted data that would
+    # be invalid if the transaction is rolled back. Transactions opened with joinable: false
+    # (i.e. Rails transactional test fixtures) are ignored.
+    #
+    # @param klass [Class] The model class being queried.
+    # @return [Boolean]
+    # @api private
+    def open_transaction?(klass)
+      return false unless klass.connection_pool.active_connection?
+
+      connection = klass.connection
+      return false unless connection.transaction_open?
+
+      # current_transaction and joinable? are internal Rails APIs. If a future Rails version
+      # changes them, fail safe by treating the transaction as open (bypassing the cache)
+      # rather than raising. There is a spec asserting the API exists so an incompatible
+      # Rails upgrade fails explicitly.
+      transaction = connection.current_transaction
+      !transaction.respond_to?(:joinable?) || transaction.joinable?
+    end
+
     def fiber_local_value(varname)
       @fiber_locals[varname]
     end
@@ -267,7 +371,7 @@ module SupportTableCache
     cache_by_attributes = self.class.support_table_cache_by_attributes
     return if cache_by_attributes.blank?
 
-    cache = self.class.send(:current_support_table_cache)
+    cache = self.class.send(:support_table_cache_for_invalidation)
     return if cache.nil?
 
     cache_by_attributes.each do |attribute_names, case_sensitive|
@@ -289,7 +393,7 @@ module SupportTableCache
     cache_by_attributes = self.class.support_table_cache_by_attributes
     return if cache_by_attributes.blank?
 
-    cache = self.class.send(:current_support_table_cache)
+    cache = self.class.send(:support_table_cache_for_invalidation)
     return if cache.nil?
 
     cache_by_attributes.each do |attribute_names, case_sensitive|

data/support_table_cache.gemspec

@@ -13,6 +13,7 @@ Gem::Specification.new do |spec|
   # The `git ls-files -z` loads the files in the RubyGem that have been added into git.
   ignore_files = %w[
     .
+    AGENTS.md
     Appraisals
     Gemfile
     Gemfile.lock
@@ -27,7 +28,7 @@ Gem::Specification.new do |spec|
 
   spec.require_paths = ["lib"]
 
-  spec.add_dependency "activerecord"
+  spec.required_ruby_version = ">= 2.6"
 
-  spec.add_development_dependency "bundler"
+  spec.add_dependency "activerecord"
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: support_table_cache
 version: !ruby/object:Gem::Version
-  version: 1.1.5
+  version: 1.1.6
 platform: ruby
 authors:
 - Brian Durand
@@ -23,27 +23,12 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '0'
-- !ruby/object:Gem::Dependency
-  name: bundler
-  requirement: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
-  type: :development
-  prerelease: false
-  version_requirements: !ruby/object:Gem::Requirement
-    requirements:
-    - - ">="
-      - !ruby/object:Gem::Version
-        version: '0'
 email:
 - bbdurand@gmail.com
 executables: []
 extensions: []
 extra_rdoc_files: []
 files:
-- AGENTS.md
 - ARCHITECTURE.md
 - CHANGELOG.md
 - MIT-LICENSE
@@ -67,7 +52,7 @@ required_ruby_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="
     - !ruby/object:Gem::Version
-      version: '0'
+      version: '2.6'
 required_rubygems_version: !ruby/object:Gem::Requirement
   requirements:
   - - ">="

data/AGENTS.md

@@ -1,74 +0,0 @@
-# Copilot Instructions for support_table_cache
-
-## Project Overview
-
-This is a Ruby gem that adds transparent caching to ActiveRecord support/lookup tables. It intercepts `find_by` queries and `belongs_to` associations to cache small, rarely-changing reference tables (statuses, types, categories) without code changes.
-
-**Core principle**: Cache entries keyed by unique attribute combinations, auto-invalidated on record changes via `after_commit` callbacks.
-
-## Architecture
-
-- **lib/support_table_cache.rb**: Main module with `cache_by` DSL, cache configuration, and invalidation logic
-- **lib/support_table_cache/find_by_override.rb**: Prepends to model class to intercept `find_by` calls
-- **lib/support_table_cache/relation_override.rb**: Prepends to `ActiveRecord::Relation` to handle scoped queries (e.g., `where(group: 'x').find_by(name: 'y')`)
-- **lib/support_table_cache/associations.rb**: Extends `belongs_to` with `cache_belongs_to` to cache foreign key lookups
-- **lib/support_table_cache/memory_cache.rb**: In-process cache implementation (use `support_table_cache = :memory`)
-
-See [ARCHITECTURE.md](../ARCHITECTURE.md) for detailed flow diagrams showing cache key generation, invalidation, and association caching sequences.
-
-## Key Patterns
-
-### Model Configuration
-Models use `cache_by` to declare unique keys that can be cached. Support composite keys and case-insensitivity:
-```ruby
-cache_by :name, case_sensitive: false
-cache_by [:group, :code]
-cache_by :name, where: {deleted_at: nil}  # For default scopes
-```
-
-### Cache Key Structure
-Cache keys are `[ClassName, {attr1: val1, attr2: val2}]` arrays with sorted attribute names. Case-insensitive values are downcased before keying.
-
-### Module Prepending Pattern
-Uses `prepend` to wrap ActiveRecord methods (`find_by`) rather than monkey-patching. This allows `super` to call original behavior on cache misses or when caching disabled.
-
-## Testing
-
-- **Multi-version testing**: Uses Appraisal gem to test against ActiveRecord 5.0-8.0 (see [Appraisals](../Appraisals))
-- **Run tests**: `bundle exec rspec` (default rake task) or `bundle exec appraisal rspec` for all versions
-- **Test setup**: In-memory SQLite database created in [spec/spec_helper.rb](../spec/spec_helper.rb) with test tables
-- **Test isolation**: Tests wrapped with `SupportTableCache.testing!` in RSpec `config.before` to prevent cache pollution
-
-### Code Style
-Use **standardrb** for linting. Run `standardrb --fix` before committing. CI enforces this on ActiveRecord 8.0 matrix entry.
-
-## Common Operations
-
-### Adding Cache Support to Models
-1. Include `SupportTableCache` in model class
-2. Call `cache_by` with unique key attributes
-3. Optionally set `self.support_table_cache_ttl = 5.minutes`
-4. For associations: include `SupportTableCache::Associations` in parent model, then `cache_belongs_to :association_name`
-
-### Cache Invalidation
-Automatic via `after_commit` callback that clears all cache key variations (both old and new attribute values on updates). No manual invalidation needed unless using in-memory cache across processes.
-
-### Debugging Cache Behavior
-- Use `fetch_by` instead of `find_by` to raise error if query won't hit cache
-- Disable caching in block: `Model.disable_cache { ... }` or globally `SupportTableCache.disable { ... }`
-- Check if caching enabled: inspect `support_table_cache_by_attributes` class attribute
-
-## Development Workflow
-
-1. **Running specs locally**: `bundle exec rspec` (uses Ruby 3.3+ and ActiveRecord 8.0 from Gemfile)
-2. **Testing specific AR version**: `bundle exec appraisal activerecord_7 rspec`
-3. **Generating all gemfiles**: `bundle exec appraisal generate`
-4. **Lint before commit**: `standardrb --fix`
-5. **Release**: Only from `main` branch (enforced by `Rakefile` pre-release check)
-
-## Important Constraints
-
-- **Target models**: Only for small tables (few hundred rows max)
-- **Unique keys only**: `cache_by` attributes must define unique constraints
-- **No runtime scopes**: Cannot use `cache_belongs_to` with scoped associations (checked at configuration time)
-- **In-memory cache caveat**: Per-process, not invalidated across processes—only use for truly static data or with TTL