subflag-rails 0.5.1 → 0.6.1

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56034c2de3a47fbbb96f97aa9f1149c87c58bc1558b50a7520db7b07a93c3e85
-  data.tar.gz: dc818a9034753adfa51b2cd810a5affe7c3cb9e30ff9943c67e0df01d0c6cf66
+  metadata.gz: 67d1ea6917f303ab8a78a5ffa90a9d5cfc3d6c30b7c13cd039f89cdd20365402
+  data.tar.gz: f8e5269abd5ef6ec77d8a4288b8a5ce91d114dcf96905d56c7aab5db368a1833
 SHA512:
-  metadata.gz: ca26926074b168811199ae8fe3e065843073dcbae20667a9951a641bfb0e02e0d30e11ed16ae7376a1cf75c5f8ffc46e8012929494ba7d142a80260732ee4e0c
-  data.tar.gz: c8b0af027aa0cf5d01bdac26b2a7681c05fa818bfe2a92d1d178a3c8cd67cc0d94f555b495b132593009c2272ad3b3b60b61b6b93087109321c99bffdef446a3
+  metadata.gz: 7ba49356001ccb5676eccb9417e54bafc382bbc5ff0af19ad95a7567f4ac7a1fc1c2bd50505fad9d40ca4528e26e18c71900b423de149f91395c41686ce30b17
+  data.tar.gz: 18a47da01c9c44396faf29d4fe2234e4132f2479ff247aa5764f09fe0b27b361ceec05c65057f8cb8e5380ed2b9a319aa8a6fb7499882aa52ee38dcf7f0dcfab

data/CHANGELOG.md

@@ -2,6 +2,22 @@
 
 All notable changes to this project will be documented in this file.
 
+## [0.6.0] - 2025-12-15
+
+### Added
+
+- **Percentage rollouts for ActiveRecord backend**: Gradually roll out features to a percentage of users
+  - Deterministic assignment using MurmurHash3 (same user always gets the same result)
+  - Combine with segment conditions (e.g., "50% of pro users")
+  - Admin UI: percentage field in targeting rules editor
+- New dependency: `murmurhash3` gem for consistent hashing
+
+### Changed
+
+- `TargetingEngine.evaluate` now accepts optional `flag_key:` parameter (required for percentage rollouts)
+- Targeting rules validation now accepts `percentage` as alternative to `conditions`
+- Admin UI: targeting rules now saved via fetch API with proper redirect handling
+
 ## [0.5.1] - 2025-12-15
 
 ### Fixed

data/README.md

@@ -482,6 +482,18 @@ Subflag::Rails::Flag.create!(
 }
 ```
 
+**Percentage rollouts:**
+
+Gradually roll out features to a percentage of users using the Admin UI:
+
+1. Create or edit a flag at `/subflag`
+2. Add a targeting rule with a **percentage** (0-100)
+3. Optionally combine with conditions (e.g., "50% of pro users")
+
+Assignment is deterministic — the same user always gets the same result for the same flag.
+
+> **Note:** Percentage rollouts require `targeting_key` in your user context (typically the user ID).
+
 **How evaluation works:**
 
 1. Flag disabled? → return code default

data/app/views/subflag/rails/flags/edit.html.erb

@@ -49,6 +49,8 @@
   .rule-header { display: flex; justify-content: space-between; align-items: center; margin-bottom: 10px; }
   .rule-value { display: flex; gap: 10px; align-items: center; margin-bottom: 10px; }
   .rule-value input { width: 200px; }
+  .rule-percentage { display: flex; gap: 10px; align-items: center; margin-bottom: 10px; }
+  .rule-percentage input { width: 80px; }
   .rule-logic { margin-bottom: 10px; }
   .rule-logic label { margin-right: 15px; }
   .condition { display: flex; gap: 8px; align-items: center; margin-bottom: 8px; }
@@ -94,6 +96,8 @@
   function renderRule(rule, ruleIndex) {
     const conditions = rule.conditions?.conditions || [];
     const logicType = rule.conditions?.type || "AND";
+    const percentage = rule.percentage;
+    const hasConditions = conditions.length > 0;
 
     return `
       <div class="rule" data-rule-index="${ruleIndex}">
@@ -105,7 +109,13 @@
           <label>Return value:</label>
           <input type="text" value="${escapeHtml(rule.value || '')}" onchange="updateRuleValue(${ruleIndex}, this.value)" placeholder="value when matched">
         </div>
-        <div class="rule-logic">
+        <div class="rule-percentage">
+          <label>Percentage rollout:</label>
+          <input type="number" min="0" max="100" value="${percentage ?? ''}" onchange="updateRulePercentage(${ruleIndex}, this.value)" placeholder="">
+          <span>% of users</span>
+          <small style="color: #666;">(leave empty to match all)</small>
+        </div>
+        <div class="rule-logic" ${!hasConditions && percentage ? 'style="opacity: 0.5;"' : ''}>
           <label><input type="radio" name="logic-${ruleIndex}" value="AND" ${logicType === 'AND' ? 'checked' : ''} onchange="updateLogic(${ruleIndex}, 'AND')"> ALL match</label>
           <label><input type="radio" name="logic-${ruleIndex}" value="OR" ${logicType === 'OR' ? 'checked' : ''} onchange="updateLogic(${ruleIndex}, 'OR')"> ANY match</label>
         </div>
@@ -113,6 +123,7 @@
           ${conditions.map((c, cIndex) => renderCondition(c, ruleIndex, cIndex)).join("")}
         </div>
         <button type="button" class="btn btn-sm" onclick="addCondition(${ruleIndex})">+ Add Condition</button>
+        <small style="display: block; margin-top: 5px; color: #666;">${hasConditions && percentage ? 'User must match conditions AND be in percentage' : ''}</small>
       </div>
     `;
   }
@@ -139,7 +150,7 @@
   function addRule() {
     rules.push({
       value: "",
-      conditions: { type: "AND", conditions: [{ attribute: "", operator: "EQUALS", value: "" }] }
+      conditions: { type: "AND", conditions: [] }
     });
     renderRules();
   }
@@ -153,6 +164,15 @@
     rules[ruleIndex].value = value;
   }
 
+  function updateRulePercentage(ruleIndex, value) {
+    if (value === '' || value === null) {
+      delete rules[ruleIndex].percentage;
+    } else {
+      rules[ruleIndex].percentage = parseInt(value, 10);
+    }
+    renderRules();
+  }
+
   function updateLogic(ruleIndex, type) {
     rules[ruleIndex].conditions.type = type;
   }
@@ -180,55 +200,42 @@
   }
 
   function saveRules() {
-    const form = document.createElement("form");
-    form.method = "POST";
-    form.action = "<%= flag_path(@flag) %>";
-
-    const methodInput = document.createElement("input");
-    methodInput.type = "hidden";
-    methodInput.name = "_method";
-    methodInput.value = "PATCH";
-    form.appendChild(methodInput);
-
-    const csrfInput = document.createElement("input");
-    csrfInput.type = "hidden";
-    csrfInput.name = "<%= request_forgery_protection_token %>";
-    csrfInput.value = "<%= form_authenticity_token %>";
-    form.appendChild(csrfInput);
-
-    // Send all flag params to preserve other fields
-    const keyInput = document.createElement("input");
-    keyInput.type = "hidden";
-    keyInput.name = "flag[key]";
-    keyInput.value = "<%= @flag.key %>";
-    form.appendChild(keyInput);
-
-    const valueInput = document.createElement("input");
-    valueInput.type = "hidden";
-    valueInput.name = "flag[value]";
-    valueInput.value = "<%= @flag.value %>";
-    form.appendChild(valueInput);
-
-    const typeInput = document.createElement("input");
-    typeInput.type = "hidden";
-    typeInput.name = "flag[value_type]";
-    typeInput.value = "<%= @flag.value_type %>";
-    form.appendChild(typeInput);
-
-    const enabledInput = document.createElement("input");
-    enabledInput.type = "hidden";
-    enabledInput.name = "flag[enabled]";
-    enabledInput.value = "<%= @flag.enabled? %>";
-    form.appendChild(enabledInput);
-
-    const rulesInput = document.createElement("input");
-    rulesInput.type = "hidden";
-    rulesInput.name = "flag[targeting_rules]";
-    rulesInput.value = JSON.stringify(rules);
-    form.appendChild(rulesInput);
-
-    document.body.appendChild(form);
-    form.submit();
+    // Clean up rules before saving - filter out invalid rules
+    const cleanedRules = rules.map(rule => {
+      const cleaned = { value: rule.value };
+      if (rule.percentage !== undefined && rule.percentage !== null && rule.percentage !== '') {
+        cleaned.percentage = rule.percentage;
+      }
+      const conditions = rule.conditions?.conditions?.filter(c => c.attribute && c.operator);
+      if (conditions && conditions.length > 0) {
+        cleaned.conditions = { type: rule.conditions?.type || "AND", conditions };
+      }
+      return cleaned;
+    }).filter(rule => rule.conditions || rule.percentage !== undefined);
+
+    const formData = new FormData();
+    formData.append("flag[key]", "<%= @flag.key %>");
+    formData.append("flag[value]", "<%= @flag.value %>");
+    formData.append("flag[value_type]", "<%= @flag.value_type %>");
+    formData.append("flag[enabled]", "<%= @flag.enabled? %>");
+    formData.append("flag[targeting_rules]", JSON.stringify(cleanedRules));
+
+    fetch("<%= flag_path(@flag) %>", {
+      method: "PATCH",
+      headers: {
+        "X-CSRF-Token": "<%= form_authenticity_token %>",
+      },
+      body: formData,
+      redirect: "manual"
+    }).then(response => {
+      if (response.ok || response.type === "opaqueredirect" || response.status === 302) {
+        window.location.reload();
+      } else {
+        alert("Failed to save rules: " + response.status);
+      }
+    }).catch(err => {
+      alert("Error saving rules: " + err.message);
+    });
   }
 
   function escapeHtml(str) {

data/lib/subflag/rails/models/flag.rb

@@ -70,7 +70,7 @@ module Subflag
       def evaluate(context: nil, expected_type: nil)
         rules = parsed_targeting_rules
         raw_value = if rules.present? && context.present?
-                      matched = TargetingEngine.evaluate(rules, context)
+                      matched = TargetingEngine.evaluate(rules, context, flag_key: key)
                       matched || value
                     else
                       value
@@ -146,7 +146,20 @@ module Subflag
 
           rule = rule.transform_keys(&:to_s)
           errors.add(:targeting_rules, "rule #{index} must have a 'value' key") unless rule.key?("value")
-          errors.add(:targeting_rules, "rule #{index} must have a 'conditions' key") unless rule.key?("conditions")
+
+          has_conditions = rule.key?("conditions") && rule["conditions"].present?
+          has_percentage = rule.key?("percentage")
+
+          unless has_conditions || has_percentage
+            errors.add(:targeting_rules, "rule #{index} must have 'conditions' and/or 'percentage'")
+          end
+
+          if has_percentage
+            pct = rule["percentage"]
+            unless pct.is_a?(Numeric) && pct >= 0 && pct <= 100
+              errors.add(:targeting_rules, "rule #{index} percentage must be a number between 0 and 100")
+            end
+          end
         end
       end
     end

data/lib/subflag/rails/targeting_engine.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require "murmurhash3"
+
 module Subflag
   module Rails
     # Evaluates targeting rules against evaluation contexts.
@@ -34,25 +36,56 @@ module Subflag
         #
         # @param rules [Array<Hash>, nil] Array of targeting rules with values
         # @param context [Hash, nil] Evaluation context with attributes
+        # @param flag_key [String, nil] The flag key (required for percentage rollouts)
         # @return [String, nil] The matched rule's value, or nil if no match
-        def evaluate(rules, context)
+        def evaluate(rules, context, flag_key: nil)
           return nil if rules.nil? || rules.empty?
           return nil if context.nil? || context.empty?
 
-          # Normalize context keys to strings for comparison
           normalized_context = normalize_context(context)
+          targeting_key = extract_targeting_key(normalized_context)
 
           rules.each do |rule|
             rule = rule.transform_keys(&:to_s)
             conditions = rule["conditions"]
-            next unless conditions
+            percentage = rule["percentage"]
+
+            segment_matches = if conditions.nil? || conditions.empty?
+                                true
+                              else
+                                evaluate_rule(conditions, normalized_context)
+                              end
+
+            next unless segment_matches
 
-            if evaluate_rule(conditions, normalized_context)
-              return rule["value"]
+            if percentage
+              next unless targeting_key && flag_key
+              next unless evaluate_percentage(targeting_key, flag_key, percentage)
             end
+
+            return rule["value"]
           end
 
-          nil # No rules matched
+          nil
+        end
+
+        # Evaluate percentage rollout using MurmurHash3
+        #
+        # @param targeting_key [String] Unique identifier for the context
+        # @param flag_key [String] The flag being evaluated
+        # @param percentage [Integer] Target percentage (0-100)
+        # @return [Boolean] true if context falls within percentage
+        def evaluate_percentage(targeting_key, flag_key, percentage)
+          percentage = percentage.to_i
+          return false if percentage <= 0
+          return true if percentage >= 100
+
+          hash_input = "#{targeting_key}:#{flag_key}"
+          hash_bytes = MurmurHash3::V128.str_hash(hash_input)
+          hash_code = [hash_bytes[0]].pack("L").unpack1("l")
+          bucket = hash_code.abs % 100
+
+          bucket < percentage
         end
 
         private
@@ -63,6 +96,10 @@ module Subflag
           end
         end
 
+        def extract_targeting_key(context)
+          context["targeting_key"] || context["targetingKey"]
+        end
+
         # Evaluate an AND/OR rule block
         def evaluate_rule(rule, context)
           rule = rule.transform_keys(&:to_s)

data/lib/subflag/rails/version.rb

@@ -2,6 +2,6 @@
 
 module Subflag
   module Rails
-    VERSION = "0.5.1"
+    VERSION = "0.6.1"
   end
 end

metadata

@@ -1,7 +1,7 @@
 --- !ruby/object:Gem::Specification
 name: subflag-rails
 version: !ruby/object:Gem::Version
-  version: 0.5.1
+  version: 0.6.1
 platform: ruby
 authors:
 - Subflag
@@ -58,6 +58,20 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
+- !ruby/object:Gem::Dependency
+  name: murmurhash3
+  requirement: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.6
+  type: :runtime
+  prerelease: false
+  version_requirements: !ruby/object:Gem::Requirement
+    requirements:
+    - - "~>"
+      - !ruby/object:Gem::Version
+        version: 0.1.6
 - !ruby/object:Gem::Dependency
   name: bundler
   requirement: !ruby/object:Gem::Requirement