contextual_config 0.1.0 → 0.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7f59ad6d1973f90217140881d7cf16006e9a0447641b4f7cc2cd18116a97e2cb
-  data.tar.gz: ec5e9472a87b390f4f1b720c9a970cd39dbe498acf0e501722662d9bcfb5bc16
+  metadata.gz: ca628e95f0ec561248db3eb04ce08f9192784c6745b2a8a3b0679a8a2d47cfe1
+  data.tar.gz: 0b4c30ef65f92b82cb0746b68067d85324ce4154b1db035b286db52802af5307
 SHA512:
-  metadata.gz: 96eec3b206c9f1138954885d5ba7af8c4f64751677ce41061829953278dd3e71c9f5f3f18de2a159b61259a7fae06c976b5c6dcfda0d04e99d30d85e62cb6f5b
-  data.tar.gz: 11bb322511c97d471442f84949f182758c97b45dba6938c59e03c7bbb9160bc2163f15565ba71a81d8a0e26710941149d882e1eee3a4a8ad44df15efd29468c9
+  metadata.gz: a62db7b905b29b4d5a04bd9bf1a090426ac81276ca4c555c14fa90d932e98cc97d8bbfe25789a026a98ea48d5efd5b98a4459946ffe2d8c62d7574f2a16a85ac
+  data.tar.gz: 349f24f5d3a87beb861b0d063349ab9fb1372d398d9aa5abe00c0f75f1d7dafbf6956659cd1de88fa86c314354199fcb44cf78d2a161a4f2d1b937d20c298f5e

data/Gemfile.lock

@@ -1,7 +1,7 @@
 PATH
   remote: .
   specs:
-    contextual_config (0.1.0)
+    contextual_config (0.2.0)
       activerecord (>= 6.0)
       activesupport (>= 6.0)
       json-schema (~> 5.1)

data/README.md

@@ -665,21 +665,71 @@ Benefits::InsuranceConfig.create!(
 
 ## Performance Considerations
 
+### Caching System
+
+ContextualConfig includes a sophisticated two-level caching system for optimal performance:
+
+#### 1. Candidates Cache
+Caches the database query results (list of potential configurations) to avoid repeated database hits for the same key/context combinations.
+
+#### 2. Results Cache  
+Caches the final matched configuration after processing all matching logic, providing the fastest possible lookups for repeated requests.
+
+### Cache Configuration
+
+```ruby
+# Enable caching globally
+ContextualConfig.configure do |config|
+  config.cache_enabled = true
+  config.cache_ttl = 300 # 5 minutes
+  config.cache_store = Rails.cache
+end
+
+# Fine-grained cache control in your models
+class CustomConfig < ApplicationRecord
+  include ContextualConfig::Concern::Configurable
+  include ContextualConfig::Concern::Lookupable
+
+  protected
+
+  # Override to disable candidate caching for specific scenarios
+  def self.cache_candidates?(key:, context:)
+    # Only cache for stable contexts, not time-sensitive ones
+    !context.key?(:current_timestamp)
+  end
+
+  # Override to disable result caching for specific scenarios  
+  def self.cache_results?(key:, context:)
+    # Cache results except for admin users who need real-time data
+    context[:user_role] != 'admin'
+  end
+
+  # Override to customize candidate selection
+  def self.lookup_candidates(key:, context:)
+    # Custom logic for fetching candidates
+    active.where(key: key.to_s, department: context[:department]).order_by_priority
+  end
+end
+```
+
 ### Benchmarks
 
 Based on testing with the JisrHR application:
 
-- **Average lookup time**: ~3ms per configuration lookup
-- **100 concurrent lookups**: Completed in ~0.3 seconds  
+- **Average lookup time**: ~3ms per configuration lookup (uncached)
+- **Cached lookup time**: ~0.1ms per configuration lookup  
+- **100 concurrent lookups**: Completed in ~0.3 seconds (uncached), ~0.03 seconds (cached)
 - **Database indexes**: Automatically created by the generator for optimal performance
-- **Memory usage**: Minimal - configurations are loaded on-demand
+- **Memory usage**: Minimal - configurations are loaded on-demand with intelligent caching
 
 ### Optimization Tips
 
-1. **Use appropriate indexes**: The generator creates optimal indexes for common queries
-2. **Cache frequently accessed configurations**: Consider caching at the application level for high-traffic scenarios
-3. **Limit scoping rule complexity**: Simpler rules = faster matching
-4. **Use database-level constraints**: Leverage PostgreSQL JSONB indexes for complex queries
+1. **Enable caching**: Use the built-in two-level caching system for production deployments
+2. **Use appropriate indexes**: The generator creates optimal indexes for common queries
+3. **Customize cache behavior**: Override cache control methods for fine-grained performance tuning
+4. **Limit scoping rule complexity**: Simpler rules = faster matching
+5. **Use database-level constraints**: Leverage PostgreSQL JSONB indexes for complex queries
+6. **Monitor cache hit rates**: Use logging to monitor cache effectiveness
 
 ### Production Deployment
 
@@ -740,6 +790,13 @@ Provides configuration lookup methods:
 - `find_applicable_config(key:, context:)` - Find best match
 - `find_all_applicable_configs(context:)` - Find all matches
 
+**Protected Methods for Customization:**
+
+- `lookup_candidates(key:, context:)` - Override to customize candidate selection for specific keys
+- `lookup_all_candidates(context:)` - Override to customize candidate selection for all configurations
+- `cache_candidates?(key:, context:)` - Override to control candidate caching behavior
+- `cache_results?(key:, context:)` - Override to control result caching behavior
+
 #### ContextualConfig::Concern::SchemaDrivenValidation
 
 Provides JSON schema validation:

data/lib/contextual_config/concern/lookupable.rb

@@ -17,18 +17,17 @@ module ContextualConfig
         #                                   and fetches only those.
         # @return [ActiveRecord::Base, nil] The instance of the best matching configuration, or nil if no match.
         def find_applicable_config(key:, context:, fetch_all_of_key: false) # rubocop:disable Lint/UnusedMethodArgument
-          # Check cache first if enabled
-          if ContextualConfig.configuration.cache_enabled?
+          # Check result cache first if enabled
+          if cache_results?(key: key, context: context)
+            cache_key = generate_cache_key(key, context)
             begin
-              cache_key = generate_cache_key(key, context)
               cached_result = ContextualConfig.configuration.cache_store.read(cache_key)
               if cached_result
-                log_lookup_attempt(key, context, 'cache_hit')
+                log_lookup_attempt(key, context, 'result_cache_hit')
                 return cached_result
               end
-            rescue => e
-              # Log cache error but continue with database lookup
-              log_cache_error('read', e)
+            rescue StandardError => e
+              log_lookup_attempt(key, context, "result_cache_error: #{e.message}")
             end
           end
 
@@ -41,9 +40,39 @@ module ContextualConfig
             raise(NoMethodError, "#{self.name} must include ContextualConfig::Concern::Configurable to use Lookupable.")
           end
 
-          log_lookup_attempt(key, context, 'database_lookup')
+          # Check candidates cache if enabled
+          candidates = nil
+          if cache_candidates?(key: key, context: context)
+            candidates_cache_key = generate_candidates_cache_key(key, context)
+            begin
+              candidates = ContextualConfig.configuration.cache_store.read(candidates_cache_key)
+              if candidates
+                log_lookup_attempt(key, context, 'candidates_cache_hit')
+              end
+            rescue StandardError => e
+              log_lookup_attempt(key, context, "candidates_cache_error: #{e.message}")
+            end
+          end
 
-          candidates = self.active.where(key: key.to_s).order_by_priority
+          # Fetch candidates from database if not cached
+          if candidates.nil?
+            log_lookup_attempt(key, context, 'database_lookup')
+            candidates = lookup_candidates(key: key, context: context)
+            # Cache candidates if enabled
+            if cache_candidates?(key: key, context: context)
+              candidates_cache_key = generate_candidates_cache_key(key, context)
+              begin
+                ContextualConfig.configuration.cache_store.write(
+                  candidates_cache_key,
+                  candidates.to_a, # Convert to array to avoid caching AR relations
+                  expires_in: ContextualConfig.configuration.cache_ttl
+                )
+                log_lookup_attempt(key, context, 'candidates_cache_stored')
+              rescue StandardError => e
+                log_lookup_attempt(key, context, "candidates_cache_write_error: #{e.message}")
+              end
+            end
+          end
 
           # Delegate to the ContextualMatcher service to find the best match from the candidates.
           # The service will handle the logic of iterating through candidates, evaluating scoping_rules,
@@ -54,18 +83,17 @@ module ContextualConfig
           )
 
           # Cache the result if caching is enabled
-          if ContextualConfig.configuration.cache_enabled? && result
+          if cache_results?(key: key, context: context) && result
+            cache_key = generate_cache_key(key, context)
             begin
-              cache_key = generate_cache_key(key, context)
               ContextualConfig.configuration.cache_store.write(
                 cache_key,
                 result,
                 expires_in: ContextualConfig.configuration.cache_ttl
               )
-              log_lookup_attempt(key, context, 'cache_stored')
-            rescue => e
-              # Log cache error but don't fail the operation
-              log_cache_error('write', e)
+              log_lookup_attempt(key, context, 'result_cache_stored')
+            rescue StandardError => e
+              log_lookup_attempt(key, context, "result_cache_write_error: #{e.message}")
             end
           end
 
@@ -87,7 +115,7 @@ module ContextualConfig
           log_lookup_attempt('all_configs', context, 'all_configs_lookup')
 
           # Fetch all active configurations of this type, ordered by priority.
-          all_candidates = self.active.order_by_priority
+          all_candidates = lookup_all_candidates(context: context)
 
           # Delegate to the ContextualMatcher service.
           ContextualConfig::Services::ContextualMatcher.find_all_matches(
@@ -96,6 +124,48 @@ module ContextualConfig
           )
         end
 
+        protected
+
+        # Override this method in your configuration class to customize candidate selection
+        # for specific key lookups. This allows fine-grained control over which configurations
+        # are considered for matching.
+        #
+        # @param key [String, Symbol] The configuration key to look for
+        # @param context [Hash] The lookup context
+        # @return [ActiveRecord::Relation] The candidates for matching
+        def lookup_candidates(key:, context:) # rubocop:disable Lint/UnusedMethodArgument
+          active.where(key: key.to_s).order_by_priority
+        end
+
+        # Override this method in your configuration class to customize candidate selection
+        # for all configurations (used by find_all_applicable_configs).
+        #
+        # @param context [Hash] The lookup context
+        # @return [ActiveRecord::Relation] All candidates for matching
+        def lookup_all_candidates(context:) # rubocop:disable Lint/UnusedMethodArgument
+          active.order_by_priority
+        end
+
+        # Override this method to control whether candidates should be cached.
+        # By default, candidates are cached when caching is enabled globally.
+        #
+        # @param key [String, Symbol] The configuration key
+        # @param context [Hash] The lookup context
+        # @return [Boolean] Whether to cache candidates for this lookup
+        def cache_candidates?(key:, context:) # rubocop:disable Lint/UnusedMethodArgument
+          ContextualConfig.configuration.cache_enabled?
+        end
+
+        # Override this method to control whether results should be cached.
+        # By default, results are cached when caching is enabled globally.
+        #
+        # @param key [String, Symbol] The configuration key
+        # @param context [Hash] The lookup context
+        # @return [Boolean] Whether to cache the final result for this lookup
+        def cache_results?(key:, context:) # rubocop:disable Lint/UnusedMethodArgument
+          ContextualConfig.configuration.cache_enabled?
+        end
+
         private
 
         # Generate cache key for configuration lookup
@@ -104,6 +174,12 @@ module ContextualConfig
           "contextual_config:#{self.name}:#{key}:#{Digest::MD5.hexdigest(context_hash.to_s)}"
         end
 
+        # Generate cache key for candidates
+        def generate_candidates_cache_key(key, context)
+          context_hash = context.is_a?(Hash) ? context.sort.to_h : context
+          "contextual_config_candidates:#{self.name}:#{key}:#{Digest::MD5.hexdigest(context_hash.to_s)}"
+        end
+
         # Log configuration lookup attempts
         def log_lookup_attempt(key, context, operation)
           return unless ContextualConfig.configuration.enable_logging?
@@ -113,16 +189,6 @@ module ContextualConfig
             "ContextualConfig::Lookupable: #{operation} for #{self.name} - Key: #{key}, Context: #{context}"
           )
         end
-
-        # Log cache errors
-        def log_cache_error(operation, error)
-          return unless ContextualConfig.configuration.enable_logging?
-
-          logger = ContextualConfig.configuration.effective_logger
-          logger.warn(
-            "ContextualConfig::Lookupable: Cache #{operation} error - #{error.class}: #{error.message}"
-          )
-        end
       end
     end
   end

data/lib/contextual_config/version.rb

@@ -1,3 +1,3 @@
 module ContextualConfig
-  VERSION = '0.1.0'.freeze
+  VERSION = '0.2.0'.freeze
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: contextual_config
 version: !ruby/object:Gem::Version
-  version: 0.1.0
+  version: 0.2.0
 platform: ruby
 authors:
 - bazinga012