subflag-rails 0.4.0 → 0.5.1

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

@@ -2,27 +2,47 @@
 
 module Subflag
   module Rails
-    # ActiveRecord model for storing feature flags in your database
+    # ActiveRecord model for storing feature flags in your database.
     #
-    # @example Create a boolean flag
+    # Supports targeting rules to show different values to different users.
+    # Perfect for internal testing before wider rollout.
+    #
+    # @example Simple flag (everyone gets the same value)
     #   Subflag::Rails::Flag.create!(
     #     key: "new-checkout",
     #     value: "true",
     #     value_type: "boolean"
     #   )
     #
-    # @example Create an integer flag
+    # @example Flag with targeting rules (internal team gets different value)
     #   Subflag::Rails::Flag.create!(
-    #     key: "max-projects",
-    #     value: "100",
-    #     value_type: "integer"
+    #     key: "new-dashboard",
+    #     value: "false",
+    #     value_type: "boolean",
+    #     targeting_rules: [
+    #       {
+    #         "value" => "true",
+    #         "conditions" => {
+    #           "type" => "OR",
+    #           "conditions" => [
+    #             { "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@company.com" },
+    #             { "attribute" => "role", "operator" => "IN", "value" => ["admin", "developer", "qa"] }
+    #           ]
+    #         }
+    #       }
+    #     ]
     #   )
     #
-    # @example Create a JSON object flag
+    # @example Progressive rollout (first match wins)
     #   Subflag::Rails::Flag.create!(
-    #     key: "feature-limits",
-    #     value: '{"max_items": 10, "max_users": 5}',
-    #     value_type: "object"
+    #     key: "max-projects",
+    #     value: "5",
+    #     value_type: "integer",
+    #     targeting_rules: [
+    #       { "value" => "1000", "conditions" => { "type" => "AND", "conditions" => [{ "attribute" => "role", "operator" => "EQUALS", "value" => "admin" }] } },
+    #       { "value" => "100", "conditions" => { "type" => "AND", "conditions" => [{ "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@company.com" }] } },
+    #       { "value" => "25", "conditions" => { "type" => "AND", "conditions" => [{ "attribute" => "plan", "operator" => "EQUALS", "value" => "pro" }] } }
+    #     ]
     #   )
     #
     class Flag < ::ActiveRecord::Base
@@ -35,29 +55,98 @@ module Subflag
                       format: { with: /\A[a-z0-9\-]+\z/, message: "only lowercase letters, numbers, and dashes" }
       validates :value_type, inclusion: { in: VALUE_TYPES }
       validates :value, presence: true
+      validate :validate_targeting_rules
 
       scope :enabled, -> { where(enabled: true) }
 
-      # Get the flag value cast to its declared type
+      # Evaluate the flag for a given context
+      #
+      # Returns the matched rule's value if context matches targeting rules,
+      # otherwise returns the default value.
+      #
+      # @param context [Hash, nil] Evaluation context with user attributes
+      # @param expected_type [Symbol, String, nil] Override the value_type for casting
+      # @return [Object] The evaluated value, cast to the appropriate type
+      def evaluate(context: nil, expected_type: nil)
+        rules = parsed_targeting_rules
+        raw_value = if rules.present? && context.present?
+                      matched = TargetingEngine.evaluate(rules, context)
+                      matched || value
+                    else
+                      value
+                    end
+
+        cast_value(raw_value, expected_type)
+      end
+
+      # Get the flag's default value cast to its declared type (ignores targeting)
       #
       # @param expected_type [Symbol, String, nil] Override the value_type for casting
       # @return [Object] The typed value
       def typed_value(expected_type = nil)
+        cast_value(value, expected_type)
+      end
+
+      private
+
+      def cast_value(raw_value, expected_type = nil)
         type = expected_type&.to_s || value_type
 
         case type.to_s
         when "boolean"
-          ActiveModel::Type::Boolean.new.cast(value)
+          ActiveModel::Type::Boolean.new.cast(raw_value)
         when "string"
-          value.to_s
+          raw_value.to_s
         when "integer"
-          value.to_i
+          raw_value.to_i
         when "float", "number"
-          value.to_f
+          raw_value.to_f
         when "object"
-          value.is_a?(Hash) ? value : JSON.parse(value)
+          raw_value.is_a?(Hash) ? raw_value : JSON.parse(raw_value)
         else
-          value
+          raw_value
+        end
+      end
+
+      def parsed_targeting_rules
+        return nil if targeting_rules.blank?
+
+        case targeting_rules
+        when String
+          JSON.parse(targeting_rules)
+        when Array
+          targeting_rules
+        else
+          targeting_rules
+        end
+      end
+
+      def validate_targeting_rules
+        return if targeting_rules.blank?
+
+        rules = case targeting_rules
+                when Array then targeting_rules
+                when String
+                  begin
+                    JSON.parse(targeting_rules)
+                  rescue JSON::ParserError
+                    errors.add(:targeting_rules, "must be valid JSON")
+                    return
+                  end
+                else
+                  errors.add(:targeting_rules, "must be an array of rules")
+                  return
+                end
+
+        rules.each_with_index do |rule, index|
+          unless rule.is_a?(Hash)
+            errors.add(:targeting_rules, "rule #{index} must be a hash")
+            next
+          end
+
+          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")
         end
       end
     end

data/lib/subflag/rails/targeting.rb

@@ -0,0 +1,48 @@
+# frozen_string_literal: true
+
+require_relative "targeting_engine"
+
+module Subflag
+  module Rails
+    # Targeting module for evaluating rules that control who sees what flag values.
+    #
+    # Rules are stored as JSON in the database and evaluated at runtime.
+    # Use targeting to roll out features to internal teams before wider release.
+    #
+    # ## Rule Format
+    #
+    # Rules are an array of objects, each with a `value` and `conditions`:
+    #
+    #   [
+    #     {
+    #       "value" => "true",
+    #       "conditions" => {
+    #         "type" => "OR",
+    #         "conditions" => [
+    #           { "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@company.com" },
+    #           { "attribute" => "role", "operator" => "IN", "value" => ["admin", "qa"] }
+    #         ]
+    #       }
+    #     }
+    #   ]
+    #
+    # ## Supported Operators
+    #
+    # - EQUALS, NOT_EQUALS - exact match
+    # - IN, NOT_IN - list membership
+    # - CONTAINS, NOT_CONTAINS - substring match
+    # - STARTS_WITH, ENDS_WITH - prefix/suffix match
+    # - GREATER_THAN, LESS_THAN, GREATER_THAN_OR_EQUAL, LESS_THAN_OR_EQUAL - numeric
+    # - MATCHES - regex match
+    #
+    # ## Evaluation
+    #
+    # Rules are evaluated in order. First match wins.
+    # If no rules match, the flag's default value is returned.
+    #
+    # TODO: Add admin UI for managing targeting rules
+    #
+    module Targeting
+    end
+  end
+end

data/lib/subflag/rails/targeting_engine.rb

@@ -0,0 +1,191 @@
+# frozen_string_literal: true
+
+module Subflag
+  module Rails
+    # Evaluates targeting rules against evaluation contexts.
+    #
+    # Rules are arrays of { "value" => X, "conditions" => {...} } hashes.
+    # First matching rule wins. Falls back to flag's default value if nothing matches.
+    #
+    # @example Rule structure
+    #   [
+    #     {
+    #       "value" => "100",
+    #       "conditions" => {
+    #         "type" => "OR",
+    #         "conditions" => [
+    #           { "attribute" => "email", "operator" => "ENDS_WITH", "value" => "@company.com" },
+    #           { "attribute" => "role", "operator" => "IN", "value" => ["admin", "developer"] }
+    #         ]
+    #       }
+    #     }
+    #   ]
+    #
+    module TargetingEngine
+      OPERATORS = %w[
+        EQUALS NOT_EQUALS IN NOT_IN
+        CONTAINS NOT_CONTAINS STARTS_WITH ENDS_WITH
+        GREATER_THAN LESS_THAN GREATER_THAN_OR_EQUAL LESS_THAN_OR_EQUAL
+        MATCHES
+      ].freeze
+
+      class << self
+        # Evaluate targeting rules against a context
+        #
+        # @param rules [Array<Hash>, nil] Array of targeting rules with values
+        # @param context [Hash, nil] Evaluation context with attributes
+        # @return [String, nil] The matched rule's value, or nil if no match
+        def evaluate(rules, context)
+          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)
+
+          rules.each do |rule|
+            rule = rule.transform_keys(&:to_s)
+            conditions = rule["conditions"]
+            next unless conditions
+
+            if evaluate_rule(conditions, normalized_context)
+              return rule["value"]
+            end
+          end
+
+          nil # No rules matched
+        end
+
+        private
+
+        def normalize_context(context)
+          context.transform_keys(&:to_s).transform_values do |v|
+            v.is_a?(Symbol) ? v.to_s : v
+          end
+        end
+
+        # Evaluate an AND/OR rule block
+        def evaluate_rule(rule, context)
+          rule = rule.transform_keys(&:to_s)
+          type = rule["type"]&.upcase || "AND"
+          conditions = rule["conditions"] || []
+
+          case type
+          when "AND"
+            conditions.all? { |c| evaluate_condition(c, context) }
+          when "OR"
+            conditions.any? { |c| evaluate_condition(c, context) }
+          else
+            false
+          end
+        end
+
+        # Evaluate a single condition
+        def evaluate_condition(condition, context)
+          condition = condition.transform_keys(&:to_s)
+          attribute = condition["attribute"]
+          operator = condition["operator"]&.upcase
+          expected = condition["value"]
+
+          return false unless attribute && operator
+
+          actual = context[attribute]
+          return false if actual.nil?
+
+          case operator
+          when "EQUALS"
+            compare_equals(actual, expected)
+          when "NOT_EQUALS"
+            !compare_equals(actual, expected)
+          when "IN"
+            compare_in(actual, expected)
+          when "NOT_IN"
+            !compare_in(actual, expected)
+          when "CONTAINS"
+            compare_contains(actual, expected)
+          when "NOT_CONTAINS"
+            !compare_contains(actual, expected)
+          when "STARTS_WITH"
+            compare_starts_with(actual, expected)
+          when "ENDS_WITH"
+            compare_ends_with(actual, expected)
+          when "GREATER_THAN"
+            compare_numeric(actual, expected) { |a, e| a > e }
+          when "LESS_THAN"
+            compare_numeric(actual, expected) { |a, e| a < e }
+          when "GREATER_THAN_OR_EQUAL"
+            compare_numeric(actual, expected) { |a, e| a >= e }
+          when "LESS_THAN_OR_EQUAL"
+            compare_numeric(actual, expected) { |a, e| a <= e }
+          when "MATCHES"
+            compare_matches(actual, expected)
+          else
+            false
+          end
+        end
+
+        def compare_equals(actual, expected)
+          normalize_value(actual) == normalize_value(expected)
+        end
+
+        def compare_in(actual, expected)
+          return false unless expected.is_a?(Array)
+
+          normalized_actual = normalize_value(actual)
+          expected.any? { |e| normalize_value(e) == normalized_actual }
+        end
+
+        def compare_contains(actual, expected)
+          actual.to_s.include?(expected.to_s)
+        end
+
+        def compare_starts_with(actual, expected)
+          actual.to_s.start_with?(expected.to_s)
+        end
+
+        def compare_ends_with(actual, expected)
+          actual.to_s.end_with?(expected.to_s)
+        end
+
+        def compare_numeric(actual, expected)
+          a = to_number(actual)
+          e = to_number(expected)
+          return false if a.nil? || e.nil?
+
+          yield(a, e)
+        end
+
+        def compare_matches(actual, expected)
+          Regexp.new(expected.to_s).match?(actual.to_s)
+        rescue RegexpError
+          false
+        end
+
+        def normalize_value(value)
+          case value
+          when Symbol then value.to_s
+          when TrueClass then true
+          when FalseClass then false
+          when Numeric then value
+          else value.to_s
+          end
+        end
+
+        def to_number(value)
+          case value
+          when Numeric then value
+          when String
+            if value.include?(".")
+              Float(value)
+            else
+              Integer(value)
+            end
+          else
+            nil
+          end
+        rescue ArgumentError, TypeError
+          nil
+        end
+      end
+    end
+  end
+end

data/lib/subflag/rails/version.rb

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

data/lib/subflag/rails.rb

@@ -11,6 +11,7 @@ require_relative "rails/client"
 require_relative "rails/flag_accessor"
 require_relative "rails/helpers"
 require_relative "rails/railtie" if defined?(Rails::Railtie)
+require_relative "rails/engine" if defined?(Rails::Engine)
 
 # Test helpers are loaded separately: require "subflag/rails/test_helpers"
 
@@ -130,6 +131,7 @@ module Subflag
       end
 
       def build_active_record_provider
+        require_relative "rails/targeting"
         require_relative "rails/backends/active_record_provider"
         require_relative "rails/models/flag"
         Backends::ActiveRecordProvider.new

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: subflag-rails
 version: !ruby/object:Gem::Version
-  version: 0.4.0
+  version: 0.5.1
 platform: ruby
 authors:
 - Subflag
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-12-11 00:00:00.000000000 Z
+date: 2025-12-15 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: openfeature-sdk
@@ -170,7 +170,7 @@ dependencies:
     - - ">="
       - !ruby/object:Gem::Version
         version: '6.1'
-description: Feature flags for Rails with pluggable backends. Use Subflag Cloud (SaaS),
+description: Feature flags for Rails with selectable backends. Use Subflag Cloud (SaaS),
   ActiveRecord (self-hosted), or Memory (testing). Get typed values (boolean, string,
   integer, double, object) with the same API regardless of backend.
 email:
@@ -182,6 +182,14 @@ files:
 - CHANGELOG.md
 - LICENSE.txt
 - README.md
+- app/controllers/subflag/rails/application_controller.rb
+- app/controllers/subflag/rails/flags_controller.rb
+- app/views/layouts/subflag/rails/application.html.erb
+- app/views/subflag/rails/flags/_form.html.erb
+- app/views/subflag/rails/flags/edit.html.erb
+- app/views/subflag/rails/flags/index.html.erb
+- app/views/subflag/rails/flags/new.html.erb
+- config/routes.rb
 - lib/generators/subflag/install_generator.rb
 - lib/generators/subflag/templates/create_subflag_flags.rb.tt
 - lib/generators/subflag/templates/initializer.rb.tt
@@ -193,12 +201,15 @@ files:
 - lib/subflag/rails/client.rb
 - lib/subflag/rails/configuration.rb
 - lib/subflag/rails/context_builder.rb
+- lib/subflag/rails/engine.rb
 - lib/subflag/rails/evaluation_result.rb
 - lib/subflag/rails/flag_accessor.rb
 - lib/subflag/rails/helpers.rb
 - lib/subflag/rails/models/flag.rb
 - lib/subflag/rails/railtie.rb
 - lib/subflag/rails/request_cache.rb
+- lib/subflag/rails/targeting.rb
+- lib/subflag/rails/targeting_engine.rb
 - lib/subflag/rails/test_helpers.rb
 - lib/subflag/rails/version.rb
 homepage: https://subflag.com