magick-feature-flags 1.2.3 → 1.3.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc65d262824128014a4e5e631001687be36d698efbc1adc5f222685d96b10613
-  data.tar.gz: d2e15a3828b13071ee573a9c6356215e311012d16d55817a0fdb2aeee51a7172
+  metadata.gz: a34f03026e8631bc2d29c0935cb98e472e7ed387fc4628edc357776423bfc2c5
+  data.tar.gz: d87af21843efb22d5dba60d342f3beb5fd807eb42f1b2948c82ae8dc3d6b67a2
 SHA512:
-  metadata.gz: 6a932f9c887525e88dfe8e6392803a90dee47a9891fb6fa04c2c18561b9203518442d8b46590a20d85b32a2c1d5d75005686f652ed24495b90747aca44e4e4ee
-  data.tar.gz: 40ac9092db1747cc50e79c94045ba80118274fcd198b57c70a6ad0c17e4b693578ae12f785d152d148684bf9b365e001a51b338174e47d2f1db2dcb5a74b830b
+  metadata.gz: '0296397245455dbecd448a2dab448b2209579f4c9c39a1e93b424e8f6982fe8a3f498140ac7af5f1127c70fc2cdaa3378194135afe2e55fe9254646a4c761e64'
+  data.tar.gz: 43e1ce6dcf51815f83ccf4440845d415f8d351e6a6038c8f7bcd0a294dfc0def6531a04a118119d66e71a64d7cfcc1607273eda0c181dfdf951c9ee61d4cfae7

data/README.md

@@ -5,6 +5,7 @@ A performant and memory-efficient feature toggle gem for Ruby and Rails applicat
 ## Features
 
 - **Multiple Feature Types**: Boolean, string, and number feature flags
+- **A/B Testing**: Built-in experiment support with deterministic, weighted variant assignment
 - **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)
@@ -359,6 +360,16 @@ string_feature :api_version, default: "v1", description: "API version"
 # Number features
 number_feature :max_results, default: 10, description: "Maximum results per page"
 
+# A/B test experiment
+experiment :checkout_button,
+  name: "Checkout Button",
+  description: "Button color experiment",
+  variants: [
+    { name: 'control', value: '#0066cc', weight: 50 },
+    { name: 'green', value: '#00cc66', weight: 30 },
+    { name: 'red', value: '#cc0000', weight: 20 }
+  ]
+
 # With status
 feature :experimental_feature,
   type: :boolean,
@@ -405,20 +416,91 @@ end
 
 ### Advanced Features
 
-#### Feature Variants (A/B Testing)
+#### A/B Testing (Experiments)
+
+Magick has built-in support for A/B testing with deterministic variant assignment. The same user always gets the same variant (based on MD5 hashing), ensuring consistent experiences.
+
+**Quick setup with DSL (`config/features.rb`):**
+
+```ruby
+experiment :checkout_button,
+  name: "Checkout Button Color",
+  description: "Test which button color converts better",
+  variants: [
+    { name: 'control', value: '#0066cc', weight: 50 },
+    { name: 'green',   value: '#00cc66', weight: 30 },
+    { name: 'red',     value: '#cc0000', weight: 20 }
+  ]
+```
+
+**Or set up programmatically:**
 
 ```ruby
-feature = Magick[:button_color]
+feature = Magick[:checkout_button]
 feature.set_variants([
-  { name: 'blue', value: '#0066cc', weight: 50 },
-  { name: 'green', value: '#00cc66', weight: 30 },
-  { name: 'red', value: '#cc0000', weight: 20 }
+  { name: 'control', value: '#0066cc', weight: 50 },
+  { name: 'green',   value: '#00cc66', weight: 30 },
+  { name: 'red',     value: '#cc0000', weight: 20 }
 ])
+```
 
-variant = feature.get_variant
-# Returns 'blue', 'green', or 'red' based on weights
+**Usage in your application:**
+
+```ruby
+# Get the variant name for a user (deterministic — same user always gets same variant)
+variant = Magick.variant(:checkout_button, user_id: current_user.id)
+# => "control", "green", or "red"
+
+# Get the variant value directly
+color = Magick.variant_value(:checkout_button, user_id: current_user.id)
+# => "#0066cc", "#00cc66", or "#cc0000"
+
+# Works with user objects too
+variant = Magick.variant(:checkout_button, user: current_user)
+
+# Use in views/controllers
+class CheckoutController < ApplicationController
+  def show
+    @button_color = Magick.variant_value(:checkout_button, user: current_user)
+    # Same user always sees the same color
+  end
+end
 ```
 
+**Experiments without a user (anonymous visitors):**
+
+For flows where there's no authenticated user yet (e.g., registration, landing pages), use any stable identifier as `user_id` — a session ID or a tracking cookie:
+
+```ruby
+class RegistrationController < ApplicationController
+  def new
+    cookies[:visitor_id] ||= SecureRandom.uuid
+    @variant = Magick.variant(:registration_flow, user_id: cookies[:visitor_id])
+  end
+end
+```
+
+The hashing just needs a consistent string. As long as the same visitor sends the same identifier, they get the same variant every time.
+
+**Safe to call on non-existent experiments:**
+
+```ruby
+Magick.variant(:nonexistent, user_id: 123)  # => nil
+Magick.variant_value(:nonexistent, user_id: 123)  # => nil
+```
+
+**Important — changing weights may shift users:**
+
+You can change variant weights at any time via the Admin UI or code, and changes take effect immediately across all adapters. However, changing weights alters the bucket boundaries, which means some users may be reassigned to a different variant after the update. Magick does not persist individual user-to-variant assignments — assignment is computed on the fly from the hash. If your experiment requires that users never shift variants mid-experiment, you should persist the assignment externally (e.g., store `user_id → variant` in a database table on first exposure).
+
+**How it works:**
+- Variants are assigned using a deterministic MD5 hash of `feature_name + user_id`
+- The same user always gets the same variant across sessions and requests
+- Weights control the distribution (e.g., 50/30/20 means ~50% control, ~30% green, ~20% red)
+- If no `user_id` is provided, falls back to random assignment (useful for anonymous users)
+- Experiments are boolean features with variants — they work with all targeting and exclusion rules
+- Manage variants through the Admin UI with visual weight distribution
+
 #### Feature Dependencies
 
 ```ruby
@@ -676,6 +758,7 @@ Once mounted, visit `/magick` in your browser to access the Admin UI.
   - **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
+- **A/B Test Management**: Create and manage experiment variants with visual weight distribution
 - **Statistics**: View performance metrics and usage statistics for each feature
 - **Feature Grouping**: Organize features into groups for easier management and filtering
 - **Filtering**: Filter features by group, name, or description
@@ -749,6 +832,7 @@ The Admin UI provides the following routes:
 - `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)
+- `PUT /magick/features/:id/update_variants` - Update A/B test variants
 - `GET /magick/stats/:id` - View feature statistics
 
 **Security:**

data/app/controllers/magick/adminui/features_controller.rb

@@ -7,7 +7,7 @@ module Magick
       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]
+      before_action :set_feature, only: %i[show edit update enable disable enable_for_user enable_for_role disable_for_role update_targeting update_variants]
 
       # Make route helpers available in views via magick_admin_ui helper
       helper_method :magick_admin_ui, :available_roles, :available_tags, :partially_enabled?
@@ -80,8 +80,11 @@ module Magick
       end
 
       def enable
-        @feature.enable
-        redirect_to magick_admin_ui.features_path, notice: 'Feature enabled'
+        if @feature.enable
+          redirect_to magick_admin_ui.features_path, notice: 'Feature enabled'
+        else
+          redirect_to magick_admin_ui.feature_path(@feature.name), alert: 'Cannot enable feature — its dependencies must be enabled first'
+        end
       end
 
       def disable
@@ -267,6 +270,35 @@ module Magick
         redirect_to magick_admin_ui.feature_path(@feature.name), alert: "Error updating targeting: #{e.message}"
       end
 
+      def update_variants
+        variants_data = []
+
+        if params[:variants].present?
+          params[:variants].each do |_index, variant_params|
+            next if variant_params[:name].blank?
+
+            variants_data << {
+              name: variant_params[:name].strip,
+              value: variant_params[:value].to_s.strip,
+              weight: (variant_params[:weight].presence || 0).to_f
+            }
+          end
+        end
+
+        if variants_data.any?
+          @feature.set_variants(variants_data)
+        else
+          # Clear variants if all removed
+          @feature.instance_variable_get(:@targeting)&.delete(:variants)
+          @feature.save_targeting
+        end
+
+        redirect_to magick_admin_ui.feature_path(@feature.name), notice: 'Variants updated successfully'
+      rescue StandardError => e
+        Rails.logger.error "Magick: Error updating variants: #{e.message}" if defined?(Rails)
+        redirect_to magick_admin_ui.feature_path(@feature.name), alert: "Error updating variants: #{e.message}"
+      end
+
       private
 
       def authenticate_admin!

data/app/views/layouts/application.html.erb

@@ -1291,6 +1291,50 @@
       searchInput.addEventListener('input', filterFeatures);
       if (groupSelect) groupSelect.addEventListener('change', filterFeatures);
     })();
+
+    // Variants management
+    (function() {
+      const addBtn = document.getElementById('add_variant_btn');
+      const container = document.getElementById('variants_container');
+      if (!addBtn || !container) return;
+
+      let variantIndex = container.querySelectorAll('.variant-row').length;
+
+      addBtn.addEventListener('click', function() {
+        const noMsg = document.getElementById('no_variants_message');
+        if (noMsg) noMsg.remove();
+
+        const row = document.createElement('div');
+        row.className = 'variant-row';
+        row.setAttribute('data-variant-index', variantIndex);
+        row.innerHTML = '<div style="display: grid; grid-template-columns: 1fr 1fr auto auto; gap: 12px; align-items: end; margin-bottom: 12px; padding: 12px; background: var(--color-bg); border: 1px solid var(--color-border); border-radius: var(--radius-sm);">' +
+          '<div><label class="form-label" style="margin-bottom: 4px; font-size: 12px;">Name</label>' +
+          '<input type="text" name="variants[' + variantIndex + '][name]" placeholder="e.g., control" required></div>' +
+          '<div><label class="form-label" style="margin-bottom: 4px; font-size: 12px;">Value</label>' +
+          '<input type="text" name="variants[' + variantIndex + '][value]" placeholder="e.g., #0066cc"></div>' +
+          '<div><label class="form-label" style="margin-bottom: 4px; font-size: 12px;">Weight</label>' +
+          '<input type="number" name="variants[' + variantIndex + '][weight]" value="0" min="0" max="1000" style="width: 80px;"></div>' +
+          '<div style="padding-bottom: 2px;"><button type="button" class="btn btn-ghost btn-sm remove-variant-btn" onclick="this.closest(\'.variant-row\').remove(); updateVariantIndices();" title="Remove variant" style="color: var(--color-danger);">&times;</button></div>' +
+          '</div>';
+        container.appendChild(row);
+        variantIndex++;
+      });
+    })();
+
+    function updateVariantIndices() {
+      const container = document.getElementById('variants_container');
+      if (!container) return;
+      const rows = container.querySelectorAll('.variant-row');
+      rows.forEach(function(row, i) {
+        row.setAttribute('data-variant-index', i);
+        row.querySelectorAll('input').forEach(function(input) {
+          const name = input.getAttribute('name');
+          if (name) {
+            input.setAttribute('name', name.replace(/variants\[\d+\]/, 'variants[' + i + ']'));
+          }
+        });
+      });
+    }
   </script>
 </body>
 </html>

data/app/views/magick/adminui/features/edit.html.erb

@@ -278,3 +278,55 @@
     <% end %>
   </div>
 </div>
+
+<div class="card" id="variants-section">
+  <div class="card-header">
+    <h2>A/B Test Variants</h2>
+  </div>
+  <div class="card-body">
+    <%= form_with url: magick_admin_ui.update_variants_feature_path(@feature.name), method: :put, local: true do |f| %>
+      <p style="font-size: 13px; color: var(--color-text-secondary); margin-bottom: 16px;">Define experiment variants with weights. Users are deterministically assigned to variants based on their user ID.</p>
+
+      <% current_variants = (@feature.instance_variable_get(:@targeting) || {})[:variants] || [] %>
+
+      <div id="variants_container">
+        <% if current_variants.any? %>
+          <% current_variants.each_with_index do |variant, index| %>
+            <div class="variant-row" data-variant-index="<%= index %>">
+              <div style="display: grid; grid-template-columns: 1fr 1fr auto auto; gap: 12px; align-items: end; margin-bottom: 12px; padding: 12px; background: var(--color-bg); border: 1px solid var(--color-border); border-radius: var(--radius-sm);">
+                <div>
+                  <label class="form-label" style="margin-bottom: 4px; font-size: 12px;">Name</label>
+                  <input type="text" name="variants[<%= index %>][name]" value="<%= variant[:name] || variant['name'] %>" placeholder="e.g., control" required>
+                </div>
+                <div>
+                  <label class="form-label" style="margin-bottom: 4px; font-size: 12px;">Value</label>
+                  <input type="text" name="variants[<%= index %>][value]" value="<%= variant[:value] || variant['value'] %>" placeholder="e.g., #0066cc">
+                </div>
+                <div>
+                  <label class="form-label" style="margin-bottom: 4px; font-size: 12px;">Weight</label>
+                  <input type="number" name="variants[<%= index %>][weight]" value="<%= (variant[:weight] || variant['weight'] || 0).to_i %>" min="0" max="1000" style="width: 80px;">
+                </div>
+                <div style="padding-bottom: 2px;">
+                  <button type="button" class="btn btn-ghost btn-sm remove-variant-btn" onclick="this.closest('.variant-row').remove(); updateVariantIndices();" title="Remove variant" style="color: var(--color-danger);">&times;</button>
+                </div>
+              </div>
+            </div>
+          <% end %>
+        <% else %>
+          <p id="no_variants_message" style="color: var(--color-text-muted); font-size: 13px; margin-bottom: 16px;">No variants configured. Add variants to create an A/B test.</p>
+        <% end %>
+      </div>
+
+      <div style="margin-bottom: 20px;">
+        <button type="button" class="btn btn-secondary btn-sm" id="add_variant_btn">+ Add Variant</button>
+      </div>
+
+      <div style="padding-top: 20px; border-top: 1px solid var(--color-border);">
+        <div class="btn-group">
+          <%= submit_tag 'Save Variants', class: 'btn btn-primary' %>
+          <a href="<%= magick_admin_ui.feature_path(@feature.name) %>" class="btn btn-secondary">Cancel</a>
+        </div>
+      </div>
+    <% end %>
+  </div>
+</div>

data/app/views/magick/adminui/features/index.html.erb

@@ -76,7 +76,9 @@
             <td data-label="Value">
               <% if feature.type == :boolean %>
                 <% targeting = feature.instance_variable_get(:@targeting) || {} %>
-                <% if targeting.any? %>
+                <% if targeting[:variants].present? %>
+                  <span class="toggle-indicator" style="background: var(--color-primary); color: #fff;">A/B</span>
+                <% elsif targeting.any? %>
                   <span class="toggle-indicator toggle-partial">PARTIAL</span>
                 <% elsif feature.enabled? %>
                   <span class="toggle-indicator toggle-on">ON</span>

data/app/views/magick/adminui/features/show.html.erb

@@ -138,6 +138,52 @@
   </div>
 </div>
 
+<% variants = (@feature.instance_variable_get(:@targeting) || {})[:variants] %>
+<% if variants.present? && variants.any? %>
+  <div class="card">
+    <div class="card-header">
+      <h2>A/B Test Variants</h2>
+      <a href="<%= magick_admin_ui.edit_feature_path(@feature.name) %>#variants-section" class="link-subtle">Manage</a>
+    </div>
+    <div class="card-body" style="padding: 0;">
+      <table>
+        <thead>
+          <tr>
+            <th>Variant</th>
+            <th>Value</th>
+            <th style="text-align: right;">Weight</th>
+            <th style="text-align: right;">Distribution</th>
+          </tr>
+        </thead>
+        <tbody>
+          <% total_weight = variants.sum { |v| (v[:weight] || v['weight'] || 0).to_f } %>
+          <% variants.each do |variant| %>
+            <% v_name = variant[:name] || variant['name'] %>
+            <% v_value = variant[:value] || variant['value'] %>
+            <% v_weight = (variant[:weight] || variant['weight'] || 0).to_f %>
+            <% percentage = total_weight > 0 ? (v_weight / total_weight * 100).round(1) : 0 %>
+            <tr>
+              <td>
+                <span style="font-weight: 600;"><%= v_name %></span>
+              </td>
+              <td><code><%= v_value %></code></td>
+              <td style="text-align: right; font-variant-numeric: tabular-nums;"><%= v_weight.to_i %></td>
+              <td style="text-align: right;">
+                <div style="display: flex; align-items: center; justify-content: flex-end; gap: 8px;">
+                  <div style="width: 80px; height: 6px; background: var(--color-border); border-radius: 3px; overflow: hidden;">
+                    <div style="width: <%= percentage %>%; height: 100%; background: var(--color-primary); border-radius: 3px;"></div>
+                  </div>
+                  <span style="font-size: 12px; font-weight: 500; color: var(--color-text-secondary); min-width: 40px; text-align: right;"><%= percentage %>%</span>
+                </div>
+              </td>
+            </tr>
+          <% end %>
+        </tbody>
+      </table>
+    </div>
+  </div>
+<% end %>
+
 <% dependencies = @feature.dependencies %>
 <% if dependencies.any? %>
   <div class="card">

data/config/routes.rb

@@ -10,6 +10,7 @@ Magick::AdminUI::Engine.routes.draw do
       put :enable_for_role
       put :disable_for_role
       put :update_targeting
+      put :update_variants
     end
   end
   resources :stats, only: [:show]

data/lib/magick/dsl.rb

@@ -19,6 +19,15 @@ module Magick
       Magick.register_feature(name, type: :number, default_value: default, **options)
     end
 
+    def experiment(name, variants:, **options)
+      feature = Magick.register_feature(name, type: :boolean, default_value: false, **options)
+      variant_data = variants.map do |v|
+        { name: v[:name].to_s, value: v[:value], weight: (v[:weight] || 0).to_f }
+      end
+      feature.set_variants(variant_data)
+      feature
+    end
+
     # Targeting DSL methods
     def enable_for_user(feature_name, user_id)
       Magick[feature_name].enable_for_user(user_id)

data/lib/magick/feature.rb

@@ -442,34 +442,38 @@ module Magick
       return nil unless targeting[:variants]
 
       variants = targeting[:variants]
-      selected_variant = if variants.length == 1
-                           variants.first[:name]
-                         else
-                           # Weighted random selection
-                           total_weight = variants.sum { |v| v[:weight] || 0 }
-                           if total_weight.zero?
-                             variants.first[:name]
-                           else
-                             random = rand(total_weight)
-                             current = 0
-                             selected = nil
-                             variants.each do |variant|
-                               current += variant[:weight] || 0
-                               if random < current
-                                 selected = variant[:name]
-                                 break
-                               end
-                             end
-                             selected || variants.first[:name]
-                           end
-                         end
+      return nil if variants.empty?
+      return variants.first[:name] if variants.length == 1
+
+      total_weight = variants.sum { |v| v[:weight] || 0 }
+      return variants.first[:name] if total_weight.zero?
+
+      # Deterministic assignment: use MD5 hash of feature_name + user_id
+      # This ensures the same user always gets the same variant
+      user_id = context[:user_id] || context[:user]&.respond_to?(:id) && context[:user].id
+      if user_id
+        hash = Digest::MD5.hexdigest("#{name}:variant:#{user_id}")
+        bucket = hash[0..7].to_i(16) % total_weight
+      else
+        # No user context — fall back to random (e.g., anonymous requests)
+        bucket = rand(total_weight)
+      end
 
-      # Rails 8+ event
-      if defined?(Magick::Rails::Events) && Magick::Rails::Events.rails8?
-        Magick::Rails::Events.variant_selected(name, variant_name: selected_variant, context: context)
+      current = 0
+      variants.each do |variant|
+        current += (variant[:weight] || 0)
+        return variant[:name] if bucket < current
       end
 
-      selected_variant
+      variants.last[:name]
+    end
+
+    def get_variant_value(context = {})
+      variant_name = get_variant(context)
+      return nil unless variant_name
+
+      variant = targeting[:variants]&.find { |v| v[:name] == variant_name }
+      variant&.dig(:value)
     end
 
     def set_value(value, user_id: nil)
@@ -512,20 +516,16 @@ module Magick
     end
 
     def enable(user_id: nil)
-      # Check if this feature is a dependency of any disabled features
-      # If a main feature that depends on this feature is disabled, prevent enabling this dependency
-      # Dependencies cannot be enabled until the main feature is enabled
-      dependent_features = find_dependent_features
-      disabled_dependents = dependent_features.select do |dep_feature_name|
-        dep_feature = Magick.features[dep_feature_name.to_s] || Magick[dep_feature_name]
-        # Check if the dependent feature (main feature) is disabled
-        dep_feature && !dep_feature.enabled?
-      end
+      # Check that all of this feature's own dependencies are enabled
+      # e.g. if checkout depends on payments, checkout can't be enabled until payments is
+      deps = @dependencies || []
+      unless deps.empty?
+        disabled_deps = deps.select do |dep_name|
+          dep_feature = Magick.features[dep_name.to_s] || Magick[dep_name]
+          dep_feature && !dep_feature.enabled?
+        end
 
-      unless disabled_dependents.empty?
-        # Return false if any main feature that depends on this feature is disabled
-        # This prevents enabling a dependency when the main feature is disabled
-        return false
+        return false unless disabled_deps.empty?
       end
 
       # Clear all targeting to enable globally
@@ -984,13 +984,12 @@ module Magick
     end
 
     def disable_dependent_features(user_id: nil)
-      # Cascade-disable this feature's own dependencies (downstream sub-features).
-      # e.g. if A depends on B, disabling A also disables B.
-      # But disabling B does NOT cascade up to A.
-      deps = @dependencies || []
-      return if deps.empty?
+      # Cascade-disable features that depend ON this feature.
+      # e.g. if checkout depends on payments, disabling payments also disables checkout.
+      dependents = find_dependent_features
+      return if dependents.empty?
 
-      deps.each do |dep_name|
+      dependents.each do |dep_name|
         dep_feature = Magick.features[dep_name.to_s] || Magick[dep_name]
         next unless dep_feature
 

data/lib/magick/version.rb

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

data/lib/magick.rb

@@ -150,6 +150,16 @@ module Magick
       !enabled?(feature_name, context)
     end
 
+    def variant(feature_name, context = {})
+      feature = features[feature_name.to_s] || self[feature_name]
+      feature.get_variant(context)
+    end
+
+    def variant_value(feature_name, context = {})
+      feature = features[feature_name.to_s] || self[feature_name]
+      feature.get_variant_value(context)
+    end
+
     def exists?(feature_name)
       features.key?(feature_name.to_s) || (adapter_registry || default_adapter_registry).exists?(feature_name)
     end

metadata

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