magick-feature-flags 1.2.3 → 1.3.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: fc65d262824128014a4e5e631001687be36d698efbc1adc5f222685d96b10613
-  data.tar.gz: d2e15a3828b13071ee573a9c6356215e311012d16d55817a0fdb2aeee51a7172
+  metadata.gz: 046dc5815e415705073eff7b3619c90bfd09a4af59b74d4116a3b2c206d5572e
+  data.tar.gz: 97bd2be3b303a73fa464c87ebbc6456098003601d236072c10e9a483e52c50b2
 SHA512:
-  metadata.gz: 6a932f9c887525e88dfe8e6392803a90dee47a9891fb6fa04c2c18561b9203518442d8b46590a20d85b32a2c1d5d75005686f652ed24495b90747aca44e4e4ee
-  data.tar.gz: 40ac9092db1747cc50e79c94045ba80118274fcd198b57c70a6ad0c17e4b693578ae12f785d152d148684bf9b365e001a51b338174e47d2f1db2dcb5a74b830b
+  metadata.gz: 85d499e307729dfd4742ec0535f5edde63fb5dc2706ee8b1189dd63f8ed7f9c8c6d7a784d9a7f59e988f394fb92f41acc84c176a9544fb417c892586dd6444f2
+  data.tar.gz: 589515a83297e0d3ce02332afa309741533f1cf91fa556044b9a1f4f63a2d327248eba80c1727baa08ed5ed476db401530ddd21645eab3d7028624f97f6ee204

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,65 @@ 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
-feature = Magick[:button_color]
+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[: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 }
 ])
+```
+
+**Usage in your application:**
 
-variant = feature.get_variant
-# Returns 'blue', 'green', or 'red' based on weights
+```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
 ```
 
+**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 +732,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 +806,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?
@@ -267,6 +267,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)

data/lib/magick/version.rb

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