magick-feature-flags 0.9.23 → 0.9.25

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 0cae8aed5b88784ad2c7b2635b377cd17270044eea05e4f47a18bd3a209c9e3f
-  data.tar.gz: f2c69d41bd7a26010f25eee8e0088d660e90fdeb976de961192dcbc52c781c3d
+  metadata.gz: 955281614bf30144cc9ab808bc425aa3ef9a7217f54fda216fbc1666e159a282
+  data.tar.gz: 4dcfafc1e22d19472464da79de5765b02a4f9e0540e9d2ff16ee7527110d2924
 SHA512:
-  metadata.gz: 7a184080f97332ecac03e71f3ae72791ed3a01389a05f84dfdab7d6588dca2a0e8da7c5c5f78b9dc7fee05c09ddbdb302bd8cc97e8a6af0b276e621a01331640
-  data.tar.gz: c51c09f333e04b46e980c8c6ff67d434611208d716757b53850d625630a48c73c6f4c961f091909ade1fd33d0170f0128111fefb1d1a181f9a012e77be2be1ab
+  metadata.gz: 1dbbd4877f1a84a8770f5b9175920ca5060e7b26b7acf23f1006094a33287ff41525ebef847ee0ebf50f22e94f14f2c20755621f503df9941cf2b8649b82e110
+  data.tar.gz: 0be714620546fc53ba039b417b0b6d85627346da8bb60acd6432f6e058ab650f20c3b0ec70f367972056dd0a7c1731244da5732bb0a572ae0047d6d1a46d535e

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
@@ -33,7 +33,7 @@ Or install it yourself as:
 $ gem install magick
 ```
 
-## Installation
+## Setup
 
 After adding the gem to your Gemfile and running `bundle install`, generate the configuration file:
 
@@ -43,6 +43,22 @@ rails generate magick:install
 
 This will create `config/initializers/magick.rb` with a basic configuration.
 
+### ActiveRecord Adapter (Optional)
+
+If you want to use ActiveRecord as a persistent storage backend, generate the migration:
+
+```bash
+rails generate magick:active_record
+```
+
+This will create a migration file that creates the `magick_features` table. Then run:
+
+```bash
+rails db:migrate
+```
+
+**Note:** The ActiveRecord adapter is optional and only needed if you want database-backed feature flags. The gem works perfectly fine with just the memory adapter or Redis adapter.
+
 ## Configuration
 
 ### Basic Configuration
@@ -52,7 +68,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 +90,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
@@ -91,6 +111,9 @@ Magick.configure do
   audit_log enabled: true
   versioning enabled: true
   warn_on_deprecated enabled: true
+
+  # Enable Admin UI (optional)
+  admin_ui enabled: true
 end
 ```
 
@@ -383,7 +406,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 +449,189 @@ 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.
+
+#### ActiveRecord Adapter (Optional)
+
+The ActiveRecord adapter provides database-backed persistent storage for feature flags. It's useful when you want to:
+- Store feature flags in your application database
+- Use ActiveRecord models for feature management
+- Have a fallback storage layer
+- Work with PostgreSQL, MySQL, SQLite, or any ActiveRecord-supported database
+
+**Setup:**
+
+1. Generate the migration:
+   ```bash
+   rails generate magick:active_record
+   rails db:migrate
+   ```
+
+   **With UUID primary keys:**
+   ```bash
+   rails generate magick:active_record --uuid
+   ```
+
+2. Configure in `config/initializers/magick.rb`:
+   ```ruby
+   Magick.configure do
+     active_record # Uses default MagickFeature model
+     # Or specify a custom model:
+     # active_record model_class: YourCustomModel
+   end
+   ```
+
+The adapter automatically creates the `magick_features` table if it doesn't exist, but using the generator is recommended for production applications.
+
+**PostgreSQL Support:**
+
+The generator automatically detects PostgreSQL and uses `jsonb` for the `data` column, providing:
+- Better performance with native JSON queries
+- Native JSON indexing and querying capabilities
+- Type-safe JSON storage
+
+For other databases (MySQL, SQLite, etc.), it uses `text` with serialized JSON.
+
+**UUID Primary Keys:**
+
+When using the `--uuid` flag:
+- Creates table with `id: :uuid` instead of integer primary key
+- Enables `pgcrypto` extension for PostgreSQL (required for UUID generation)
+- Works with other databases using their native UUID support
+
+**Note:** The ActiveRecord adapter works as a fallback in the adapter chain: Memory → Redis → ActiveRecord. It's automatically included if ActiveRecord is available and configured.
+
+**Adapter Chain:**
+
+The adapter registry uses a fallback strategy:
+1. **Memory Adapter** (first) - Fast, in-memory lookups
+2. **Redis Adapter** (second) - Persistent, distributed storage
+3. **ActiveRecord Adapter** (third) - Database-backed fallback
+
+When a feature is requested:
+- First checks memory cache (fastest)
+- Falls back to Redis if not in memory
+- Falls back to ActiveRecord if Redis is unavailable or returns nil
+- Updates all adapters when features are modified
+
+This ensures maximum performance while maintaining persistence and reliability.
+
+### Admin UI
+
+Magick includes a web-based Admin UI for managing feature flags. It's a Rails Engine that provides a user-friendly interface for viewing, enabling, disabling, and configuring features.
+
+**Setup:**
+
+1. Enable Admin UI in `config/initializers/magick.rb`:
+
+```ruby
+Magick.configure do
+  admin_ui enabled: true
+end
+```
+
+2. Configure roles (optional) for targeting management:
+
+```ruby
+Magick::AdminUI.configure do |config|
+  config.available_roles = ['admin', 'user', 'manager', 'guest']
+end
+```
+
+3. Mount the engine in `config/routes.rb`:
+
+```ruby
+Rails.application.routes.draw do
+  # ... your other routes ...
+
+  # With authentication (recommended for production)
+  authenticate :admin_user do
+    mount Magick::AdminUI::Engine, at: '/magick'
+  end
+
+  # Or without authentication (development only)
+  # mount Magick::AdminUI::Engine, at: '/magick'
+end
+```
+
+**Access:**
+
+Once mounted, visit `/magick` in your browser to access the Admin UI.
+
+**Features:**
+
+- **Feature List**: View all registered features with their current status, type, and description
+- **Feature Details**: View detailed information about each feature including:
+  - Current value/status
+  - Targeting rules (users, groups, roles, percentages, etc.)
+  - Performance statistics (usage count, average duration)
+  - Feature metadata (type, default value, dependencies)
+- **Enable/Disable**: Quickly enable or disable features globally
+- **Targeting Management**: Configure targeting rules through a user-friendly interface:
+  - **Role Targeting**: Select roles from a configured list (checkboxes)
+  - **User Targeting**: Enter user IDs (comma-separated)
+  - **Visual Display**: See all active targeting rules with badges
+- **Edit Features**: Update feature values (boolean, string, number) directly from the UI
+- **Statistics**: View performance metrics and usage statistics for each feature
+
+**Targeting Management:**
+
+The Admin UI provides a comprehensive targeting interface:
+
+1. **Role Targeting**:
+   - Configure available roles via `Magick::AdminUI.configure`
+   - Select multiple roles using checkboxes
+   - Roles are automatically added/removed when checkboxes are toggled
+
+2. **User Targeting**:
+   - Enter user IDs as comma-separated values (e.g., `123, 456, 789`)
+   - Add or remove users dynamically
+   - Clear all user targeting by leaving the field empty
+
+3. **Visual Feedback**:
+   - All targeting rules are displayed as badges in the feature details view
+   - Easy to see which roles/users have access to each feature
+
+**Routes:**
+
+The Admin UI provides the following routes:
+
+- `GET /magick` - Feature list (index)
+- `GET /magick/features/:id` - Feature details
+- `GET /magick/features/:id/edit` - Edit feature
+- `PUT /magick/features/:id` - Update feature value
+- `PUT /magick/features/:id/enable` - Enable feature globally
+- `PUT /magick/features/:id/disable` - Disable feature globally
+- `PUT /magick/features/:id/enable_for_user` - Enable feature for specific user
+- `PUT /magick/features/:id/enable_for_role` - Enable feature for specific role
+- `PUT /magick/features/:id/disable_for_role` - Disable feature for specific role
+- `PUT /magick/features/:id/update_targeting` - Update targeting rules (roles and users)
+- `GET /magick/stats/:id` - View feature statistics
+
+**Security:**
+
+The Admin UI is a basic Rails Engine without built-in authentication. **You should add authentication/authorization** before mounting it in production. For example:
+
+```ruby
+# config/routes.rb
+Rails.application.routes.draw do
+  # Using Devise
+  authenticate :admin_user do
+    mount Magick::AdminUI::Engine, at: '/magick'
+  end
+
+  # Or using session-based authentication
+  constraints(->(request) { request.session[:user_id].present? && request.session[:admin] }) do
+    mount Magick::AdminUI::Engine, at: '/magick'
+  end
+end
+```
+
+Or use a before_action in your ApplicationController if you mount it at the application level.
+
+**Note:** The Admin UI is optional and only loaded when explicitly enabled in configuration. It requires Rails to be available.
 
 ### Feature Types
 

data/lib/generators/magick/active_record/active_record_generator.rb

@@ -0,0 +1,44 @@
+# frozen_string_literal: true
+
+module Magick
+  module Generators
+    class ActiveRecordGenerator < Rails::Generators::Base
+      include Rails::Generators::Migration
+
+      source_root File.expand_path('templates', __dir__)
+
+      desc 'Creates a migration for Magick feature flags table (ActiveRecord adapter)'
+      class_option :uuid, type: :boolean, default: false, desc: 'Use UUID as primary key'
+
+      def self.next_migration_number(dirname)
+        ActiveRecord::Generators::Base.next_migration_number(dirname)
+      end
+
+      def create_migration
+        unless defined?(::ActiveRecord::Base)
+          say 'ActiveRecord is not available. This generator requires ActiveRecord.', :red
+          exit 1
+        end
+
+        migration_number = self.class.next_migration_number('db/migrate')
+        @use_uuid = options[:uuid]
+        @is_postgresql = postgresql?
+        template 'create_magick_features.rb', "db/migrate/#{migration_number}_create_magick_features.rb"
+      end
+
+      private
+
+      def postgresql?
+        return false unless defined?(::ActiveRecord::Base)
+
+        begin
+          adapter = ActiveRecord::Base.connection.adapter_name.downcase
+          adapter == 'postgresql' || adapter == 'postgis'
+        rescue StandardError
+          # If we can't connect, check database.yml or default to false
+          false
+        end
+      end
+    end
+  end
+end

data/lib/generators/magick/active_record/templates/create_magick_features.rb

@@ -0,0 +1,20 @@
+# frozen_string_literal: true
+
+class CreateMagickFeatures < ActiveRecord::Migration[<%= ActiveRecord::Migration.current_version %>]
+  def change
+<% if @use_uuid -%>
+    enable_extension 'pgcrypto' if adapter_name == 'PostgreSQL'
+    create_table :magick_features, id: :uuid do |t|
+<% else -%>
+    create_table :magick_features do |t|
+<% end -%>
+      t.string :feature_name, null: false, index: { unique: true }
+<% if @is_postgresql -%>
+      t.jsonb :data
+<% else -%>
+      t.text :data
+<% end -%>
+      t.timestamps
+    end
+  end
+end

data/lib/magick/adapters/active_record.rb

@@ -0,0 +1,267 @@
+# frozen_string_literal: true
+
+module Magick
+  module Adapters
+    class ActiveRecord < Base
+      @table_created_mutex = Mutex.new
+      @table_created = false
+
+      def initialize(model_class: nil)
+        @model_class = model_class || default_model_class
+        ensure_table_exists
+      rescue StandardError => e
+        raise AdapterError, "Failed to initialize ActiveRecord adapter: #{e.message}"
+      end
+
+      def get(feature_name, key)
+        ensure_table_exists unless @model_class.table_exists?
+        feature_name_str = feature_name.to_s
+        record = @model_class.find_by(feature_name: feature_name_str)
+        return nil unless record
+
+        # Handle both Hash (from serialize) and Hash/JSON (from attribute :json)
+        data = record.data || {}
+        value = data.is_a?(Hash) ? data[key.to_s] : nil
+        deserialize_value(value)
+      rescue StandardError => e
+        # If table doesn't exist, try to create it and retry once
+        if e.message.include?('no such table') || e.message.include?("doesn't exist")
+          ensure_table_exists
+          retry
+        end
+        raise AdapterError, "Failed to get from ActiveRecord: #{e.message}"
+      end
+
+      def set(feature_name, key, value)
+        ensure_table_exists unless @model_class.table_exists?
+        feature_name_str = feature_name.to_s
+        retries = 5
+        begin
+          record = @model_class.find_or_initialize_by(feature_name: feature_name_str)
+          # Ensure data is a Hash (works for both serialize and attribute :json)
+          data = record.data || {}
+          data = {} unless data.is_a?(Hash)
+          data[key.to_s] = serialize_value(value)
+          record.data = data
+          # Use Time.now if Time.current is not available (for non-Rails environments)
+          record.updated_at = defined?(Time.current) ? Time.current : Time.now
+          record.save!
+        rescue ::ActiveRecord::StatementInvalid, ::ActiveRecord::ConnectionTimeoutError => e
+          # SQLite busy/locked errors - retry with exponential backoff
+          if (e.message.include?('database is locked') || e.message.include?('busy') || e.message.include?('timeout') || e.message.include?('no such table')) && retries > 0
+            retries -= 1
+            # If it's a "no such table" error, ensure table exists
+            if e.message.include?('no such table')
+              ensure_table_exists
+            end
+            sleep(0.01 * (6 - retries)) # Exponential backoff: 0.01, 0.02, 0.03, 0.04, 0.05
+            retry
+          end
+          raise AdapterError, "Failed to set in ActiveRecord: #{e.message}"
+        rescue StandardError => e
+          # If table doesn't exist, try to create it and retry once
+          if (e.message.include?('no such table') || e.message.include?("doesn't exist")) && retries > 0
+            retries -= 1
+            ensure_table_exists
+            sleep(0.01)
+            retry
+          end
+          raise AdapterError, "Failed to set in ActiveRecord: #{e.message}"
+        end
+      end
+
+      def delete(feature_name)
+        ensure_table_exists unless @model_class.table_exists?
+        feature_name_str = feature_name.to_s
+        retries = 5
+        begin
+          @model_class.where(feature_name: feature_name_str).destroy_all
+        rescue ::ActiveRecord::StatementInvalid, ::ActiveRecord::ConnectionTimeoutError => e
+          # SQLite busy/locked errors - retry with exponential backoff
+          if (e.message.include?('database is locked') || e.message.include?('busy') || e.message.include?('timeout') || e.message.include?('no such table')) && retries > 0
+            retries -= 1
+            # If it's a "no such table" error, ensure table exists
+            if e.message.include?('no such table')
+              ensure_table_exists
+            end
+            sleep(0.01 * (6 - retries)) # Exponential backoff: 0.01, 0.02, 0.03, 0.04, 0.05
+            retry
+          end
+          raise AdapterError, "Failed to delete from ActiveRecord: #{e.message}"
+        rescue StandardError => e
+          # If table doesn't exist, try to create it and retry once
+          if (e.message.include?('no such table') || e.message.include?("doesn't exist")) && retries > 0
+            retries -= 1
+            ensure_table_exists
+            sleep(0.01)
+            retry
+          end
+          raise AdapterError, "Failed to delete from ActiveRecord: #{e.message}"
+        end
+      end
+
+      def exists?(feature_name)
+        @model_class.exists?(feature_name: feature_name.to_s)
+      rescue StandardError => e
+        raise AdapterError, "Failed to check existence in ActiveRecord: #{e.message}"
+      end
+
+      def all_features
+        @model_class.pluck(:feature_name).uniq
+      rescue StandardError => e
+        raise AdapterError, "Failed to get all features from ActiveRecord: #{e.message}"
+      end
+
+      private
+
+      def default_model_class
+        return MagickFeature if defined?(MagickFeature)
+
+        # Create model class if it doesn't exist
+        create_model_class
+      end
+
+      def create_model_class
+        # Define the model class dynamically
+        # Use ::ActiveRecord::VERSION to access from global namespace
+        ar_major = ::ActiveRecord::VERSION::MAJOR
+        ar_minor = ::ActiveRecord::VERSION::MINOR
+        use_json = ar_major >= 8 || (ar_major == 7 && ar_minor >= 1)
+
+        Object.const_set('MagickFeature', Class.new(::ActiveRecord::Base) do
+          self.table_name = 'magick_features'
+
+          # ActiveRecord 8.1 changed serialize signature - it now only accepts one argument
+          # Use attribute :data, :json for ActiveRecord 7.1+ (including 8.1)
+          # Fall back to serialize for older versions
+          if use_json
+            # ActiveRecord 7.1+ and 8.x use attribute with type
+            attribute :data, :json, default: {}
+          else
+            # Older ActiveRecord versions use serialize
+            serialize :data, Hash
+          end
+
+          def self.table_exists?
+            connection.table_exists?(table_name)
+          end
+        end)
+      end
+
+      def ensure_table_exists
+        return if @model_class.table_exists?
+
+        # Use a non-blocking mutex to prevent deadlocks
+        mutex = self.class.instance_variable_get(:@table_created_mutex)
+        if mutex.try_lock
+          begin
+            # Double-check after acquiring lock
+            return if @model_class.table_exists?
+
+            create_table
+            self.class.instance_variable_set(:@table_created, true)
+          ensure
+            mutex.unlock
+          end
+        else
+          # Another thread is creating the table, wait for it to complete
+          # Use a longer timeout with exponential backoff to avoid hanging
+          20.times do |i|
+            sleep(0.01 * (i + 1)) # Exponential backoff: 0.01, 0.02, 0.03, ...
+            return if @model_class.table_exists?
+          end
+          # If we still don't have the table, try one more time
+          unless @model_class.table_exists?
+            # Last attempt: try to acquire lock and create
+            if mutex.try_lock
+              begin
+                return if @model_class.table_exists?
+                create_table
+                self.class.instance_variable_set(:@table_created, true)
+              ensure
+                mutex.unlock
+              end
+            end
+          end
+        end
+      rescue StandardError => e
+        # Don't raise if table exists now (might have been created by another thread)
+        return if @model_class.table_exists?
+        raise e
+      end
+
+      def create_table
+        connection = @model_class.connection
+        return if connection.table_exists?('magick_features')
+
+        connection.create_table :magick_features do |t|
+          t.string :feature_name, null: false, index: { unique: true }
+          t.text :data
+          t.timestamps
+        end
+      rescue StandardError => e
+        # Table might already exist or migration might be needed
+        # Check if table exists now (might have been created by another thread)
+        return if connection.table_exists?('magick_features')
+
+        warn "Magick: Could not create magick_features table: #{e.message}" if defined?(Rails) && Rails.env.development?
+        raise e if defined?(Rails) && Rails.env.test?
+      end
+
+      def serialize_value(value)
+        # For ActiveRecord 8.1+ with attribute :json, we can store booleans as-is
+        # For older versions with serialize, we convert to strings
+        ar_major = ::ActiveRecord::VERSION::MAJOR
+        ar_minor = ::ActiveRecord::VERSION::MINOR
+        use_json = ar_major >= 8 || (ar_major == 7 && ar_minor >= 1)
+
+        case value
+        when Hash, Array
+          value
+        when true
+          use_json ? true : 'true'
+        when false
+          use_json ? false : 'false'
+        else
+          value
+        end
+      end
+
+      def deserialize_value(value)
+        return nil if value.nil?
+
+        # For ActiveRecord 8.1+ with attribute :json, booleans are already booleans
+        # For older versions with serialize, we convert from strings
+        case value
+        when Hash
+          # JSON serialization converts symbol keys to strings
+          # Convert string keys back to symbols for consistency with input
+          symbolize_hash_keys(value)
+        when Array
+          # Recursively process array elements
+          value.map { |v| v.is_a?(Hash) ? symbolize_hash_keys(v) : v }
+        when 'true'
+          # String 'true' from older serialize - convert to boolean
+          true
+        when 'false'
+          # String 'false' from older serialize - convert to boolean
+          false
+        when true, false
+          # Already a boolean (from JSON attribute)
+          value
+        else
+          value
+        end
+      end
+
+      def symbolize_hash_keys(hash)
+        return hash unless hash.is_a?(Hash)
+
+        hash.each_with_object({}) do |(k, v), result|
+          key = k.is_a?(String) ? k.to_sym : k
+          result[key] = v.is_a?(Hash) ? symbolize_hash_keys(v) : (v.is_a?(Array) ? v.map { |item| item.is_a?(Hash) ? symbolize_hash_keys(item) : item } : v)
+        end
+      end
+    end
+  end
+end