support_table_cache 1.1.4 → 1.1.5

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5102ba8b7a75ecc7186dc527880ff0278f9e259b020fc8b36b8e3e72c4b0c150
-  data.tar.gz: ebf2696d9ea3917895038b35989d2c23c5b418db4f405c4b36812e6da59f7691
+  metadata.gz: 9fe5a9190c32271b431faed20e0b6ddbeb195cd05c927cae94c03b5c7d20bc8a
+  data.tar.gz: 8f8bc59c1a0eb6240712e50fb34da28f45d071e1c6b59e28d647d8bcf7e17896
 SHA512:
-  metadata.gz: eae75a3e8afea4fcf9cff14fec02110ab0f332685bd912ca3f37fdd17baeeaa2db107824cbd0f6bec18acdf501815012476fd48f50d63b3a38c0767daae7cf98
-  data.tar.gz: 1be4a2c1013221d4af65eb26dbfd5e9c56eb130a4bdc94ce540854f11a3df7dd7526e264ba645f7e46340cd43de8bef8899837043031aeae8897e463113e4fc5
+  metadata.gz: c833468a94fed3f16efd45022c56cbf19c755d6f0e2f48a2d93b8b92c2d946bd46f246170a623f2edeade892aa017851d581794fc7505c4efd5c5bce3fdf29b9
+  data.tar.gz: d4307c2d653184fe890e8aa8af0c548ef340d817141fddcb69e8a083ffcd235fa7d0d124b98e6ece0dd99e5a8fc549db1a8a986acf571aada17cb6f0619c67e1

data/AGENTS.md

@@ -0,0 +1,74 @@
+# 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

data/CHANGELOG.md

@@ -4,6 +4,13 @@ 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.5
+
+### Fixed
+
+- Replaced thread local variables with fiber local variables to prevent the possibility of behavior from leaking across fibers when disabling the cache in a block.
+- Allow setting the cache to an in-memory cache by setting `support_table_cache` to `true`.
+
 ## 1.1.4
 
 ### Fixed
@@ -13,21 +20,25 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## 1.1.3
 
 ### Fixed
+
 - Avoid calling methods that require a database connection when setting up belongs to caching.
 
 ## 1.1.2
 
 ### Fixed
+
 - Do not cache records where only some of the columns have been loaded with a call to `select`.
 
 ## 1.1.1
 
 ### Fixed
+
 - Fixed disabled and disable_cache methods to yield a block to match the documentation.
 
 ## 1.1.0
 
 ### Added
+
 - Added fetch_by and fetch_by! methods that can verify the result will be cacheable.
 - Allow configuring cache storage on a per class basis.
 - Allow disabling caching on per class basis.
@@ -36,15 +47,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Added test mode to intialize new caches within a test block.
 
 ### Changed
+
 - Changed fiber local variables used for disabling the cache to thread local variables.
 - Using find_by! on a relation will now use the cache.
 
 ## 1.0.1
 
 ### Added
+
 - Preserve scope on relations terminated with a `find_by`.
 
 ## 1.0.0
 
 ### Added
+
 - Add SupportTableCache concern to enable automatic caching on models when calling `find_by` with unique key parameters.

data/README.md

@@ -19,6 +19,18 @@ end
 
 With this gem, you can avoid the database query associated with the `find_by` call. You don't need to alter your code in any way other than to include `SupportTableCache` in your model and telling it the attributes that comprise a unique key, which can be used for caching.
 
+## Table of Contents
+
+- [Usage](#usage)
+  - [Setting the Cache](#setting-the-cache)
+  - [Disabling Caching](#disabling-caching)
+  - [Caching Belongs to Associations](#caching-belongs-to-associations)
+  - [Testing](#testing)
+  - [Companion Gems](#companion-gems)
+- [Installation](#installation)
+- [Contributing](#contributing)
+- [License](#license)
+
 ## Usage
 
 To use the gem, you need to include it in you models and then specify which attributes can be used for caching with the `cache_by` method. A caching attribute must be a unique key on the model. For a composite unique key, you can specify an array of attributes. If any of the attributes are case-insensitive strings, you need to specify that as well.
@@ -115,6 +127,9 @@ end
 
 You can include `SupportTableCache::Associations` in your `ApplicationRecord` class to make association caching available on all models.
 
+> [!NOTE]
+> You still need to set up the target model to cache by the primary key used by the belongs to association. Otherwise the association will not be cached.
+
 ### Testing
 
 Caching may interfere with tests by allowing data created in one test to leak into subsequent tests. You can resolve this by wrapping your tests with the `SupportTableCache.testing!` method.
@@ -132,14 +147,16 @@ class MiniTest::Spec
   around do |tests|
     SupportTableCache.testing!(&tests)
   end
-=end
-
+end
 ```
 
-### Maintaining Data
+### Companion Gems
 
 You can use the companion [support_table_data gem](https://github.com/bdurand/support_table_data) to provide functionality for loading static data into your support tables as well as adding helper functions to make looking up specific rows much easier.
 
+> [!TIP]
+> The [support_table](https://github.com/bdurand/support_table) gem combines both gems in a drop in solution for Rails applications.
+
 ## Installation
 
 Add this line to your application's Gemfile:

data/VERSION

@@ -1 +1 @@
-1.1.4
+1.1.5

data/lib/support_table_cache/fiber_locals.rb

@@ -0,0 +1,53 @@
+# frozen_string_literal: true
+
+module SupportTableCache
+  # Utility class for managing fiber-local variables. This implementation
+  # does not pollute the global namespace.
+  class FiberLocals
+    def initialize
+      @mutex = Mutex.new
+      @locals = {}
+    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]
+    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
+
+        previous_value = fiber_locals[key]
+        fiber_locals[key] = value
+
+        yield
+      ensure
+        if inited_vars
+          @mutex.synchronize do
+            @locals.delete(fiber_id)
+          end
+        else
+          fiber_locals[key] = previous_value
+        end
+      end
+    end
+  end
+end

data/lib/support_table_cache.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require_relative "support_table_cache/associations"
+require_relative "support_table_cache/fiber_locals"
 require_relative "support_table_cache/find_by_override"
 require_relative "support_table_cache/relation_override"
 require_relative "support_table_cache/memory_cache"
@@ -10,6 +11,13 @@ require_relative "support_table_cache/memory_cache"
 module SupportTableCache
   extend ActiveSupport::Concern
 
+  NOT_SET = Object.new.freeze
+  private_constant :NOT_SET
+
+  @fiber_locals = FiberLocals.new
+  @cache = NOT_SET
+  @disabled = false
+
   included do
     # @api private Used to store the list of attribute names used for caching.
     class_attribute :support_table_cache_by_attributes, instance_accessor: false
@@ -42,14 +50,7 @@ module SupportTableCache
     # @yield Executes the provided block with caching disabled or enabled.
     # @return [Object] The return value of the block.
     def disable_cache(disabled = true, &block)
-      varname = "support_table_cache_disabled:#{name}"
-      save_val = Thread.current.thread_variable_get(varname)
-      begin
-        Thread.current.thread_variable_set(varname, !!disabled)
-        yield
-      ensure
-        Thread.current.thread_variable_set(varname, save_val)
-      end
+      SupportTableCache.with_fiber_local("support_table_cache_disabled:#{name}", !!disabled, &block)
     end
 
     # Enable the caching behavior for this class within the block. The enabled setting
@@ -81,10 +82,10 @@ module SupportTableCache
     # Set a class-specific cache to use in lieu of the global cache.
     #
     # @param cache [ActiveSupport::Cache::Store, Symbol] The cache instance to use. You can also
-    #   specify the value :memory to use an optimized in-memory cache.
+    #   specify the value :memory or true to use an optimized in-memory cache.
     # @return [void]
     def support_table_cache=(cache)
-      cache = MemoryCache.new if cache == :memory
+      cache = MemoryCache.new if cache == :memory || cache == true
       self.support_table_cache_impl = cache
     end
 
@@ -127,7 +128,7 @@ module SupportTableCache
     private
 
     def support_table_cache_disabled?
-      current_block_value = Thread.current.thread_variable_get("support_table_cache_disabled:#{name}")
+      current_block_value = SupportTableCache.fiber_local_value("support_table_cache_disabled:#{name}")
       if current_block_value.nil?
         SupportTableCache.disabled?
       else
@@ -150,13 +151,7 @@ module SupportTableCache
     # @return [Object, nil] The return value of the block if a block is given, nil otherwise.
     def disable(disabled = true, &block)
       if block
-        save_val = Thread.current.thread_variable_get(:support_table_cache_disabled)
-        begin
-          Thread.current.thread_variable_set(:support_table_cache_disabled, !!disabled)
-          yield
-        ensure
-          Thread.current.thread_variable_set(:support_table_cache_disabled, save_val)
-        end
+        SupportTableCache.with_fiber_local("support_table_cache_disabled", !!disabled, &block)
       else
         @disabled = !!disabled
       end
@@ -174,9 +169,9 @@ module SupportTableCache
     # Return true if caching has been disabled.
     # @return [Boolean]
     def disabled?
-      block_value = Thread.current.thread_variable_get(:support_table_cache_disabled)
+      block_value = SupportTableCache.fiber_local_value("support_table_cache_disabled")
       if block_value.nil?
-        !!(defined?(@disabled) && @disabled)
+        !!@disabled
       else
         block_value
       end
@@ -197,7 +192,7 @@ module SupportTableCache
     def cache
       if testing_cache
         testing_cache
-      elsif defined?(@cache)
+      elsif @cache != NOT_SET
         @cache
       elsif defined?(Rails.cache)
         Rails.cache
@@ -211,14 +206,11 @@ module SupportTableCache
     # @yield Executes the provided block in test mode.
     # @return [Object] The return value of the block.
     def testing!(&block)
-      save_val = Thread.current.thread_variable_get(:support_table_cache_test_cache)
+      save_val = SupportTableCache.fiber_local_value("support_table_cache_test_cache")
       if save_val.nil?
-        Thread.current.thread_variable_set(:support_table_cache_test_cache, MemoryCache.new)
-      end
-      begin
+        SupportTableCache.with_fiber_local("support_table_cache_test_cache", MemoryCache.new, &block)
+      else
         yield
-      ensure
-        Thread.current.thread_variable_set(:support_table_cache_test_cache, save_val)
       end
     end
 
@@ -227,9 +219,9 @@ module SupportTableCache
     # @return [SupportTableCache::MemoryCache, nil] The test cache or nil if not in test mode.
     # @api private
     def testing_cache
-      unless defined?(@cache) && @cache.nil?
-        Thread.current.thread_variable_get(:support_table_cache_test_cache)
-      end
+      return nil if @cache.nil?
+
+      SupportTableCache.fiber_local_value("support_table_cache_test_cache")
     end
 
     # Generate a consistent cache key for a set of attributes. It will return nil if the attributes
@@ -258,6 +250,14 @@ module SupportTableCache
 
       [klass.name, sorted_attributes]
     end
+
+    def fiber_local_value(varname)
+      @fiber_locals[varname]
+    end
+
+    def with_fiber_local(varname, value, &block)
+      @fiber_locals.with(varname, value, &block)
+    end
   end
 
   # Remove the cache entry for this record.

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: support_table_cache
 version: !ruby/object:Gem::Version
-  version: 1.1.4
+  version: 1.1.5
 platform: ruby
 authors:
 - Brian Durand
@@ -43,6 +43,7 @@ executables: []
 extensions: []
 extra_rdoc_files: []
 files:
+- AGENTS.md
 - ARCHITECTURE.md
 - CHANGELOG.md
 - MIT-LICENSE
@@ -50,6 +51,7 @@ files:
 - VERSION
 - lib/support_table_cache.rb
 - lib/support_table_cache/associations.rb
+- lib/support_table_cache/fiber_locals.rb
 - lib/support_table_cache/find_by_override.rb
 - lib/support_table_cache/memory_cache.rb
 - lib/support_table_cache/relation_override.rb
@@ -72,7 +74,7 @@ required_rubygems_version: !ruby/object:Gem::Requirement
     - !ruby/object:Gem::Version
       version: '0'
 requirements: []
-rubygems_version: 3.6.9
+rubygems_version: 4.0.3
 specification_version: 4
 summary: Automatic ActiveRecord caching for small support tables.
 test_files: []