magick-feature-flags 1.1.2 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 7ce19a872aa305d47f9bd4fa75023829cb2a63aafa86809260049cd09e11e696
-  data.tar.gz: 8a1bed262b71e443384ba60505a2af92ae5f4a1399112730887ec89f6379097a
+  metadata.gz: 7f87e02cd09ce5fb4e837f66c5117d2ca709918cd4bcc1f1fe808ceaafe7e049
+  data.tar.gz: 5ed85473443dd9e065c2a7298030a361b1fe965376c68085b0355d57124c04e2
 SHA512:
-  metadata.gz: 441203a6279d12d0ef44043e2145fc591e74cfe849ba186f2c5f6baebc617f78af6a2a6499cfc2c12e24fc0832640ccfd044436a3030bfbbf8d2549f9ff616bb
-  data.tar.gz: 4370e495deae46281c40f68d81ca1f388fd962297104c6409af7d91a21d6af7eafa5632ec3535c0dc4bcd570b428dd6286b0135a4b2f0c128a2c5e40b8248021
+  metadata.gz: 29402326b70df322e48ae798571ee500a12eafc964545ed0e1a2f15e56bce6197254084b3c9eb75cadd22a61e2583c74fbbb41d0c50f478f733e561d8c41917f
+  data.tar.gz: a8d84d507bab0fd1e02eb3583830c059f3cdd5d475a137bfe952a85194fc66f2e5a8f8b548096722664ae0a92325087d265b17aa3f1d12e6d3f3f5176c212ca5

data/README.md

@@ -6,6 +6,7 @@ A performant and memory-efficient feature toggle gem for Ruby and Rails applicat
 
 - **Multiple Feature Types**: Boolean, string, and number feature flags
 - **Flexible Targeting**: Enable features for specific users, groups, roles, tags, or percentages
+- **Exclusions**: Exclude specific users, groups, roles, tags, or IPs — exclusions always take priority over inclusions
 - **Dual Backend**: Memory adapter (fast) with Redis fallback (persistent)
 - **Rails Integration**: Seamless integration with Rails, including request store caching
 - **DSL Support**: Define features in a Ruby DSL file (`config/features.rb`)
@@ -193,6 +194,76 @@ feature.enable_for_ip_addresses('192.168.1.0/24', '10.0.0.1')
 feature.enable_for_custom_attribute(:subscription_tier, ['premium', 'enterprise'])
 ```
 
+### Feature Exclusions
+
+Exclusions let you block specific users, groups, roles, tags, or IP addresses from a feature — even if they match an inclusion rule. **Exclusions always take priority over inclusions.**
+
+```ruby
+feature = Magick[:new_dashboard]
+
+# Exclude specific users
+feature.exclude_user(456)
+feature.exclude_user(789)
+
+# Exclude specific tags
+feature.exclude_tag('legacy_tier')
+feature.exclude_tag('banned')
+
+# Exclude specific groups
+feature.exclude_group('suspended_users')
+
+# Exclude specific roles
+feature.exclude_role('guest')
+
+# Exclude IP addresses (supports CIDR notation)
+feature.exclude_ip_addresses(['10.0.0.0/8', '192.168.1.100'])
+
+# Remove exclusions
+feature.remove_user_exclusion(456)
+feature.remove_tag_exclusion('legacy_tier')
+feature.remove_group_exclusion('suspended_users')
+feature.remove_role_exclusion('guest')
+feature.remove_ip_exclusion  # Removes all IP exclusions
+```
+
+**Exclusions win over inclusions:**
+
+```ruby
+feature = Magick[:premium_features]
+feature.enable  # Enabled globally for everyone
+
+feature.exclude_user(123)
+Magick.enabled?(:premium_features, user_id: 123)  # => false (excluded)
+Magick.enabled?(:premium_features, user_id: 456)  # => true  (not excluded)
+
+# Even percentage targeting is overridden
+feature.enable_percentage_of_users(100)  # 100% of users
+feature.exclude_user(123)
+Magick.enabled?(:premium_features, user_id: 123)  # => false (still excluded)
+```
+
+**Exclusions in DSL (`config/features.rb`):**
+
+```ruby
+boolean_feature :new_dashboard, default: true
+
+# Exclude problematic users
+exclude_user :new_dashboard, 'user_123'
+exclude_user :new_dashboard, 'user_456'
+
+# Exclude legacy tiers
+exclude_tag :new_dashboard, 'legacy_tier'
+
+# Exclude groups
+exclude_group :new_dashboard, 'banned_users'
+
+# Exclude roles
+exclude_role :new_dashboard, 'suspended'
+
+# Exclude IPs
+exclude_ip_addresses :new_dashboard, '10.0.0.0/8'
+```
+
 ### Checking Feature Enablement with Objects
 
 You can check if a feature is enabled for an object (like a User model) and its fields:
@@ -258,6 +329,12 @@ result = feature.enable_for_role('admin')  # => true
 result = feature.enable_for_tag('premium') # => true
 result = feature.enable_percentage_of_users(25)  # => true
 result = feature.set_value(true)          # => true
+
+# Exclusion methods also return true
+result = feature.exclude_user(456)         # => true
+result = feature.exclude_tag('banned')     # => true
+result = feature.exclude_group('blocked')  # => true
+result = feature.exclude_role('guest')     # => true
 ```
 
 ### DSL Configuration
@@ -303,6 +380,13 @@ boolean_feature :premium_feature,
 
 # Add dependencies after feature definition
 add_dependency(:another_feature, :required_feature)
+
+# Exclusions - block specific users/groups/roles/tags
+exclude_user :new_dashboard, 'user_123'
+exclude_tag :new_dashboard, 'legacy_tier'
+exclude_group :new_dashboard, 'banned_users'
+exclude_role :new_dashboard, 'suspended'
+exclude_ip_addresses :new_dashboard, '10.0.0.0/8'
 ```
 
 ### In Controllers
@@ -443,8 +527,8 @@ end
 
 Magick uses a dual-adapter strategy:
 
-1. **Memory Adapter**: Fast, in-memory storage with TTL support
-2. **Redis Adapter**: Persistent storage for distributed systems (optional)
+1. **Memory Adapter**: Fast, in-memory storage with TTL support and JSON serialization
+2. **Redis Adapter**: Persistent storage for distributed systems (optional), uses SCAN instead of KEYS and pipelined bulk operations
 
 The registry automatically falls back from memory to Redis if a feature isn't found in memory. When features are updated:
 - Both adapters are updated simultaneously
@@ -589,6 +673,7 @@ Once mounted, visit `/magick` in your browser to access the Admin UI.
   - **Role Targeting**: Select roles from a configured list (checkboxes)
   - **Tag Targeting**: Select tags from a dynamically loaded list (checkboxes)
   - **User Targeting**: Enter user IDs (comma-separated)
+  - **Exclusions**: Exclude users, roles, and tags from a feature (exclusions override inclusions)
   - **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
@@ -641,7 +726,12 @@ The Admin UI provides a comprehensive targeting interface:
    - Add or remove users dynamically
    - Clear all user targeting by leaving the field empty
 
-4. **Visual Feedback**:
+4. **Exclusion Targeting**:
+   - Exclude specific users (comma-separated IDs), roles, and tags
+   - Exclusions always take priority over inclusions
+   - Managed through the same targeting form
+
+5. **Visual Feedback**:
    - All targeting rules are displayed as badges in the feature details view
    - Easy to see which roles/tags/users have access to each feature
 
@@ -663,7 +753,27 @@ The Admin UI provides the following routes:
 
 **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:
+The Admin UI includes a built-in authentication hook via `require_role`. Configure it to gate access:
+
+```ruby
+# config/initializers/magick.rb
+Rails.application.config.after_initialize do
+  Magick::AdminUI.configure do |config|
+    # Option 1: Lambda-based authentication (recommended)
+    config.require_role = ->(controller) {
+      # Return true to allow, false to deny (returns 403 Forbidden)
+      controller.current_user&.admin?
+    }
+
+    # Option 2: Check for a specific role
+    config.require_role = ->(controller) {
+      controller.current_user&.role == 'admin'
+    }
+  end
+end
+```
+
+You can also gate access at the routing level:
 
 ```ruby
 # config/routes.rb
@@ -680,8 +790,6 @@ Rails.application.routes.draw do
 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/app/controllers/magick/adminui/features_controller.rb

@@ -6,6 +6,7 @@ module Magick
       # Include route helpers so views can use magick_admin_ui.* helpers
       include Magick::AdminUI::Engine.routes.url_helpers
       layout 'application'
+      before_action :authenticate_admin!
       before_action :set_feature, only: %i[show edit update enable disable enable_for_user enable_for_role disable_for_role update_targeting]
 
       # Make route helpers available in views via magick_admin_ui helper
@@ -207,6 +208,49 @@ module Magick
           @feature.disable_percentage_of_requests if current_targeting[:percentage_requests]
         end
 
+        # Handle excluded user IDs
+        if targeting_params[:excluded_user_ids].present?
+          excluded_user_ids = targeting_params[:excluded_user_ids].split(',').map(&:strip).reject(&:blank?)
+          current_excluded_users = current_targeting[:excluded_users].is_a?(Array) ? current_targeting[:excluded_users] : (current_targeting[:excluded_users] ? [current_targeting[:excluded_users]] : [])
+
+          (current_excluded_users - excluded_user_ids).each do |user_id|
+            @feature.remove_user_exclusion(user_id) if user_id.present?
+          end
+
+          (excluded_user_ids - current_excluded_users).each do |user_id|
+            @feature.exclude_user(user_id) if user_id.present?
+          end
+        elsif targeting_params.key?(:excluded_user_ids) && targeting_params[:excluded_user_ids].blank?
+          current_excluded_users = current_targeting[:excluded_users].is_a?(Array) ? current_targeting[:excluded_users] : (current_targeting[:excluded_users] ? [current_targeting[:excluded_users]] : [])
+          current_excluded_users.each do |user_id|
+            @feature.remove_user_exclusion(user_id) if user_id.present?
+          end
+        end
+
+        # Handle excluded roles
+        current_excluded_roles = current_targeting[:excluded_roles].is_a?(Array) ? current_targeting[:excluded_roles] : (current_targeting[:excluded_roles] ? [current_targeting[:excluded_roles]] : [])
+        selected_excluded_roles = Array(targeting_params[:excluded_roles]).reject(&:blank?)
+
+        (current_excluded_roles - selected_excluded_roles).each do |role|
+          @feature.remove_role_exclusion(role) if role.present?
+        end
+
+        (selected_excluded_roles - current_excluded_roles).each do |role|
+          @feature.exclude_role(role) if role.present?
+        end
+
+        # Handle excluded tags
+        current_excluded_tags = current_targeting[:excluded_tags].is_a?(Array) ? current_targeting[:excluded_tags] : (current_targeting[:excluded_tags] ? [current_targeting[:excluded_tags]] : [])
+        selected_excluded_tags = Array(targeting_params[:excluded_tags]).reject(&:blank?)
+
+        (current_excluded_tags - selected_excluded_tags).each do |tag|
+          @feature.remove_tag_exclusion(tag) if tag.present?
+        end
+
+        (selected_excluded_tags - current_excluded_tags).each do |tag|
+          @feature.exclude_tag(tag) if tag.present?
+        end
+
         # After all targeting updates, ensure we're using the registered feature instance
         # and reload it to get the latest state from adapter
         feature_name = @feature.name.to_s
@@ -225,6 +269,18 @@ module Magick
 
       private
 
+      def authenticate_admin!
+        return unless Magick::AdminUI.config.require_role
+
+        auth_callback = Magick::AdminUI.config.require_role
+        if auth_callback.respond_to?(:call)
+          unless auth_callback.call(self)
+            head :forbidden
+            nil
+          end
+        end
+      end
+
       def set_feature
         feature_name = params[:id].to_s
         @feature = Magick.features[feature_name] || Magick[feature_name]

data/lib/magick/adapters/active_record.rb

@@ -5,6 +5,10 @@ module Magick
     class ActiveRecord < Base
       def initialize(model_class: nil)
         @model_class = model_class || default_model_class
+        # Cache AR version check once at init time (hot path optimization)
+        ar_major = ::ActiveRecord::VERSION::MAJOR
+        ar_minor = ::ActiveRecord::VERSION::MINOR
+        @use_json = ar_major >= 8 || (ar_major == 7 && ar_minor >= 1)
         # Verify table exists - raise clear error if it doesn't
         unless @model_class.table_exists?
           raise AdapterError, "Table 'magick_features' does not exist. Please run: rails generate magick:active_record && rails db:migrate"
@@ -30,20 +34,18 @@ module Magick
         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!
+          @model_class.transaction do
+            record = @model_class.lock.find_or_create_by!(feature_name: feature_name_str)
+            data = record.data || {}
+            data = {} unless data.is_a?(Hash)
+            data[key.to_s] = serialize_value(value)
+            record.update!(data: data, updated_at: defined?(Time.current) ? Time.current : Time.now)
+          end
         rescue ::ActiveRecord::StatementInvalid, ::ActiveRecord::ConnectionTimeoutError => e
-          # SQLite busy/locked errors - retry with exponential backoff
+          # SQLite busy/locked errors - retry with linear backoff
           if (e.message.include?('database is locked') || e.message.include?('busy') || e.message.include?('timeout')) && retries > 0
             retries -= 1
-            sleep(0.01 * (6 - retries)) # Exponential backoff: 0.01, 0.02, 0.03, 0.04, 0.05
+            sleep(0.01 * (6 - retries))
             retry
           end
           raise AdapterError, "Failed to set in ActiveRecord: #{e.message}"
@@ -97,9 +99,8 @@ module Magick
       end
 
       def load_all_features_data
-        records = @model_class.all
         result = {}
-        records.each do |record|
+        @model_class.find_each do |record|
           data = record.data || {}
           next unless data.is_a?(Hash)
 
@@ -118,15 +119,15 @@ module Magick
         feature_name_str = feature_name.to_s
         retries = 5
         begin
-          record = @model_class.find_or_initialize_by(feature_name: feature_name_str)
-          existing_data = record.data || {}
-          existing_data = {} unless existing_data.is_a?(Hash)
-          data_hash.each do |key, value|
-            existing_data[key.to_s] = serialize_value(value)
+          @model_class.transaction do
+            record = @model_class.lock.find_or_create_by!(feature_name: feature_name_str)
+            existing_data = record.data || {}
+            existing_data = {} unless existing_data.is_a?(Hash)
+            data_hash.each do |key, value|
+              existing_data[key.to_s] = serialize_value(value)
+            end
+            record.update!(data: existing_data, updated_at: defined?(Time.current) ? Time.current : Time.now)
           end
-          record.data = existing_data
-          record.updated_at = defined?(Time.current) ? Time.current : Time.now
-          record.save!
         rescue ::ActiveRecord::StatementInvalid, ::ActiveRecord::ConnectionTimeoutError => e
           if (e.message.include?('database is locked') || e.message.include?('busy') || e.message.include?('timeout')) && retries > 0
             retries -= 1
@@ -176,19 +177,13 @@ module Magick
       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'
+          @use_json ? true : 'true'
         when false
-          use_json ? false : 'false'
+          @use_json ? false : 'false'
         else
           value
         end

data/lib/magick/adapters/memory.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Magick
   module Adapters
     class Memory < Base
@@ -134,7 +136,7 @@ module Magick
       def serialize_value(value)
         case value
         when Hash, Array
-          Marshal.dump(value)
+          JSON.generate(value)
         else
           value
         end
@@ -145,10 +147,14 @@ module Magick
 
         case value
         when String
-          # Try to unmarshal if it's a serialized hash/array
-          begin
-            Marshal.load(value)
-          rescue StandardError
+          # Only attempt JSON parse on strings that look like JSON objects/arrays
+          if value.start_with?('{', '[')
+            begin
+              JSON.parse(value)
+            rescue JSON::ParserError
+              value
+            end
+          else
             value
           end
         else

data/lib/magick/adapters/redis.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'json'
+
 module Magick
   module Adapters
     class Redis < Base
@@ -37,8 +39,7 @@ module Magick
       end
 
       def all_features
-        pattern = "#{namespace}:*"
-        keys = redis.keys(pattern)
+        keys = scan_keys
         keys.map { |key| key.sub("#{namespace}:", '') }
       rescue StandardError => e
         raise AdapterError, "Failed to get all features from Redis: #{e.message}"
@@ -56,14 +57,18 @@ module Magick
       end
 
       def load_all_features_data
-        pattern = "#{namespace}:*"
-        keys = redis.keys(pattern)
+        keys = scan_keys
         return {} if keys.empty?
 
+        # Pipeline all HGETALL calls to avoid N+1 round-trips
+        raw_results = redis.pipelined do |pipeline|
+          keys.each { |key| pipeline.hgetall(key) }
+        end
+
         result = {}
-        keys.each do |key|
+        keys.each_with_index do |key, idx|
           feature_name = key.sub("#{namespace}:", '')
-          raw = redis.hgetall(key)
+          raw = raw_results[idx]
           next if raw.nil? || raw.empty?
 
           feature_data = {}
@@ -89,10 +94,28 @@ module Magick
         raise AdapterError, "Failed to set all data in Redis: #{e.message}"
       end
 
+      # Public accessor for the underlying Redis client
+      def client
+        @redis
+      end
+
       private
 
       attr_reader :redis, :namespace
 
+      # Use SCAN instead of KEYS to avoid blocking Redis
+      def scan_keys
+        pattern = "#{namespace}:*"
+        keys = []
+        cursor = '0'
+        loop do
+          cursor, batch = redis.scan(cursor, match: pattern, count: 100)
+          keys.concat(batch)
+          break if cursor == '0'
+        end
+        keys
+      end
+
       def key_for(feature_name)
         "#{namespace}:#{feature_name}"
       end
@@ -109,7 +132,7 @@ module Magick
       def serialize_value(value)
         case value
         when Hash, Array
-          Marshal.dump(value)
+          JSON.generate(value)
         when true
           'true'
         when false
@@ -122,17 +145,16 @@ module Magick
       def deserialize_value(value)
         return nil if value.nil?
 
-        # Try to unmarshal if it's a serialized hash/array
-        if value.is_a?(String) && value.start_with?("\x04\x08")
-          begin
-            Marshal.load(value)
-          rescue StandardError
-            value
-          end
-        elsif value == 'true'
+        if value == 'true'
           true
         elsif value == 'false'
           false
+        elsif value.is_a?(String) && value.start_with?('{', '[')
+          begin
+            JSON.parse(value)
+          rescue JSON::ParserError
+            value
+          end
         else
           value
         end

data/lib/magick/adapters/registry.rb

@@ -266,7 +266,7 @@ module Magick
       def redis_client
         return nil unless redis_adapter
 
-        redis_adapter.instance_variable_get(:@redis)
+        redis_adapter.client
       end
 
       # Publish cache invalidation message to Redis Pub/Sub (without deleting local memory cache)
@@ -276,7 +276,7 @@ module Magick
         return unless redis_adapter
 
         begin
-          redis_client = redis_adapter.instance_variable_get(:@redis)
+          redis_client = redis_adapter.client
           redis_client&.publish(CACHE_INVALIDATION_CHANNEL, feature_name.to_s)
         rescue StandardError => e
           # Silently fail - cache invalidation is best effort
@@ -299,6 +299,9 @@ module Magick
       # Check if a feature was recently written by this process
       def local_write?(feature_name_str)
         @reload_mutex.synchronize do
+          # Periodic cleanup of stale entries to prevent unbounded growth
+          cleanup_stale_tracking_entries
+
           wrote_at = @local_writes[feature_name_str]
           return false unless wrote_at
 
@@ -311,6 +314,16 @@ module Magick
         end
       end
 
+      # Clean up stale entries from tracking hashes (called under mutex)
+      def cleanup_stale_tracking_entries
+        now = Time.now.to_f
+        return if @last_tracking_cleanup && (now - @last_tracking_cleanup) < 60.0
+
+        @last_tracking_cleanup = now
+        @local_writes.delete_if { |_, wrote_at| (now - wrote_at) >= LOCAL_WRITE_TTL }
+        @last_reload_times.delete_if { |_, reload_at| (now - reload_at) >= 10.0 }
+      end
+
       # Start a background thread to listen for cache invalidation messages
       def start_cache_invalidation_subscriber
         return unless redis_adapter && defined?(Thread)
@@ -320,7 +333,7 @@ module Magick
         return if defined?(Rails) && Rails.env.test?
 
         @subscriber_thread = Thread.new do
-          redis_client = redis_adapter.instance_variable_get(:@redis)
+          redis_client = redis_adapter.client
           return unless redis_client
 
           begin

data/lib/magick/dsl.rb

@@ -58,6 +58,27 @@ module Magick
       Magick[feature_name].enable_for_custom_attribute(attribute_name, values, operator: operator)
     end
 
+    # Exclusion DSL methods
+    def exclude_user(feature_name, user_id)
+      Magick[feature_name].exclude_user(user_id)
+    end
+
+    def exclude_tag(feature_name, tag_name)
+      Magick[feature_name].exclude_tag(tag_name)
+    end
+
+    def exclude_group(feature_name, group_name)
+      Magick[feature_name].exclude_group(group_name)
+    end
+
+    def exclude_role(feature_name, role_name)
+      Magick[feature_name].exclude_role(role_name)
+    end
+
+    def exclude_ip_addresses(feature_name, *ip_addresses)
+      Magick[feature_name].exclude_ip_addresses(ip_addresses)
+    end
+
     def set_variants(feature_name, variants)
       Magick[feature_name].set_variants(variants)
     end

data/lib/magick/export_import.rb

@@ -75,7 +75,7 @@ module Magick
 
       # Rails 8+ event
       if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
-        Magick::Rails::Events.imported(format: format, feature_count: features.length)
+        Magick::Rails::Events.imported(format: :json, feature_count: features.length)
       end
 
       features

data/lib/magick/feature.rb

@@ -1,6 +1,7 @@
 # frozen_string_literal: true
 
 require 'digest'
+require 'time'
 require_relative '../magick/feature_variant'
 
 module Magick
@@ -89,16 +90,17 @@ module Magick
     end
 
     def check_enabled(context = {})
+      # Dup context to avoid mutating the caller's hash
+      context = context.dup
+
       # Extract context from user object if provided
       # This allows Magick.enabled?(:feature, user: player) to work
       if context[:user]
-        extracted = extract_context_from_object(context[:user])
+        extracted = extract_context_from_object(context.delete(:user))
         # Merge extracted context, but don't override explicit values already in context
         extracted.each do |key, value|
           context[key] = value unless context.key?(key)
         end
-        # Remove :user key after extraction to avoid confusion
-        context.delete(:user)
       end
 
       # Fast path: check status first
@@ -107,6 +109,9 @@ module Magick
 
       # Fast path: skip targeting checks if targeting is empty (most common case)
       unless @_targeting_empty
+        # Check exclusions FIRST — exclusions always take priority over inclusions
+        return false if excluded?(context)
+
         # Check date/time range targeting
         return false if targeting[:date_range] && !date_range_active?(targeting[:date_range])
 
@@ -262,6 +267,58 @@ module Magick
       true
     end
 
+    # --- Exclusion methods ---
+
+    def exclude_user(user_id)
+      enable_targeting(:excluded_users, user_id)
+      true
+    end
+
+    def remove_user_exclusion(user_id)
+      disable_targeting(:excluded_users, user_id)
+      true
+    end
+
+    def exclude_tag(tag_name)
+      enable_targeting(:excluded_tags, tag_name)
+      true
+    end
+
+    def remove_tag_exclusion(tag_name)
+      disable_targeting(:excluded_tags, tag_name)
+      true
+    end
+
+    def exclude_group(group_name)
+      enable_targeting(:excluded_groups, group_name)
+      true
+    end
+
+    def remove_group_exclusion(group_name)
+      disable_targeting(:excluded_groups, group_name)
+      true
+    end
+
+    def exclude_role(role_name)
+      enable_targeting(:excluded_roles, role_name)
+      true
+    end
+
+    def remove_role_exclusion(role_name)
+      disable_targeting(:excluded_roles, role_name)
+      true
+    end
+
+    def exclude_ip_addresses(ip_addresses)
+      enable_targeting(:excluded_ip_addresses, Array(ip_addresses))
+      true
+    end
+
+    def remove_ip_exclusion
+      disable_targeting(:excluded_ip_addresses)
+      true
+    end
+
     def enable_percentage_of_users(percentage)
       @targeting[:percentage_users] = percentage.to_f
       save_targeting
@@ -717,6 +774,10 @@ module Magick
       # Normalize targeting keys (handle both string and symbol keys)
       target = targeting.transform_keys(&:to_sym)
 
+      # If only exclusion keys exist (no inclusion targeting), treat as globally enabled
+      inclusion_keys = target.keys.reject { |k| k.to_s.start_with?('excluded_') }
+      return true if inclusion_keys.empty?
+
       # Check user targeting
       if context[:user_id] && target[:user]
         user_list = target[:user].is_a?(Array) ? target[:user] : [target[:user]]
@@ -780,7 +841,7 @@ module Magick
       ip_list.any? do |ip_str|
         IPAddr.new(ip_str).include?(client_ip)
       end
-    rescue IPAddr::InvalidAddressError
+    rescue IPAddr::InvalidAddressError, ArgumentError
       false
     end
 
@@ -819,8 +880,7 @@ module Magick
       conditions = complex_config[:conditions] || complex_config['conditions'] || []
       operator = (complex_config[:operator] || complex_config['operator'] || :and).to_sym
 
-      results = conditions.map do |condition|
-        # Each condition is a hash with type and params
+      evaluate_condition = lambda do |condition|
         condition_type = (condition[:type] || condition['type']).to_sym
         condition_params = condition[:params] || condition['params'] || {}
 
@@ -845,9 +905,9 @@ module Magick
 
       case operator
       when :and, :all
-        results.all?
+        conditions.all?(&evaluate_condition)
       when :or, :any
-        results.any?
+        conditions.any?(&evaluate_condition)
       else
         false
       end
@@ -962,9 +1022,63 @@ module Magick
       dependent_features
     end
 
+    def excluded?(context)
+      target = targeting.transform_keys(&:to_sym)
+
+      # Check excluded users
+      if context[:user_id] && target[:excluded_users]
+        excluded_list = target[:excluded_users].is_a?(Array) ? target[:excluded_users] : [target[:excluded_users]]
+        return true if excluded_list.include?(context[:user_id].to_s)
+      end
+
+      # Check excluded groups
+      if context[:group] && target[:excluded_groups]
+        excluded_list = target[:excluded_groups].is_a?(Array) ? target[:excluded_groups] : [target[:excluded_groups]]
+        return true if excluded_list.include?(context[:group].to_s)
+      end
+
+      # Check excluded roles
+      if context[:role] && target[:excluded_roles]
+        excluded_list = target[:excluded_roles].is_a?(Array) ? target[:excluded_roles] : [target[:excluded_roles]]
+        return true if excluded_list.include?(context[:role].to_s)
+      end
+
+      # Check excluded tags
+      if context[:tags] && target[:excluded_tags]
+        context_tags = Array(context[:tags]).map(&:to_s)
+        excluded_tags = target[:excluded_tags].is_a?(Array) ? target[:excluded_tags].map(&:to_s) : [target[:excluded_tags].to_s]
+        return true if (context_tags & excluded_tags).any?
+      end
+
+      # Check excluded IP addresses
+      if context[:ip_address] && target[:excluded_ip_addresses]
+        begin
+          require 'ipaddr'
+          excluded_ips = Array(target[:excluded_ip_addresses])
+          client_ip = IPAddr.new(context[:ip_address])
+          return true if excluded_ips.any? { |ip_str| IPAddr.new(ip_str).include?(client_ip) }
+        rescue IPAddr::InvalidAddressError, ArgumentError
+          # Invalid IP, not excluded
+        end
+      end
+
+      false
+    end
+
     def enable_targeting(type, value)
-      @targeting[type] ||= []
-      @targeting[type] << value.to_s unless @targeting[type].include?(value.to_s)
+      case type
+      when :date_range, :custom_attributes, :complex_conditions, :variants, :excluded_ip_addresses
+        # These types store structured data directly (Hash or Array of Hashes)
+        @targeting[type] = value
+      when :percentage_users, :percentage_requests
+        # Numeric types store a single value
+        @targeting[type] = value.to_f
+      else
+        # Array-based types (user, group, role, tag, ip_address)
+        @targeting[type] ||= []
+        str_value = value.to_s
+        @targeting[type] << str_value unless @targeting[type].include?(str_value)
+      end
       save_targeting
 
       # Rails 8+ event

data/lib/magick/targeting/complex.rb

@@ -11,13 +11,11 @@ module Magick
       def matches?(context)
         return false if @conditions.empty?
 
-        results = @conditions.map { |condition| condition.matches?(context) }
-
         case @operator
         when :and, :all
-          results.all?
+          @conditions.all? { |condition| condition.matches?(context) }
         when :or, :any
-          results.any?
+          @conditions.any? { |condition| condition.matches?(context) }
         else
           false
         end

data/lib/magick/targeting/custom_attribute.rb

@@ -7,6 +7,10 @@ module Magick
         @attribute_name = attribute_name.to_sym
         @values = Array(values)
         @operator = operator.to_sym
+
+        if %i[greater_than gt less_than lt].include?(@operator) && @values.empty?
+          raise ArgumentError, "#{@operator} operator requires at least one value"
+        end
       end
 
       def matches?(context)

data/lib/magick/targeting/date_range.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'time'
+
 module Magick
   module Targeting
     class DateRange < Base

data/lib/magick/targeting/ip_address.rb

@@ -14,7 +14,7 @@ module Magick
 
         client_ip = IPAddr.new(context[:ip_address])
         @ip_addresses.any? { |ip| ip.include?(client_ip) }
-      rescue IPAddr::InvalidAddressError
+      rescue IPAddr::InvalidAddressError, ArgumentError
         false
       end
     end

data/lib/magick/version.rb

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

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: magick-feature-flags
 version: !ruby/object:Gem::Version
-  version: 1.1.2
+  version: 1.2.0
 platform: ruby
 authors:
 - Andrew Lobanov