magick-feature-flags 1.1.3 → 1.2.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: e896cf3753f151fb2f1082a231c9af82095e3caea7716642a9f535e60d36e9e4
-  data.tar.gz: 24992a605474319bd831fbd60a6d955ba05de266d7419f60065fef2a2d32d2d1
+  metadata.gz: 7f87e02cd09ce5fb4e837f66c5117d2ca709918cd4bcc1f1fe808ceaafe7e049
+  data.tar.gz: 5ed85473443dd9e065c2a7298030a361b1fe965376c68085b0355d57124c04e2
 SHA512:
-  metadata.gz: ba376fb1fea1613bd7841fd4a56b8ed30833ab91c6563fad61abde4127caba802330b9bf14b9b0a52094addd7c58b92cb85d30af2b78c283647121de69fee19c
-  data.tar.gz: cfe7ad50afee3b0c7b192a1bb8a5b035834672f21d29627f67a3eda2939330880806686c655ccc6d17d4875c7d6fd029fc1f1732ee68562cc520373a2d54190f
+  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

@@ -208,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

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/feature.rb

@@ -109,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])
 
@@ -264,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
@@ -719,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]]
@@ -963,9 +1022,52 @@ 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)
       case type
-      when :date_range, :custom_attributes, :complex_conditions, :variants
+      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

data/lib/magick/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Magick
-  VERSION = '1.1.3'
+  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.3
+  version: 1.2.0
 platform: ruby
 authors:
 - Andrew Lobanov