magick-feature-flags 0.9.22 → 0.9.24

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 42699b3af1d542ac14b10f2b82ea4156da27b68e3e2a07e715cd528f0e3f936b
-  data.tar.gz: 0c5235c6cb220201ed0443d1a4633009325d410620d8d28ecbb836cac01bdc25
+  metadata.gz: 9aaecf68655a77ae48f4f7b2d7f760528a4aa14aa5f37b5f8a603897e3040d40
+  data.tar.gz: 8b9694162f06fded4597aaadd14334c515f996979161915004ef113a979aba38
 SHA512:
-  metadata.gz: 10fb678c4aeaf5a17f721341e01ec937bf9a14042e4a90fa0bcc1aba13c5e91272aba144fa05913a020660ffd602ccf7481d216e92364338c7e4a111794e0896
-  data.tar.gz: '079e2d11d6ab0339929f965c1eb05fc934ea88522f26e268df324c366ad28268f87131233fe0f2315a5494328ae5fa18790e8e512fa550372852c3c1d61c3faf'
+  metadata.gz: 4f47eaddee984442954a6a9f556c434469f8f9c923c93daa4971e232ff0b8ee248c96a510c505c3caecd99ed38687ec2a27544d8624837030a767b13b6253d0f
+  data.tar.gz: e2523e3c4051c6922638bdf6739eb3dc89e92822a1a93b0f542d6827bb5706a59d8de3bf2d56d1125584d5e20c016f92b3314b9f1f6ac047cab0ce828b00ad7d

data/README.md

@@ -10,7 +10,7 @@ A performant and memory-efficient feature toggle gem for Ruby and Rails applicat
 - **Rails Integration**: Seamless integration with Rails, including request store caching
 - **DSL Support**: Define features in a Ruby DSL file (`config/features.rb`)
 - **Thread-Safe**: All operations are thread-safe for concurrent access
-- **Performance**: Optimized for speed with memory-first caching strategy
+- **Performance**: Lightning-fast feature checks with async metrics recording and memory-first caching strategy
 - **Advanced Features**: Circuit breaker, audit logging, performance metrics, versioning, and more
 
 ## Installation
@@ -52,7 +52,8 @@ The generator creates `config/initializers/magick.rb` with sensible defaults. Yo
 ```ruby
 Magick.configure do
   # Configure Redis (optional)
-  redis url: ENV['REDIS_URL']
+  # Use database 1 by default to avoid conflicts with Rails cache (which uses DB 0)
+  redis url: ENV['REDIS_URL'], db: 1
 
   # Enable features
   performance_metrics enabled: true
@@ -73,7 +74,10 @@ Magick.configure do
   memory_ttl 7200 # 2 hours
 
   # Redis configuration
-  redis url: ENV['REDIS_URL'], namespace: 'magick:features'
+  # Use separate database (DB 1) to avoid conflicts with Rails cache (DB 0)
+  # This ensures feature toggles persist even when Rails cache is cleared
+  redis url: ENV['REDIS_URL'], namespace: 'magick:features', db: 1
+  # Or include database in URL: redis url: 'redis://localhost:6379/1'
 
   # Circuit breaker settings
   circuit_breaker threshold: 5, timeout: 60
@@ -383,7 +387,9 @@ Magick.configure do
 end
 ```
 
-**Note:** When `redis_tracking: true` is set, usage counts are persisted to Redis and aggregated across all processes, giving you total usage statistics.
+**Performance:** Metrics are recorded asynchronously in a background thread, ensuring zero overhead on feature checks. The `enabled?` method remains lightning-fast even with metrics enabled.
+
+**Note:** When `redis_tracking: true` is set, usage counts are persisted to Redis and aggregated across all processes, giving you total usage statistics. Metrics are automatically flushed in batches to minimize Redis overhead.
 
 #### Audit Logging
 
@@ -424,6 +430,9 @@ With Redis configured:
 - ✅ Persistent storage across restarts
 - ✅ Zero Redis calls on feature checks (only memory lookups)
 - ✅ Automatic cache invalidation when features change in any process
+- ✅ **Isolated from Rails cache** - Use `db: 1` to store feature toggles in a separate Redis database, ensuring they persist even when Rails cache is cleared
+
+**Important:** By default, Magick uses Redis database 1 to avoid conflicts with Rails cache (which typically uses database 0). This ensures that clearing Rails cache (`Rails.cache.clear`) won't affect your feature toggle states.
 
 ### Feature Types
 

data/lib/magick/config.rb

@@ -3,7 +3,7 @@
 module Magick
   class Config
     attr_accessor :adapter_registry, :performance_metrics, :audit_log, :versioning, :warn_on_deprecated,
-                  :async_updates, :memory_ttl, :circuit_breaker_threshold, :circuit_breaker_timeout, :redis_url, :redis_namespace, :environment
+                  :async_updates, :memory_ttl, :circuit_breaker_threshold, :circuit_breaker_timeout, :redis_url, :redis_namespace, :redis_db, :environment
 
     def initialize
       @warn_on_deprecated = false
@@ -12,6 +12,7 @@ module Magick
       @circuit_breaker_threshold = 5
       @circuit_breaker_timeout = 60
       @redis_namespace = 'magick:features'
+      @redis_db = nil # Use default database (0) unless specified
       @environment = defined?(Rails) ? Rails.env.to_s : 'development'
     end
 
@@ -38,10 +39,11 @@ module Magick
       configure_memory_adapter(**options)
     end
 
-    def redis(url: nil, namespace: nil, **options)
+    def redis(url: nil, namespace: nil, db: nil, **options)
       @redis_url = url if url
       @redis_namespace = namespace if namespace
-      redis_adapter = configure_redis_adapter(url: url, namespace: namespace, **options)
+      @redis_db = db if db
+      redis_adapter = configure_redis_adapter(url: url, namespace: namespace, db: db, **options)
 
       # Automatically create Registry adapter if it doesn't exist
       # This allows users to just call `redis url: ...` without needing to call `adapter :registry`
@@ -161,17 +163,33 @@ module Magick
       adapter
     end
 
-    def configure_redis_adapter(url: nil, namespace: nil, client: nil)
+    def configure_redis_adapter(url: nil, namespace: nil, db: nil, client: nil)
       return nil unless defined?(Redis)
 
       url ||= @redis_url
       namespace ||= @redis_namespace
+      db ||= @redis_db
 
       redis_client = client || begin
+        redis_options = {}
+
         if url
-          ::Redis.new(url: url)
+          # Parse URL to extract database number if present
+          parsed_url = URI.parse(url) rescue nil
+          db_from_url = nil
+          if parsed_url && parsed_url.path && parsed_url.path.length > 1
+            # Redis URL format: redis://host:port/db_number
+            db_from_url = parsed_url.path[1..-1].to_i
+          end
+
+          # Use db parameter if provided, otherwise use db from URL, otherwise nil (default DB 0)
+          final_db = db || db_from_url
+          redis_options[:db] = final_db if final_db
+          redis_options[:url] = url
+          ::Redis.new(redis_options)
         else
-          ::Redis.new
+          redis_options[:db] = db if db
+          ::Redis.new(redis_options)
         end
       rescue StandardError
         nil
@@ -179,6 +197,20 @@ module Magick
 
       return nil unless redis_client
 
+      # If db was specified but not in URL, select it explicitly
+      # This handles cases where URL doesn't include db number
+      if db && url
+        parsed_url = URI.parse(url) rescue nil
+        url_has_db = parsed_url && parsed_url.path && parsed_url.path.length > 1
+        unless url_has_db
+          begin
+            redis_client.select(db)
+          rescue StandardError
+            # Ignore if SELECT fails (some Redis setups don't support SELECT, e.g., Redis Cluster)
+          end
+        end
+      end
+
       adapter = Adapters::Redis.new(redis_client)
       adapter.instance_variable_set(:@namespace, namespace) if namespace
       adapter

data/lib/magick/performance_metrics.rb

@@ -40,23 +40,43 @@ module Magick
       @_rails_events_enabled = defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
       @_adapter_available = nil # Will be cached on first check
       @_redis_available = nil # Will be cached on first check
+
+      # Async recording queue for non-blocking metrics
+      @async_queue = Queue.new
+      @async_thread = nil
+      @async_enabled = true # Enable async by default for performance
+      start_async_processor
     end
 
     # Public accessor for redis_enabled
     attr_reader :redis_enabled
 
     def record(feature_name, operation, duration, success: true)
-      # Fast path: minimize work in mutex
-      feature_name_str = feature_name.to_s
+      # Fast path: push to async queue (non-blocking, zero overhead in hot path)
+      # Queue#<< is thread-safe and lock-free - extremely fast!
+      return unless @async_enabled
+
+      # Push to async queue - this is lock-free and extremely fast
+      # Use non-blocking push (will raise if queue is full, but our queue is unbounded)
+      begin
+        @async_queue << [feature_name.to_s, operation.to_s, duration, success]
+      rescue ThreadError, ClosedQueueError
+        # Queue is closed or thread died, disable async
+        @async_enabled = false
+      end
+
+      nil
+    end
 
+    # Internal: Process metrics from async queue (runs in background thread)
+    def process_async_record(feature_name_str, operation_str, duration, success)
       # Minimize mutex lock time - only update counters
       pending_count = nil
       total_pending = nil
       @mutex.synchronize do
         # Only create Metric object if we're keeping metrics in memory
-        # Most of the time we just need counters, not full metric objects
         if @metrics.length < 1000
-          metric = Metric.new(feature_name_str, operation, duration, success: success)
+          metric = Metric.new(feature_name_str, operation_str, duration, success: success)
           @metrics << metric
         end
         @usage_count[feature_name_str] += 1
@@ -69,14 +89,48 @@ module Magick
 
       # Rails 8+ event for usage tracking (cached check)
       if @_rails_events_enabled
-        Magick::Rails::Events.usage_tracked(feature_name, operation: operation, duration: duration, success: success)
+        Magick::Rails::Events.usage_tracked(feature_name_str, operation: operation_str, duration: duration,
+                                                              success: success)
       end
 
-      # Batch flush check - only if we're close to batch size (avoid expensive checks)
-      # Check pending count first before doing expensive adapter checks
+      # Batch flush check - only if we're close to batch size
       flush_to_redis_if_needed if pending_count >= @batch_size || total_pending >= @batch_size
+    end
 
-      nil # Don't return metric object to avoid allocation overhead
+    # Start background thread to process async metrics
+    def start_async_processor
+      return if @async_thread&.alive?
+
+      @async_thread = Thread.new do
+        last_flush_check = Time.now
+        loop do
+          # Wait for metrics with timeout to allow periodic flush checks
+          # Queue#pop with timeout returns nil on timeout, raises on closed queue
+          begin
+            data = @async_queue.pop(timeout: 1.0)
+          rescue ThreadError => e
+            # Queue closed or thread interrupted
+            break if e.message.include?('queue closed')
+
+            raise
+          end
+
+          if data
+            feature_name_str, operation_str, duration, success = data
+            process_async_record(feature_name_str, operation_str, duration, success)
+            last_flush_check = Time.now
+          elsif Time.now - last_flush_check >= 1.0
+            # Timeout - check if we need to flush based on time (every second)
+            flush_to_redis_if_needed
+            last_flush_check = Time.now
+          end
+        rescue StandardError => e
+          # Log error but continue processing
+          warn "Magick: Error in async metrics processor: #{e.message}" if defined?(Rails) && Rails.env.development?
+          sleep 0.1 # Brief pause on error
+        end
+      end
+      @async_thread.abort_on_exception = false
     end
 
     def flush_to_redis_if_needed
@@ -326,5 +380,13 @@ module Magick
         @flushed_counts.clear
       end
     end
+
+    # Stop async processor (for cleanup)
+    def stop_async_processor
+      @async_enabled = false
+      @async_queue.close if @async_queue.respond_to?(:close)
+      @async_thread&.kill
+      @async_thread = nil
+    end
   end
 end

data/lib/magick/rails/railtie.rb

@@ -25,7 +25,13 @@ if defined?(Rails)
               if defined?(Redis)
                 begin
                   redis_url = app.config.respond_to?(:redis_url) ? app.config.redis_url : nil
-                  redis_client = redis_url ? ::Redis.new(url: redis_url) : ::Redis.new
+                  # Use database 1 for Magick by default to avoid conflicts with Rails cache (which uses DB 0)
+                  # Users can override this in their config/initializers/magick.rb
+                  redis_db = 1
+                  redis_options = {}
+                  redis_options[:url] = redis_url if redis_url
+                  redis_options[:db] = redis_db
+                  redis_client = redis_url ? ::Redis.new(redis_options) : ::Redis.new(db: redis_db)
                   memory_adapter = Adapters::Memory.new
                   redis_adapter = Adapters::Redis.new(redis_client)
                   magick.adapter_registry = Adapters::Registry.new(memory_adapter, redis_adapter)

data/lib/magick/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Magick
-  VERSION = '0.9.22'
+  VERSION = '0.9.24'
 end

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: magick-feature-flags
 version: !ruby/object:Gem::Version
-  version: 0.9.22
+  version: 0.9.24
 platform: ruby
 authors:
 - Andrew Lobanov
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-11-24 00:00:00.000000000 Z
+date: 2025-12-02 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: rspec