subflag-rails 0.5.1 → 0.6.0

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 56034c2de3a47fbbb96f97aa9f1149c87c58bc1558b50a7520db7b07a93c3e85
-  data.tar.gz: dc818a9034753adfa51b2cd810a5affe7c3cb9e30ff9943c67e0df01d0c6cf66
+  metadata.gz: 474015cc849b73a4360fa11418161fbc78c6bbc163596b5b9add7e45929b6db4
+  data.tar.gz: 25f595010b6722d107b0604774ac089386e9d3ced39d7fef72411964a310140c
 SHA512:
-  metadata.gz: ca26926074b168811199ae8fe3e065843073dcbae20667a9951a641bfb0e02e0d30e11ed16ae7376a1cf75c5f8ffc46e8012929494ba7d142a80260732ee4e0c
-  data.tar.gz: c8b0af027aa0cf5d01bdac26b2a7681c05fa818bfe2a92d1d178a3c8cd67cc0d94f555b495b132593009c2272ad3b3b60b61b6b93087109321c99bffdef446a3
+  metadata.gz: afbe39727f8e70a3273b77e49bf8127debc459487b4d01bc14693c682082592b11fd3506388a8db2bd5021e9bbb914767e19f279a56a56a30c114fe79f10b0f2
+  data.tar.gz: f124c9b3103ff13453615be92dfe7639fabfeb042d514bc4232b5a73e8fa1dcbe812e4d0fb418c45a35c33ac0e71753958d37cff01c6742ff991a408e637946f

data/CHANGELOG.md

@@ -2,6 +2,21 @@
 
 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")
+  - Configure via Admin UI or targeting rules JSON
+- 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`
+
 ## [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/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.0"
   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.0
 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